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 helper: mark an event (annotation), general interface.
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
Annotation helper: tag with a general binary annotation.
binary_annotation(id, :i16, "tab", 4)
Annotation helper: mark a client_send event (cs
annotation); see also :client
option on Tapper.start/1
.
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
Tapper.Tracer.Timeout
- timeout behaviour.async/0
annotation.
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)])
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)
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, asTapper.TraceId.t
.span_id
- the current span id, asTapper.SpanId.t
.parent_span_id
- the parent span id, asTapper.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, iftrue
this turns sampling for this trace on, regardless of the value ofsampled
.
Options
name
(String) - name of spantype
- the type of the span, i.e..:client
,:server
; defaults to:server
. See notes below.annotations
(list) - a list of annotations, specified byTapper.tag/3
etc.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
(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 initialcr
orsr
annotation, defaults to one derived from Tapper configuration (seeTapper.Application.start/2
).reporter
- override the configured reporter for this trace; useful for testing.
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
.
See Tapper.Tracer.join/6
.
Annotation helper: mark a server_receive event (sr
annotation); see also :server
option on Tapper.start/1
.
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 byTapper.http_host/2
etc.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 before automatically finishing it (useful for long-running async operations); milliseconds (default 30,000 ms)endpoint
- sets the endpoint for the annotation created bytype
, defaults to one derived from Tapper configuration (seeTapper.Application.start/2
).reporter
- override the configured reporter for this trace; useful for testing.
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 the 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 = start_span(id, name: "foo", local: "do foo", annotations: [Tapper.sql_query("select * from foo")])
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
.
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)
])