Tapper v0.2.0 Tapper
The high-level 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, [
:wire_recv,
Tapper.tag("userId", userId),
])
...
# end child span
id = Tapper.finish_span(child_id, annotations: Tapper.http_status(200))
Tapper.finish(span_id) # end traceAnnotations and Updates
Annotations are either binary annotations, which have a type, key and value, and an optional endpoint,
or event annotations which have a key-like value, and an optional endpoint. Only event annotations have
an associated timestamp (normally automatically generated by the API, or alternatively supplied to update_span/3).
The helper functions in this module produce either a binary annotation or an event annotation, and can be
passed through the annotations option on any of start/1, join/6, start_span/2, finish_span/2
and finish/2, or as the second parameter of update_span/3. Note that for convenience, all these functions
accept either a list of annotations, or a single annotation.
For event annotations, instead of using the helper function, you can pass an atom, which results in an event annotation, with the default endpoint. i.e. the following are all equivalent in terms of the annotations they produce (but not, of course in other ways):
Tapper.start_span(id, annotations: [Tapper.server_receive()])
Tapper.start_span(id, annotations: Tapper.server_receive())
Tapper.start_span(id, annotations: [:sr])
Tapper.start_span(id, annotations: :sr)
Tapper.update_span(id, [Tapper.server_receive()])
Tapper.update_span(id, Tapper.server_receive())
Tapper.update_span(id, :sr)
Tapper.update_span(id, [:sr])| Helper | Kind | Value/Key | Short-code(s) |
|---|---|---|---|
server_receive/0 | event | sr | :sr, :server_recv |
server_send/0 | event | ss | :ss, :server_send |
client_receive/0 | event | cr | :cr, :client_recv |
client_send/0 | event | cs | :cs, :server_send |
wire_send/0 | event | ws | :ws, :wire_send |
wire_receive/0 | event | wr | :wr, :wire_recv |
error/0 | event | error | :error |
async/0 | event | async | N/A |
annotation/2 | event | given value | N/A |
client_address/1 | binary | ca | N/A |
server_address/1 | binary | sa | N/A |
http_host/1 | binary | http.host | N/A |
http_method/1 | binary | http.method | N/A |
http_path/1 | binary | http.path | N/A |
http_url/1 | binary | http.url | N/A |
http_status_code/1 | binary | http.status_code | N/A |
http_request_size/1 | binary | http.request_size | N/A |
http_response_size/1 | binary | http.response_size | N/A |
sql_query/1 | binary | sql.query | N/A |
error_message/1 | binary | error | N/A |
tag/3 | binary | given key | N/A |
binary_annotation/4 | binary | given key | N/A |
The general functions, annotation/2 and binary_annotation/4 can be used to create any other type
of annotation, and also allow a Tapper.Endpoint struct to be specified.
Other update types with special meanings
name/1does not add an annotation, it sets the name of the span.async/0adds anasyncevent annotation, but also modifies the behaviour of Tapper to support asynchronous termination of spans. SeeTapper.Tracer.Timeoutfor details.
Summary
Functions
Annotation helper: create an event annotation, general interface
Annotation helper: mark the span as asynchronous, and add an async event annotation
Annotation helper: create a general binary annotation
Annotation helper: tag the client’s address (ca binary annotation)
Annotation helper: create a client_receive event (cr event annotation)
Annotation helper: create a client_send event (cs event annotation); see also :client option on Tapper.start/1
Annotation helper: create an error event (error event annotation)
Annotation helper: tag with an error message (error binary annotation)
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)
Annotation helper: name (or rename) the current span
Annotation helper: tag with the server’s address (sa binary annotation)
Annotation helper: create a server_receive event (sr event annotation); see also :server option on Tapper.start/1
Annotation helper: create a server_send event (ss event annotation)
Annotation helper: tag with a database query (sql.query binary annotation)
Annotation helper: tag with a general (key,value,host) binary annotation, determining type of annotation automatically
Annotation helper: create a receive event (wr event annotation)
Annotation helper: create a send event (ws event annotation)
Functions
annotation(value :: Tapper.Tracer.Api.annotation_value, endpoint :: Tapper.Tracer.Api.maybe_endpoint) :: Tapper.Tracer.Api.annotation_delta
Annotation helper: create an event annotation, general interface.
Annotation helper: mark the span as asynchronous, and add an async event annotation.
Adding this annotation is semantically equivalent to calling finish/2 with the async option, and
instigates the same time-out behaviour.
You would probably add one of these to every asynchronous span, so we know which spans were async.
Ensure that child spans, and the whole trace, are finished as normal.
Example
# start a trace
id = Tapper.start(name: "main")
# spawn a task
ref = Task.start(fn ->
# start a child span in the task
child_id = Tapper.start_span(id, "fetch", annotations: Tapper.async())
res = do_something()
{res, child_id}
end)
# finish the trace, this won't send the spans; note we don't need async: true
# if Task has already called start_span(), but it might not have, so safer to do so!
Tapper.finish(id, async: true)
...
# await the result from our task
{res, span_id} = Task.await(ref)
send_result_to_queue_or_something(res)
# finish the child span; will complete trace and send spans
Tapper.finish_span(span_id)See also
binary_annotation(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
Annotation helper: create a general binary annotation.
type is one of: :string, :bool, :i16, :i32, :i64, :double, :bytes
Example
binary_annotation(id, :i16, "tab", 4)client_address(endpoint :: Tapper.Endpoint.t) :: Tapper.Tracer.Api.binary_annotation_delta
Annotation helper: tag the client’s address (ca binary annotation).
Annotation helper: create a client_receive event (cr event annotation).
Annotation helper: create a client_send event (cs event annotation); see also :client option on Tapper.start/1.
Annotation helper: create an error event (error event annotation).
error_message(message :: String.t) :: Tapper.Tracer.Api.binary_annotation_delta
Annotation helper: tag with an error message (error binary annotation)
Annotation helper: tag with HTTP host information (http.host binary annotation).
http_method(method :: String.t | atom) :: Tapper.Tracer.Api.binary_annotation_delta
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)
http_request_size(size :: integer) :: Tapper.Tracer.Api.binary_annotation_delta
Annotation helper: tag with an HTTP request size (http.request.size binary annotation)
http_response_size(size :: integer) :: Tapper.Tracer.Api.binary_annotation_delta
Annotation helper: tag with an HTTP reponse size (http.response.size binary annotation)
http_status_code(code :: integer) :: Tapper.Tracer.Api.binary_annotation_delta
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)
See Tapper.Tracer.join/5.
join(trace_id :: Tapper.TraceId.t, span_id :: Tapper.SpanId.t, parent_id :: Tapper.SpanId.t | :root, sample :: boolean, debug :: boolean, opts :: Keyword.t) :: Tapper.Id.t
See Tapper.Tracer.join/6.
Annotation helper: name (or rename) the current span.
server_address(endpoint :: Tapper.Endpoint.t) :: Tapper.Tracer.Api.binary_annotation_delta
Annotation helper: tag with the server’s address (sa binary annotation).
Annotation helper: create a server_receive event (sr event annotation); see also :server option on Tapper.start/1.
Annotation helper: create a server_send event (ss event annotation).
Annotation helper: tag with a database query (sql.query binary annotation)
tag(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
Annotation helper: tag with a general (key,value,host) binary annotation, determining type of annotation automatically
update_span(tapper_id :: Tapper.Id.t, deltas :: Tapper.Tracer.Api.delta | [Tapper.Tracer.Api.delta], opts :: Keyword.t) :: Tapper.Id.t
Annotation helper: create a receive event (wr event annotation).
Annotation helper: create a send event (ws event annotation).