View Source opentelemetry (opentelemetry_api v1.3.1)

The types defined here, and referencing records in opentelemetry.hrl are used to store trace information while being collected on the Erlang node.

Thus, while the types are based on protos found in the opentelemetry-proto repo: src/opentelemetry/proto/trace/v1/trace.proto, they are not exact translations because further processing is done after the span has finished and can be vendor specific. For example, there is no count of the number of dropped attributes in the span record. And an attribute's value can be a function to only evaluate the value if it is actually used (at the time of exporting). And the stacktrace is a regular Erlang stack trace.

Summary

Functions

Convert a native monotonic timestamp to POSIX time of any erlang:time_unit(). Meaning the time since Epoch. Epoch is defined to be 00:00:00 UTC, 1970-01-01.

Creates a Span event with the given Name and Attributes.

Creates a list of Span events from the given List.

Returns the default global tracer.

Returns the tracer for the given name.

Creates a Span link to the Span represented by the given SpanCtx.

Creates a Span link to the Span represented by the given TraceId and SpanId.

Creates a list of Span links from the given List.

Create a Span status from the given Code.

Create a Span status from the given Code and with the given Message.

A monotonically increasing time provided by the Erlang runtime system in the native time unit. This value is the most accurate and precise timestamp available from the Erlang runtime and should be used for finding durations or any timestamp that can be converted to a system time before being sent to another system.

Convert a native monotonic timestamp to nanosecond POSIX time. Meaning the time since Epoch. Epoch is defined to be 00:00:00 UTC, 1970-01-01.

Types

-type attribute() :: {attribute_key(), attribute_value()}.
-type attribute_key() :: unicode:unicode_binary() | atom().
-type attribute_value() ::
    unicode:unicode_binary() |
    atom() |
    number() |
    boolean() |
    [unicode:unicode_binary() | atom() | float() | integer() | boolean()] |
    tuple().
-type attributes_map() :: #{attribute_key() => attribute_value()} | [attribute()].
-type event() ::
    #{system_time_native => integer(), name := event_name(), attributes := attributes_map()}.
-type event_name() :: unicode:unicode_binary() | atom().
-type hex_span_id() :: binary().
-type hex_trace_id() :: binary().
Link to this type

instrumentation_scope/0

View Source
-type instrumentation_scope() ::
    #instrumentation_scope{name :: unicode:unicode_binary() | undefined | '_',
                           version :: unicode:unicode_binary() | undefined | '_',
                           schema_url :: uri_string:uri_string() | undefined | '_'}.
-type link() ::
    #{trace_id := trace_id(),
      span_id := span_id(),
      attributes := attributes_map(),
      tracestate := otel_tracestate:t()}.
-type resource() :: #{unicode:unicode_binary() => unicode:unicode_binary()}.
-type span() :: term().
-type span_ctx() ::
    #span_ctx{trace_id :: opentelemetry:trace_id(),
              span_id :: opentelemetry:span_id(),
              trace_flags :: integer(),
              tracestate :: otel_tracestate:t(),
              is_valid :: boolean() | undefined,
              is_remote :: boolean(),
              is_recording :: boolean() | undefined,
              span_sdk :: {module(), term()} | undefined}.
-type span_id() :: non_neg_integer().
-type span_kind() :: internal | server | client | producer | consumer.
-type span_name() :: unicode:unicode_binary() | atom().
-type status() :: #status{code :: opentelemetry:status_code(), message :: unicode:unicode_binary()}.
-type status_code() :: unset | ok | error.
-type text_map() :: [{unicode:unicode_binary(), unicode:unicode_binary()}].
-type timestamp() :: integer().
-type trace_flags() :: non_neg_integer().
-type trace_id() :: non_neg_integer().
-type tracer() :: {module(), term()}.
-type tracestate() :: otel_tracestate:t().

Functions

Link to this function

convert_timestamp(Timestamp, Unit)

View Source
-spec convert_timestamp(timestamp(), erlang:time_unit()) -> integer().

Convert a native monotonic timestamp to POSIX time of any erlang:time_unit(). Meaning the time since Epoch. Epoch is defined to be 00:00:00 UTC, 1970-01-01.

Link to this function

create_application_tracers(Applications)

View Source
-spec create_application_tracers([{Application, Description, Vsn}]) -> ok
                              when Application :: atom(), Description :: string(), Vsn :: string().
-spec event(Name, Attributes) -> event() | undefined
         when Name :: event_name(), Attributes :: attributes_map().

Equivalent to event(opentelemetry:timestamp(), Name, Attributes).

Link to this function

event(Timestamp, Name, Attributes)

View Source
-spec event(Timestamp, Name, Attributes) -> event() | undefined
         when Timestamp :: integer(), Name :: event_name(), Attributes :: attributes_map().

Creates a Span event with the given Name and Attributes.

The Span event is marked to have happened at Timestamp. The returned event can be used to add an event to a Span through otel_span:add_events/2, for example.

-spec events([Event]) -> [event()]
          when
              Event ::
                  {Timestamp :: integer(), event_name(), attributes_map()} |
                  {event_name(), attributes_map()}.

Creates a list of Span events from the given List.

