Module passage

Description
Data Types
Function Index
Function Details

API for operating active spans.

Description

API for operating active spans.

Most of the functions and types provided in this module are based on the OpenTracing API.

Examples

  %% Registers `tracer'
  Context = passage_span_context_null,
  Sampler = passage_sampler_all:new(),
  Reporter = passage_reporter_process:new(self(), span),
  ok = passage_tracer_registry:register(tracer, Context, Sampler, Reporter),
 
  %% Starts a root span
  RootSpan = passage:start_span(example_root, [{tracer, tracer}]),
 
  %% Starts a child span
  ChildSpan = passage:start_span(example_child, [{child_of, RootSpan}]),
 
  %% Finishes spans
  passage:finish_span(ChildSpan),
  passage:finish_span(RootSpan),
 
  %% Receives the finished spans
  receive {span, FinishedChildSpan} -> ok end,
  receive {span, FinishedRootSpan} -> ok end.

Data Types

baggage_item_name()

baggage_item_name() = binary()

Baggage item name.

baggage_item_value()

baggage_item_value() = binary()

Baggage item value.

baggage_items()

baggage_items() = #{baggage_item_name() => baggage_item_value()}

Baggage items.

Baggage items are just key/value pairs that cross OS process boundaries.

finish_span_option()

finish_span_option() = {time, erlang:timestamp()} | {lifetime, pid()}

time: Finish timestamp of the span. The default value is erlang:timestamp().
lifetime: If this option is specified, the report of the finished span will be delayed until the lifetime process exits.

finish_span_options()

finish_span_options() = [finish_span_option()]

Options for finish_span/2.

log_field_name()

log_field_name() = atom()

Log field name.

log_field_value()

log_field_value() = term()

Log field value.

log_fields()

log_fields() = #{log_field_name() => log_field_value()}

Span log fields.

log_option()

log_option() = {time, erlang:timestamp()} | error | {error, boolean()}

time: Timestamp of the log. The default value is erlang:timestamp().
error: If this option presents, the log will be treated as an error log. That is the event field with the value error will be added automatically. In addition, the tag #{error => true} will be set to the calling span.

log_options()

log_options() = [log_option()]

Options for log/3.

maybe_span()

maybe_span() = passage_span:span() | undefined

Sampled or unsampled span.

undefined means the span is unsampled.

operation_name()

operation_name() = atom()

Operation name.

ref()

ref() = {ref_type(), passage_span:span()}

Span reference.

Note that the values of tags, references and logs of a reference are set to empty when the associated span is created.

ref_type()

ref_type() = child_of | follows_from

Span reference type.

refs()

refs() = [ref()]

Span references.

start_span_option()

start_span_option() = {tracer, tracer_id()} | {tags, tags()} | {ref_type(), maybe_span()} | {time, erlang:timestamp()}

tracer: The tracer used for tracing the span. If this option is omitted, the span will never be a root span. If the span has any valid references, this option will be ignored.
time: Start timestamp of the span. The default value is erlang:timestamp().
tags: Tags associated to the span. The default value is #{}.
child_of|follows_from: Specifies a references related to the span. This option can be presented more than once.

start_span_options()

start_span_options() = [start_span_option()]

Options for start_span/2.

tag_name()

tag_name() = atom()

Tag name.

tag_value()

tag_value() = term()

Tag value.

tags()

tags() = #{tag_name() => tag_value()}

Span tags.

tracer_id()

tracer_id() = atom()

Tracer identifier.

Function Index

extract_span/4	Extracts a span from `Carrier`.
finish_span/1	Equivalent to `finish_span(Span, [])`.
finish_span/2	Finishes the span.
get_baggage_items/1	Returns the baggage items carried by `Span`.
inject_span/4	Injects `Span` into `Carrier`.
log/2	Equivalent to `log(Span, Fields, [])`.
log/3	Logs the `Fields` to `Span`.
set_baggage_items/2	Sets the baggage items of `Span` to `Items`.
set_operation_name/2	Sets the operation name of `Span` to `Name`.
set_tags/2	Sets the tags of `Span` to `Tags`.
set_tracer/2	Sets the tracer of `Span` to `Tracer`.
start_span/1	Equivalent to `start_span(OperationName, [])`.
start_span/2	Starts a span.
strip_span/1	Strips the tags, logs and references from the given span.