Tapper v0.1.1 Tapper.Tracer

Low-level client API, interfaces between a Tapper client and a Tapper.Tracer.Server.

See also

  • Tapper - high-level client API.

Summary

Functions

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

Finish a nested span, returning an updated Tapper.Id

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

Some aliases for annotation type

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

Starts a child span, returning an updated Tapper.Id

Functions

annotation_delta(value, endpoint \\ nil)

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

async_delta()
binary_annotation_delta(type, key, value, endpoint \\ nil)

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

check_endpoint(arg1)
finish(id, opts \\ [])

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

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_span(id, opts \\ [])

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(arg, opts \\ [])
join(trace_id, span_id, parent_id, sample, debug, opts \\ [])

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.
map_annotation_type(type)

Some aliases for annotation type

name_delta(name)
name_delta(name :: String.t | atom) :: Tapper.Tracer.Api.name_delta
start(opts \\ [])

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.
start_span(id, opts \\ [])

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")])
update_span(id, deltas, opts \\ [])
update_span(id :: Tapper.Id.t, deltas :: [Tapper.Tracer.Api.delta], opts :: Keyword.t) :: Tapper.Id.t

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

whereis(trace_id)