This is a convenience function to create a list of Span events from a list of {Time, Name, Attributes} or {Name, Attributes} tuples. It's equivalent to calling event/2 or event/3 multiple times. This function also automatically filters out any invalid tuple.

Link to this function

get_application(ModuleName)

View Source
-spec get_application(module()) -> ApplicationTuple
                   when
                       ApplicationTuple :: {Name, Vsn, SchemaUrl} | atom(),
                       Name :: atom(),
                       Vsn :: unicode:unicode_binary() | undefined,
                       SchemaUrl :: uri_string:uri_string() | undefined.
Link to this function

get_application_scope(ModuleName)

View Source
-spec get_application_scope(module()) -> instrumentation_scope() | undefined.
Link to this function

get_application_tracer(ModuleName)

View Source
-spec get_application_tracer(module()) -> tracer().
Link to this function

get_text_map_extractor()

View Source
-spec get_tracer() -> tracer().

Returns the default global tracer.

Without the opentelemetry application loaded (as a dependency) and started (or another SDK), this function returns the default value {otel_tracer_noop, []}.

-spec get_tracer(Name) -> Tracer
              when
                  Name :: atom() | {atom(), Vsn, SchemaUrl},
                  Vsn :: unicode:chardata() | undefined,
                  SchemaUrl :: uri_string:uri_string() | undefined,
                  Tracer :: opentelemetry:tracer().

Returns the tracer for the given name.

Passing {Name, Vsn, SchemaUrl} is the same as calling get_tracer(Name, Vsn, SchemaUrl).

See also: get_tracer/3.

Link to this function

get_tracer(Name, Vsn, SchemaUrl)

View Source
-spec get_tracer(Name, Vsn, SchemaUrl) -> Tracer
              when
                  Name :: atom(),
                  Vsn :: unicode:chardata() | undefined,
                  SchemaUrl :: uri_string:uri_string() | undefined,
                  Tracer :: opentelemetry:tracer().

Equivalent to get_tracer({Name, Vsn, SchemaUrl}).

Link to this function

instrumentation_library(Name, Vsn, SchemaUrl)

View Source
Link to this function

instrumentation_scope(Name, Vsn, SchemaUrl)

View Source
-spec link(span_ctx() | undefined) -> link() | undefined.

Equivalent to link(SpanCtx, []).

Link to this function

link(SpanCtx, Attributes)

View Source
-spec link(span_ctx() | undefined, attributes_map()) -> link() | undefined.

Creates a Span link to the Span represented by the given SpanCtx.

The returned link can be used in the links field of a Span.

Link to this function

link(TraceId, SpanId, Attributes, TraceState)

View Source
-spec link(TraceId, SpanId, Attributes, TraceState) -> link() | undefined
        when
            TraceId :: trace_id(),
            SpanId :: span_id(),
            Attributes :: attributes_map(),
            TraceState :: otel_tracestate:t() | otel_tracestate:members().

Creates a Span link to the Span represented by the given TraceId and SpanId.

The returned link can be used in the links field of a Span.

-spec links([TraceIdAndSpanId | span_ctx() | {span_ctx(), Attributes}]) -> [link()]
         when
             TraceIdAndSpanId :: {trace_id(), span_id(), Attributes, TraceState},
             Attributes :: attributes_map(),
             TraceState :: otel_tracestate:t() | [{string(), string()}].

Creates a list of Span links from the given List.

This is equivalent to calling link/2 or link/4 multiple times.

Link to this function

set_default_tracer(Tracer)

View Source
-spec set_default_tracer(tracer()) -> boolean().
Link to this function

set_default_tracer(TracerProvider, Tracer)

View Source
-spec set_default_tracer(atom(), tracer()) -> boolean().
Link to this function

set_text_map_extractor(Propagator)

View Source
Link to this function

set_text_map_injector(Propagator)

View Source
Link to this function

set_text_map_propagator(Propagator)

View Source
Link to this function

set_tracer(Name, Tracer)

View Source
-spec set_tracer(atom(), tracer()) -> boolean().
Link to this function

start_tracer_provider(Name, Config)

View Source
This function is deprecated. Start the TracerProvider through the SDK".
-spec start_tracer_provider(atom(), map()) -> {ok, pid() | undefined} | {error, term()}.
-spec status(Code) -> status() | undefined when Code :: status_code().

Create a Span status from the given Code.

The returned status can be used to set the status of a Span through otel_span:set_status/2, for example.

-spec status(Code, Message) -> status() | undefined
          when Code :: status_code(), Message :: unicode:unicode_binary().

Create a Span status from the given Code and with the given Message.

The returned status can be used to set the status of a Span through otel_span:set_status/2, for example.

-spec timestamp() -> integer().

A monotonically increasing time provided by the Erlang runtime system in the native time unit. This value is the most accurate and precise timestamp available from the Erlang runtime and should be used for finding durations or any timestamp that can be converted to a system time before being sent to another system.

Link to this function

timestamp_to_nano(Timestamp)

View Source
-spec timestamp_to_nano(timestamp()) -> pos_integer().

Convert a native monotonic timestamp to nanosecond POSIX time. Meaning the time since Epoch. Epoch is defined to be 00:00:00 UTC, 1970-01-01.