Specs

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.

Specs

async() :: Tapper.Tracer.Api.async_delta()

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

• Tapper.Tracer.Timeout
• Tapper.finish/2

Specs

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)

Specs

client_address(endpoint :: Tapper.Endpoint.t()) ::
  Tapper.Tracer.Api.binary_annotation_delta()

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

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

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

Specs

context() :: Tapper.Id.t() | no_return()

Get the in-context Tapper.Id of this process.

If the context does not exist, and :tapper configuration option :debug_context is is :warn will log a warning with stack-trace, if otherwise truthy, will raise a RuntimeError, else will just return :ignore.

determine if there is a Tapper.Id in context

delete the in-context Tapper.Id

Specs

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

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(opts :: Keyword.t()) :: :ok

Finishes the trace, for the current contextual Tapper.Id, removing the id from the process context.

See Tapper.Tracer.finish/2 for options.

Specs

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

Finish a nested span of the current contextual Tapper.Id, returning an updated Tapper.Id, and updating the id in the context.

See Tapper.Tracer.finish_span/2 for options.

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

http_path(path :: String.t()) :: Tapper.Tracer.Api.binary_annotation_delta()

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)

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

http_url(url :: String.t()) :: Tapper.Tracer.Api.binary_annotation_delta()

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

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

Joins an existing trace, e.g. server recieving an annotated request.

A Tapper.Id is returned, and stored it in the process context.

id = Tapper.Ctx.join(trace_id, span_id, parent_id, sample, debug, name: "receive request")
^id = Tapper.Ctx.context()

See Tapper.Tracer.join/6 for options.

Specs

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

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

Specs

put_context(id :: Tapper.Id.t()) :: Tapper.Id.t()

Set the in-context Tapper.Id of this process.

Specs

server_address(endpoint :: Tapper.Endpoint.t()) ::
  Tapper.Tracer.Api.binary_annotation_delta()

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

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

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

Specs

sql_query(query :: String.t()) :: Tapper.Tracer.Api.binary_annotation_delta()

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

Specs

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

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

A new Tapper.Id is returned, and stored in the process context, see Tapper.Ctx.put_context/1.

id = Tapper.Ctx.start(name: "request resource", type: :client, remote: remote_endpoint)
^id = Tapper.Ctx.context()

See Tapper.Tracer.start/1 for options.

Specs

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

Starts a child span of the current span of the current contextual Tapper.Id, returning an updated Tapper.Id, and updating the id in the context.

See Tapper.Tracer.start_span/2 for options.

Specs

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

Specs

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

Add annotations to the current contextual span, returning the same Tapper.Id.

See Tapper.Tracer.update_span/3 for details.

Specs

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

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

Specs

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

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