instrument_tracer (instrument v0.6.1)

View Source

OpenTelemetry-compatible Tracer API.

This module provides a native span implementation with W3C TraceContext format support. Spans are stored in the process dictionary via the context system.

Example Usage

  instrument_tracer:with_span(<<"process_request">>, fun() ->
    instrument_tracer:set_attributes(#{<<"user.id">> => UserId}),
    Result = process(),
    instrument_tracer:set_status(ok),
    Result
  end).

Summary

Types

span/0
span_opts/0
tracer/0

Functions

add_event(Name)

Adds an event to the current span.

add_event(Name, Attrs)

Adds an event with attributes to the current span. Enforces span event count limit per OTel spec.

add_link(Span_ctx)

Adds a link to the current span.

current_span()

Gets the current span.

end_span()

Ends the current span.

end_span(Span)

Ends a specific span. The span parameter is used to identify which span to end via its span_id. The actual span data is retrieved from context to capture any modifications.

get_tracer(Name)

Gets or creates a Tracer with the given name.

get_tracer(Name, Opts)

Gets or creates a Tracer with the given name and options.

is_recording()

Checks if the current span is recording.

is_sampled()

Checks if the current span is sampled.

record_exception(Exception)

Records an exception on the current span.

record_exception(Exception, Attrs)

Records an exception with attributes on the current span.

register_exporter(Exporter)

Registers a span exporter. The exporter must be a function that takes a span record. Thread-safe: uses ETS for atomic operations.

set_attribute(Key, Value)

Sets a single attribute on the current span.

set_attributes(Attrs)

Sets multiple attributes on the current span. Enforces span attribute count limit per OTel spec.

set_status(_)

Sets the status of the current span to ok.

set_status(_, Description)

Sets the status of the current span with description.

span_ctx()

Gets the span context of the current span.

span_ctx(Span)

Gets the span context of a specific span.

span_id()

Gets the span ID of the current span.

span_id(Span)

Gets the span ID of a specific span.

start_span(Name)

Starts a new span with the given name.

start_span(Name, Opts)

Starts a new span with the given name and options.

trace_id()

Gets the trace ID of the current span.

trace_id(Span)

Gets the trace ID of a specific span.

unregister_exporter(Exporter)

Unregisters a span exporter. Thread-safe: uses ETS for atomic operations.

update_name(Name)

Updates the name of the current span.

with_span(Name, Fun)

Executes a function within a span.

with_span(Name, Opts, Fun)

Executes a function within a span with options.

Types

span/0

-type span() ::
          #span{name :: binary(),
                ctx ::
                    #span_ctx{trace_id :: <<_:128>> | undefined,
                              span_id :: <<_:64>> | undefined,
                              trace_flags :: 0 | 1,
                              trace_state :: [{binary(), binary()}],
                              is_remote :: boolean()},
                parent_ctx ::
                    #span_ctx{trace_id :: <<_:128>> | undefined,
                              span_id :: <<_:64>> | undefined,
                              trace_flags :: 0 | 1,
                              trace_state :: [{binary(), binary()}],
                              is_remote :: boolean()} |
                    undefined,
                tracer ::
                    #tracer{name :: binary(),
                            version :: binary() | undefined,
                            schema_url :: binary() | undefined,
                            resource ::
                                #resource{attributes :: map(), schema_url :: binary() | undefined} |
                                undefined} |
                    undefined,
                kind :: client | server | producer | consumer | internal,
                start_time :: integer(),
                end_time :: integer() | undefined,
                attributes :: map(),
                events :: [#span_event{name :: binary(), timestamp :: integer(), attributes :: map()}],
                links ::
                    [#span_link{ctx ::
                                    #span_ctx{trace_id :: <<_:128>> | undefined,
                                              span_id :: <<_:64>> | undefined,
                                              trace_flags :: 0 | 1,
                                              trace_state :: [{binary(), binary()}],
                                              is_remote :: boolean()},
                                attributes :: map()}],
                status :: unset | ok | {error, binary()},
                is_recording :: boolean(),
                dropped_attributes_count :: non_neg_integer(),
                dropped_events_count :: non_neg_integer(),
                dropped_links_count :: non_neg_integer()}.

span_opts/0

-type span_opts() ::
          #{kind => client | server | producer | consumer | internal,
            attributes => map(),
            links =>
                [#span_link{ctx ::
                                #span_ctx{trace_id :: <<_:128>> | undefined,
                                          span_id :: <<_:64>> | undefined,
                                          trace_flags :: 0 | 1,
                                          trace_state :: [{binary(), binary()}],
                                          is_remote :: boolean()},
                            attributes :: map()}],
            start_time => integer(),
            parent =>
                #span_ctx{trace_id :: <<_:128>> | undefined,
                          span_id :: <<_:64>> | undefined,
                          trace_flags :: 0 | 1,
                          trace_state :: [{binary(), binary()}],
                          is_remote :: boolean()} |
                undefined,
            span_id => binary(),
            tracer =>
                #tracer{name :: binary(),
                        version :: binary() | undefined,
                        schema_url :: binary() | undefined,
                        resource ::
                            #resource{attributes :: map(), schema_url :: binary() | undefined} |
                            undefined} |
                undefined}.

