Tapper v0.1.1 Tapper

Client API for Tapper.

Example

# start new trace (and span)
id = Tapper.start(name: "main", type: :client, debug: true, annotations: [Tapper.tag("a", "b")])

# or join an existing one
# id = Trapper.join(trace_id, span_id, parent_id, sample, debug, name: "main")

# start child span
id = Tapper.start_span(id, name: "call-out", annotations: [
  Tapper.wire_send(),
  Tapper.http_path("/resource/1234")
])

# do something
...

# tag current span with some additional metadata, e.g. when available
Tapper.update_span(id, [
  Tapper.tag("userId", 12)
])
...

# end child span
id = Tapper.finish_span(child_id, annotations: [
  Tapper.http_status(200)
])

Tapper.finish(span_id) # end trace

Summary

Functions

Annotation helper: mark an event (annotation), general interface

Annotation helper: marks the span as asynchronous, adding an async annotation

Annotation helper: tag with a general binary annotation

Annotation helper: Tag with the client’s address (ca binary annotation)

Annotation helper: mark a client_receive event (cr annotation)

Annotation helper: mark a client_send event (cs annotation); see also :client option on Tapper.start/1

Annotation helper: mark an error event (error annotation)

Annotation helper: Tag with an error message (error binary annotation)

Finishes the trace

Finish a nested child span, returning an updated Tapper.Id

Annotation helper: Tag with HTTP host information (http.host binary annotation)

Annotation helper: Tag with HTTP method information (http.method binary annotation)

Annotation helper: Tag with HTTP path information: should be without query parameters (http.path binary annotation)

Annotation helper: Tag with an HTTP request size (http.request.size binary annotation)

Annotation helper: Tag with an HTTP reponse size (http.response.size binary annotation)

Annotation helper: Tag with an HTTP status code (http.status_code binary annotation)

Annotation helper: Tag with full HTTP URL information (http.url binary annotation)

join an existing trace, e.g. server recieving an annotated request.

id = Tapper.Tracer.join(trace_id, span_id, parent_id, sampled, debug, name: "receive request")

NB Probably called by an integration (e.g. tapper_plug) with name, annotations etc. added in the service code, so the name is optional here, see name/1

Annotation helper: name (or rename) the current span

Annotation helper: Tag with the server’s address (sa binary annotation)

Annotation helper: mark a server_receive event (sr annotation); see also :server option on Tapper.start/1

Annotation helper: mark a server_send event (ss annotation)

Annotation helper: Tag with a database query (sql.query binary annotation)

start a new root trace, e.g. on originating a request, e.g

Starts a child span, returning an updated Tapper.Id

Annotation helper: Tag with a general (key,value,host) binary annotation, determining type of annotation automatically

Commit annotations to a span; returns the same Tapper.Id

Annotation helper: mark a receive event (wr annotation)

Annotation helper: mark a send event (ws annotation)

Functions

annotation(value, endpoint \\ nil)

Annotation helper: mark an event (annotation), general interface.

async()

Annotation helper: marks the span as asynchronous, adding an async annotation.

This is semantically equivalent to calling finish/2 with the async option, and has the same time-out behaviour, but annotates individual spans as being asynchronous. You can call this for every asynchronous span.

Ensure that child spans, and the whole trace, are finished as normal.

See also

binary_annotation(type, key, value, endpoint \\ nil)

Annotation helper: tag with a general binary annotation.

binary_annotation(id, :i16, "tab", 4)
client_address(endpoint)

Annotation helper: Tag with the client’s address (ca binary annotation).

client_receive()

Annotation helper: mark a client_receive event (cr annotation).

client_send()

Annotation helper: mark a client_send event (cs annotation); see also :client option on Tapper.start/1.

error()

Annotation helper: mark an error event (error annotation).

error_message(message)

Annotation helper: Tag with an error message (error binary annotation)

finish(id)

Finishes the trace.

For async processes (where spans persist in another process), call finish/2 when done with the main span, passing the async option, and finish child spans as normal using finish_span/2. When the trace times out, spans will be sent to the server, marking any unfinished spans with a timeout annotation.

Options

  • async - mark the trace as asynchronous, allowing child spans to finish within the TTL.
  • annotations (list) - a list of annotations to attach to the span.

See also

finish(id, opts)

See Tapper.Tracer.finish/2.

finish_span(id)

Finish a nested child span, returning an updated Tapper.Id.

Arguments

  • id - Tapper id.

Options

  • annotations (list) - a list of annotations to attach the the span.
id = Tapper.finish_span(id, annotations: [Tapper.http_status_code(202)])
finish_span(id, opts)

See Tapper.Tracer.finish_span/2.

http_host(hostname)

Annotation helper: Tag with HTTP host information (http.host binary annotation).

http_method(method)

Annotation helper: Tag with HTTP method information (http.method binary annotation).

http_path(path)

Annotation helper: Tag with HTTP path information: should be without query parameters (http.path binary annotation)

http_request_size(size)

Annotation helper: Tag with an HTTP request size (http.request.size binary annotation)

