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
Callback implementation for Tapper.Tracer.Api.update_span/3
Functions
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 update/3
; see also convenience functions in Tapper
.
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_annotaton_delta
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, iftrue
this turns sampling for this trace on, regardless of the value ofsampled
.
Options
name
name of span, see alsoTapper.name/1
.annotations
- a list of annotations to attach to main span, specified byTapper.tag/3
etc.type
- the type of the span, i.e..:client
,:server
; defaults to:server
; determines which ofsr
(:server
) orcs
(: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 alsoTapper.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
nordebug
are set, all operations on this trace become a no-op. type
determines the type of an automatically createdsr
(:server
) orcs
(:client
) annotation, see alsoTapper.client_send/0
andTapper.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 byTapper.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
nordebug
are set, all operations on this trace become a no-op. type
determines the type of an automatically createdsr
(:server
) orcs
(:client
) annotation, see alsoTapper.client_send/0
andTapper.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 alc
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 :: Tapper.Id.t, deltas :: [Tapper.Tracer.Api.delta], opts :: Keyword.t) :: Tapper.Id.t
Callback implementation for Tapper.Tracer.Api.update_span/3
.