opentelemetry (OpenTelemetry API v1.4.0)
View SourceThe 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.
Equivalent to link(SpanCtx, []).
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().
-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 tracestate() :: otel_tracestate:t().
Functions
-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.
-spec event(Name, Attributes) -> event() | undefined when Name :: event_name(), Attributes :: attributes_map().
Equivalent to event(opentelemetry:timestamp(), Name, Attributes).
-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.
-spec get_application(module()) -> ApplicationTuple when ApplicationTuple :: {Name, Vsn, SchemaUrl} | atom(), Name :: atom(), Vsn :: unicode:unicode_binary() | undefined, SchemaUrl :: uri_string:uri_string() | undefined.
-spec get_application_scope(module()) -> instrumentation_scope() | undefined.
-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.
-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}).
Equivalent to link(SpanCtx, []).
-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.
-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.
-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.
-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.