http_response_size(size)

Annotation helper: Tag with an HTTP reponse size (http.response.size binary annotation)

http_status_code(code)

Annotation helper: Tag with an HTTP status code (http.status_code binary annotation)

http_url(url)

Annotation helper: Tag with full HTTP URL information (http.url binary annotation)

join(trace_id, span_id, parent_id, sample, debug)

join an existing trace, e.g. server recieving an annotated request.

id = Tapper.Tracer.join(trace_id, span_id, parent_id, sampled, debug, name: "receive request")

NB Probably called by an integration (e.g. tapper_plug) with name, annotations etc. added in the service code, so the name is optional here, see name/1.

Arguments

  • trace_id - the trace id, as Tapper.TraceId.t.
  • span_id - the current span id, as Tapper.SpanId.t.
  • parent_span_id - the parent span id, as Tapper.SpanId.t or :root if root trace.
  • sample is the incoming sampling status; true implies trace has been sampled, and down-stream spans should be sampled also, false that it will not be sampled, and down-stream spans should not be sampled either.
  • debug is the debugging flag, if true this turns sampling for this trace on, regardless of the value of sampled.

Options

  • name (String) - name of span
  • type - the type of the span, i.e.. :client, :server; defaults to :server. See notes below.
  • annotations (list) - a list of annotations, specified by Tapper.tag/3 etc.
  • remote (Tapper.Endpoint) - the remote endpoint: automatically creates a “sa” (:client) or “ca” (:server) binary annotation on this span, see also Tapper.server_address/1.
  • ttl (integer) - how long this span should live between operations before automatically finishing it (useful for long-running async operations); milliseconds, defaults to 30,000 ms.
  • endpoint - sets the endpoint for the initial cr or sr annotation, defaults to one derived from Tapper configuration (see Tapper.Application.start/2).
  • reporter - override the configured reporter for this trace; useful for testing.

Notes

  • If neither sample nor debug are set, all operations on this trace become a no-op.
  • type determines the type of an automatically created sr (:server) or cs (:client) annotation, see also Tapper.client_send/0 and Tapper.server_receive/0.
join(trace_id, span_id, parent_id, sample, debug, opts)

See Tapper.Tracer.join/6.

name(name)

Annotation helper: name (or rename) the current span.

server_address(endpoint)

Annotation helper: Tag with the server’s address (sa binary annotation).

server_receive()

Annotation helper: mark a server_receive event (sr annotation); see also :server option on Tapper.start/1.

server_send()

Annotation helper: mark a server_send event (ss annotation).

sql_query(query)

Annotation helper: Tag with a database query (sql.query binary annotation)

start()

start a new root trace, e.g. on originating a request, e.g.:

id = Tapper.Tracer.start(name: "request resource", type: :client, remote: remote_endpoint)

Options

  • name - the name of the span.
  • sample - boolean, whether to sample this trace or not.
  • debug - boolean, enabled debug.
  • type - the type of the span, i.e.. :client, :server; defaults to :client. See notes below.
  • annotations (list) - a list of annotations, specified by Tapper.http_host/2 etc.
  • remote (%Tapper.Endpoint{}) - the remote Endpoint: automatically creates a “sa” (client) or “ca” (server) binary annotation on this span, see also Tapper.server_address/1.
  • ttl - how long this span should live before automatically finishing it (useful for long-running async operations); milliseconds (default 30,000 ms)
  • endpoint - sets the endpoint for the annotation created by type, defaults to one derived from Tapper configuration (see Tapper.Application.start/2).
  • reporter - override the configured reporter for this trace; useful for testing.

Notes

  • If neither sample nor debug are set, all operations on this trace become a no-op.
  • type determines the type of an automatically created sr (:server) or cs (:client) annotation, see also Tapper.client_send/0 and Tapper.server_receive/0.
start(opts)

See Tapper.Tracer.start/1.

start_span(id)

Starts a child span, returning an updated Tapper.Id.

Arguments

  • id - Tapper id.

Options

  • name (string) - name the span.
  • local (string) - provide a local span context name (via a lc binary annotation).
  • annotations (list) - a list of annotations to attach to the span.
id = start_span(id, name: "foo", local: "do foo", annotations: [Tapper.sql_query("select * from foo")])
start_span(id, opts)

See Tapper.Tracer.start_span/2.

tag(key, value, endpoint \\ nil)

Annotation helper: Tag with a general (key,value,host) binary annotation, determining type of annotation automatically

update_span(id, deltas)

Commit annotations to a span; returns the same Tapper.Id.

Use with annotation helper functions:

id = Tapper.start_span(id)

Tapper.update_span(id, [
  Tapper.async(),
  Tapper.name("child"),
  Tapper.http_path("/server/x"),
  Tapper.tag("x", 101)
])
update_span(id, deltas, opts)

See Tapper.Tracer.update_span/3.

wire_receive()

Annotation helper: mark a receive event (wr annotation).

wire_send()

Annotation helper: mark a send event (ws annotation).