Tapper v0.6.2 Tapper View Source

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, # equivalent to Tapper.wire_receive/0
  Tapper.tag("someId", someId),
])
...

# end child span
id = Tapper.finish_span(child_id, annotations: Tapper.http_status_code(200))

Tapper.finish(span_id) # end trace

Annotations 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])
HelperKindValue/KeyShort-code(s)
server_receive/0eventsr:server_recv, :sr
server_send/0eventss:server_send, :ss
client_receive/0eventcr:client_recv, :cr
client_send/0eventcs:server_send, :cs
wire_send/0eventws:wire_send, :ws
wire_receive/0eventwr:wire_recv, :wr
error/0eventerror:error
async/0eventasyncN/A
annotation/2eventgiven valueN/A
client_address/1binarycaN/A
server_address/1binarysaN/A
http_host/1binaryhttp.hostN/A
http_method/1binaryhttp.methodN/A
http_path/1binaryhttp.pathN/A
http_url/1binaryhttp.urlN/A
http_status_code/1binaryhttp.status_codeN/A
http_request_size/1binaryhttp.request_sizeN/A
http_response_size/1binaryhttp.response_sizeN/A
sql_query/1binarysql.queryN/A
error_message/1binaryerrorN/A
tag/3binarygiven keyN/A
binary_annotation/4binarygiven keyN/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/1 does not add an annotation, it sets the name of the span.
  • async/0 adds an async event annotation, but also modifies the behaviour of Tapper to support asynchronous termination of spans. See Tapper.Tracer.Timeout for details.

Link to this section 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)

Callback implementation for Tapper.Tracer.Api.finish/2.

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)

Callback implementation for Tapper.Tracer.Api.start/1.

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

Link to this section Functions

Link to this function

annotation(value, endpoint \\ nil)

View Source

Specs

Annotation helper: create an event annotation, general interface.

Specs

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

Link to this function

binary_annotation(type, key, value, endpoint \\ nil)

View Source

Specs

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)
Link to this function

client_address(endpoint)

View Source

Specs

Annotation helper: tag the client's address (ca binary annotation).

Specs

client_receive() :: Tapper.Tracer.Api.annotation_delta()

Annotation helper: create a client_receive event (cr event annotation).

Specs

Annotation helper: create a client_send event (cs event annotation); see also :client option on Tapper.start/1.

Specs

Annotation helper: create an error event (error event annotation).

Specs

error_message(message :: any()) :: Tapper.Tracer.Api.binary_annotation_delta()

Annotation helper: tag with an error message (error binary annotation)

Specs

finish(tapper_id :: Tapper.Id.t(), opts :: Keyword.t()) :: :ok

Callback implementation for Tapper.Tracer.Api.finish/2.

Link to this function

finish_span(id, opts \\ [])

View Source

Specs

finish_span(tapper_id :: Tapper.Id.t(), opts :: Keyword.t()) :: Tapper.Id.t()

Callback implementation for Tapper.Tracer.Api.finish_span/2.

Specs

http_host(hostname :: String.t()) :: Tapper.Tracer.Api.binary_annotation_delta()

Annotation helper: tag with HTTP host information (http.host binary annotation).

Specs

http_method(method :: String.t() | atom()) ::
  Tapper.Tracer.Api.binary_annotation_delta()

Annotation helper: tag with HTTP method information (http.method binary annotation).

Specs

Annotation helper: tag with HTTP path information: should be without query parameters (http.path binary annotation)

Specs

http_request_size(size :: integer()) ::
  Tapper.Tracer.Api.binary_annotation_delta()

Annotation helper: tag with an HTTP request size (http.request.size binary annotation)

Link to this function

http_response_size(size)

View Source

Specs

http_response_size(size :: integer()) ::
  Tapper.Tracer.Api.binary_annotation_delta()

Annotation helper: tag with an HTTP reponse size (http.response.size binary annotation)

Specs

http_status_code(code :: integer()) ::
  Tapper.Tracer.Api.binary_annotation_delta()

Annotation helper: tag with an HTTP status code (http.status_code binary annotation)

Specs

Annotation helper: tag with full HTTP URL information (http.url binary annotation)

Link to this function

join(trace_id, span_id, parent_id, sample, debug, opts \\ [])

View Source

Specs

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

Callback implementation for Tapper.Tracer.Api.join/6.

Specs

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

Annotation helper: name (or rename) the current span.

Link to this function

server_address(endpoint)

View Source

Specs

Annotation helper: tag with the server's address (sa binary annotation).

Specs

server_receive() :: Tapper.Tracer.Api.annotation_delta()

Annotation helper: create a server_receive event (sr event annotation); see also :server option on Tapper.start/1.

Specs

Annotation helper: create a server_send event (ss event annotation).

Specs

Annotation helper: tag with a database query (sql.query binary annotation)

Specs

start(opts :: Keyword.t()) :: Tapper.Id.t()

Callback implementation for Tapper.Tracer.Api.start/1.

Link to this function

start_span(id, opts \\ [])

View Source

Specs

start_span(tapper_id :: Tapper.Id.t(), opts :: Keyword.t()) :: Tapper.Id.t()

Callback implementation for Tapper.Tracer.Api.start_span/2.

Link to this function

tag(key, value, endpoint \\ nil)

View Source

Specs

Annotation helper: tag with a general (key,value,host) binary annotation, determining type of annotation automatically

Link to this function

update_span(id, deltas, opts \\ [])

View Source

Specs

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

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

Specs

Annotation helper: create a receive event (wr event annotation).

Specs

Annotation helper: create a send event (ws event annotation).