Specs

annotation_delta(
  value :: Tapper.Tracer.Api.annotation_value(),
  endpoint :: Tapper.Tracer.Api.maybe_endpoint()
) :: Tapper.Tracer.Api.annotation_delta()

build a span annotation, suitable for passing to annotations option or update_span/3; see also convenience functions in Tapper.

Specs

async_delta() :: Tapper.Tracer.Api.async_delta()

build an async action, suitable for passing to annotations option or update_span/3; see also Tapper.async/0.

Specs

binary_annotation_delta(
  type :: Tapper.Tracer.Api.binary_annotation_type(),
  key :: Tapper.Tracer.Api.binary_annotation_key(),
  value :: Tapper.Tracer.Api.binary_annotation_value(),
  endpoint :: Tapper.Tracer.Api.maybe_endpoint()
) :: Tapper.Tracer.Api.binary_annotation_delta()

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

Finishes the trace, returns :ok.

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)])

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.

See also

• Tapper.Tracer.Timeout - timeout behaviour.
• Tapper.async/0 annotation.

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

Arguments

• id - Tapper id.

Options

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

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

Specs

join({binary(), binary(), :root | binary(), boolean(), boolean()}, keyword()) ::
  Tapper.Id.t()

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

id = Tapper.join(trace_id, span_id, parent_id, sample, 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

• trace_id - the incoming trace id.
• span_id - the incoming span id.
• parent_span_id - the incoming parent span id, or :root if none.
• 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, see also Tapper.name/1.
• annotations (list, atom or tuple) - a single annotation or list of annotations, 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.
• endpoint - sets the endpoint for the initial cr or sr annotation, defaults to one derived from Tapper configuration (see Tapper.Application.start/2).
• 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.
• reporter (module atom or function) - 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.

Provides some aliases for event annotation types:

Specs

name_delta(name :: String.t() | atom()) :: Tapper.Tracer.Api.name_delta()

build an name-span action, suitable for passing to annotations option or update_span/3; see also Tapper.name/1.

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

id = Tapper.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) - the debugging flag, if true this turns sampling for this trace on, regardless of the value of sample.
• annotations (list, atom or tuple) - a single annotation or list of annotations, specified by Tapper.tag/3 etc.
• type (:client | :server) - the type of the span; defaults to :client ¹.
• remote - the remote Tapper.Endpoint: 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.
• reporter (module atom or function) - override the configured reporter for this trace; useful for testing.

¹ determines the type of an automatically created sr (type :server) or cs (type :client) annotation, see also Tapper.client_send/0 and Tapper.server_receive/0.

Notes

• If neither sample nor debug are set, all operations on this trace become a no-op.

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

Arguments

• id - Tapper id.
• options - see below.

Options

• name (string) - name of span.
• local (string) - provide a local span context name (via a lc binary annotation).
• annotations (list, atom or tuple) - 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")])

Specs

update_span(
  id :: Tapper.Id.t(),
  deltas :: Tapper.Tracer.Api.delta() | [Tapper.Tracer.Api.delta()],
  opts :: Keyword.t()
) :: Tapper.Id.t()

Add annotations to the current span; returns the same Tapper.Id.

Arguments

• id - Tapper id.
• deltas - list, or single annotation tuple/atom. See helper functions.
• opts - keyword list of options.

Options

• timestamp - an alternative timestamp for these annotations, e.g. from Tapper.Timestamp.instant/0.

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)
])