build a span annotation, suitable for passing to update/3; see also convenience functions in Tapper.

build a span binary annotation, suitable for passing to update/3; see also convenience functions in Tapper.

Finishes the trace.

For async processes (where spans persist in another process), just 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.

id = Tapper.finish(id, async: true, annotations: [Tapper.http_status_code(401)])

See also

• Tapper.Tracer.Timeout - the time-out logic.

Options

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

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

Arguments

• id - Tapper id.

Options

• annotations (list) - a list of annotations to attach the the span.

id = finish_span(id, annotations: [Tapper.http_status_code(202)])

join an existing trace, e.g. server recieving an annotated request, returning a Tapper.Id for subsequent operations:

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 Tapper.name/1.

Arguments

• sampled 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 name of span, see also Tapper.name/1.
• annotations - a list of annotations to attach to main span, specified by Tapper.tag/3 etc.
• type - the type of the span, i.e.. :client, :server; defaults to :server; determines which of sr (:server) or cs (:client) annotations is added. Defaults to :server.
• 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 between operations, before automatically finishing it (useful for long-running async operations); milliseconds.

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 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.
• annotations - a list of annotations to attach to main span, specified by Tapper.tag/3 etc.
• type - the type of the span, i.e.. :client, :server; defaults to :client.
• remote - the remote Endpoint: automatically creates a “sa” (client) or “ca” (server) binary annotation on this span.
• ttl - how long this span should live before automatically finishing it (useful for long-running async operations); milliseconds.

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.

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

Arguments

• id - Tapper id.

Options

• name (string) - name of 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 = Tapper.start_span(id, name: "foo", local: "do foo", annotations: [Tapper.sql_query("select * from foo")])

Callback implementation for Tapper.Tracer.Api.update_span/3.