Module passage

API for operating active spans.

Copyright © 2017 Takeru Ohta <phjgt308@gmail.com>

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_root_span(example_root, 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()}

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.

See also: Standard log fields (OpenTracing API)

log_option()

log_option() = {time, erlang:timestamp()}

------------------------------------------------------------------------------ Exported Functions ------------------------------------------------------------------------------

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(), maybe_span()}

Span reference.

See also: References between Spans (The OpenTracing Semantic Specification)

ref_type()

ref_type() = child_of | follows_from

Span reference type.

refs()

refs() = [ref()]

Span references.

start_root_span_option()

start_root_span_option() = {time, erlang:timestamp()} | {tags, tags()}

start_root_span_options()

start_root_span_options() = [start_root_span_option()]

Options for start_root_span/3.

start_span_option()

start_span_option() = {refs, refs()} | start_root_span_option()

start_span_options()

start_span_options() = [start_span_option()]

Options for start_span/3.

tag_name()

tag_name() = atom()

Tag name.

tag_value()

tag_value() = term()

Tag value.

tags()

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

Span tags.

See also: Standard span tags (OpenTracing API)

tracer_id()

tracer_id() = atom()

Tracer identifier.

Function Index

error_log/2Equivalent to error_log(Span, Message, []).
error_log/3Equivalent to error_log(Span, Format, Data, #{}).
error_log/4Equivalent to error_log(Span, Format, Data, Fields, []).
error_log/5Logs error message to Span.
extract_span/4Extracts a span from Carrier.
finish_span/1Equivalent to finish_span(Span, []).
finish_span/2Finishes the span.
get_baggage_items/1Returns the baggage items carried by Span.
inject_span/4Injects Span into Carrier.
log/2Equivalent to log(Span, Fields, []).
log/3Logs the Fields to Span.
set_baggage_items/2Sets the baggage items of Span to Items.
set_operation_name/2Sets the operation name of Span to Name.
set_tags/2Sets the tags of Span to Tags.
start_root_span/2Equivalent to start_root_span(OperationName, Tracer, []).
start_root_span/3Starts a root span.
start_span/2Equivalent to start_span(OperationName, PrimaryReference, []).
start_span/3Starts a span.

Function Details

error_log/2

error_log(Span::maybe_span(), Message::iodata()) -> maybe_span()

Equivalent to error_log(Span, Message, []).

error_log/3

error_log(Span::maybe_span(), Format::io:format(), Data::[term()]) -> maybe_span()

Equivalent to error_log(Span, Format, Data, #{}).

error_log/4

error_log(Span::maybe_span(), Format::io:format(), Data::[term()], Fields::log_fields()) -> maybe_span()

Equivalent to error_log(Span, Format, Data, Fields, []).

error_log/5

error_log(Span0::maybe_span(), Format::io:format(), Data::[term()], Fields::log_fields(), Options::log_options()) -> maybe_span()

Logs error message to Span.

This function logs Fields` and `#{event => error, message => io_lib:format(Format, Data)}.

In addition, it sets the tag #{error => true} automatically.

extract_span/4

extract_span(Tracer, Format, IterateFun, Carrier) -> maybe_span()

Extracts a span from Carrier.

If Carrier has no span context, this function will return undefined.

finish_span/1

finish_span(Span::maybe_span()) -> ok

Equivalent to finish_span(Span, []).

finish_span/2

finish_span(Span::maybe_span(), Options::finish_span_options()) -> ok

Finishes the span.

The finished span will be sent an external observer via the reporter associated with the tracer of the span.

Note that if you call this function on the same span more than once, duplicate reports will be sent.

get_baggage_items/1

get_baggage_items(Span::maybe_span()) -> baggage_items()

Returns the baggage items carried by Span.

inject_span/4

inject_span(Span, Format, InjectFun, Carrier) -> Carrier

Injects Span into Carrier.

log/2

log(Span::maybe_span(), Fields::log_fields()) -> maybe_span()

Equivalent to log(Span, Fields, []).

log/3

log(Span::maybe_span(), Fields::log_fields(), Options::log_options()) -> maybe_span()

Logs the Fields to Span.

set_baggage_items/2

set_baggage_items(Span::maybe_span(), Items::baggage_items()) -> maybe_span()

Sets the baggage items of Span to Items.

Note that the existing items which have different keys with Items are preserved.

See also: Set a baggage item (The OpenTracing Semantic Specification)

set_operation_name/2

set_operation_name(Span::maybe_span(), Name::operation_name()) -> maybe_span()

Sets the operation name of Span to Name.

set_tags/2

set_tags(Span::maybe_span(), Tags::tags()) -> maybe_span()

Sets the tags of Span to Tags.

Note that the existing tags which have different keys with Tags are preserved.

start_root_span/2

start_root_span(OperationName::operation_name(), Tracer::tracer_id()) -> maybe_span()

Equivalent to start_root_span(OperationName, Tracer, []).

start_root_span/3

start_root_span(OperationName::operation_name(), Tracer::tracer_id(), Options::start_root_span_options()) -> maybe_span()

Starts a root span.

If the sampler associated with Tracer does not sample the span, this function will return undefined.

start_span/2

start_span(OperationName::operation_name(), PrimaryReference::ref()) -> maybe_span()

Equivalent to start_span(OperationName, PrimaryReference, []).

start_span/3

start_span(OperationName::operation_name(), PrimaryReference::ref(), Options::start_span_options()) -> maybe_span()

Starts a span.

If there is no sampled span references, this function will return undefined.


Generated by EDoc, Oct 23 2017, 04:34:59.