tracer/0

-type tracer() ::
          #tracer{name :: binary(),
                  version :: binary() | undefined,
                  schema_url :: binary() | undefined,
                  resource ::
                      #resource{attributes :: map(), schema_url :: binary() | undefined} | undefined}.

Functions

add_event(Name)

-spec add_event(binary()) -> ok.

Adds an event to the current span.

add_event(Name, Attrs)

-spec add_event(binary(), map()) -> ok.

Adds an event with attributes to the current span. Enforces span event count limit per OTel spec.

add_link(Span_ctx)

-spec add_link(#span_ctx{trace_id :: <<_:128>> | undefined,
                         span_id :: <<_:64>> | undefined,
                         trace_flags :: 0 | 1,
                         trace_state :: [{binary(), binary()}],
                         is_remote :: boolean()} |
               #{}) ->
                  ok.

Adds a link to the current span.

current_span()

-spec current_span() -> span() | undefined.

Gets the current span.

end_span()

-spec end_span() -> ok.

Ends the current span.

end_span(Span)

-spec end_span(span()) -> ok.

Ends a specific span. The span parameter is used to identify which span to end via its span_id. The actual span data is retrieved from context to capture any modifications.

get_tracer(Name)

-spec get_tracer(binary() | atom()) -> tracer().

Gets or creates a Tracer with the given name.

get_tracer(Name, Opts)

-spec get_tracer(binary() | atom(), map()) -> tracer().

Gets or creates a Tracer with the given name and options.

is_recording()

-spec is_recording() -> boolean().

Checks if the current span is recording.

is_sampled()

-spec is_sampled() -> boolean().

Checks if the current span is sampled.

record_exception(Exception)

-spec record_exception(term()) -> ok.

Records an exception on the current span.

record_exception(Exception, Attrs)

-spec record_exception(term(), map()) -> ok.

Records an exception with attributes on the current span.

register_exporter(Exporter)

-spec register_exporter(fun((span()) -> ok)) -> ok.

Registers a span exporter. The exporter must be a function that takes a span record. Thread-safe: uses ETS for atomic operations.

set_attribute(Key, Value)

-spec set_attribute(term(), term()) -> ok.

Sets a single attribute on the current span.

set_attributes(Attrs)

-spec set_attributes(map()) -> ok.

Sets multiple attributes on the current span. Enforces span attribute count limit per OTel spec.

set_status(_)

-spec set_status(ok | error) -> ok.

Sets the status of the current span to ok.

set_status(_, Description)

-spec set_status(ok | error, binary()) -> ok.

Sets the status of the current span with description.

span_ctx()

-spec span_ctx() ->
                  #span_ctx{trace_id :: <<_:128>> | undefined,
                            span_id :: <<_:64>> | undefined,
                            trace_flags :: 0 | 1,
                            trace_state :: [{binary(), binary()}],
                            is_remote :: boolean()} |
                  undefined.

Gets the span context of the current span.

span_ctx(Span)

-spec span_ctx(span()) ->
                  #span_ctx{trace_id :: <<_:128>> | undefined,
                            span_id :: <<_:64>> | undefined,
                            trace_flags :: 0 | 1,
                            trace_state :: [{binary(), binary()}],
                            is_remote :: boolean()}.

Gets the span context of a specific span.

span_id()

-spec span_id() -> binary() | undefined.

Gets the span ID of the current span.

span_id(Span)

-spec span_id(span()) -> binary().

Gets the span ID of a specific span.

start_span(Name)

-spec start_span(binary() | atom()) -> span().

Starts a new span with the given name.

start_span(Name, Opts)

-spec start_span(binary() | atom(), span_opts()) -> span().

Starts a new span with the given name and options.

trace_id()

-spec trace_id() -> binary() | undefined.

Gets the trace ID of the current span.

trace_id(Span)

-spec trace_id(span()) -> binary().

Gets the trace ID of a specific span.

unregister_exporter(Exporter)

-spec unregister_exporter(fun((span()) -> ok)) -> ok.

Unregisters a span exporter. Thread-safe: uses ETS for atomic operations.

update_name(Name)

-spec update_name(binary()) -> ok.

Updates the name of the current span.

with_span(Name, Fun)

-spec with_span(binary() | atom(), fun(() -> Result)) -> Result when Result :: term().

Executes a function within a span.

with_span(Name, Opts, Fun)

-spec with_span(binary() | atom(), span_opts(), fun(() -> Result)) -> Result when Result :: term().

Executes a function within a span with options.