OpenTelemetry API v1.0.0-rc.2 OpenTelemetry
An OpenTelemetry Trace consists of 1 or more Spans that either have a
parent/child relationship or are linked together through a Link. Each Span has a TraceId (trace_id/0),
SpanId (span_id/0), and a start and end time in nanoseconds.
This module provides declaration of the types used throughout the library, as well as functions for
building the additional pieces of a span that are optional. Each item can be attached to individual
Span using the functions in OpenTelemetry.Span module.
Example
require OpenTelemetry.Tracer
require OpenTelemetry.Span
OpenTelemetry.register_application_tracer(:this_otp_app)
Tracer.start_span("some-span")
...
event = "ecto.query"
ecto_attributes = OpenTelemetry.event([{"query", query}, {"total_time", total_time}])
OpenTelemetry.Span.add_event(event, ecto_event)
...
Tracer.end_span()
Link to this section Summary
Types
Attributes are a collection of key/value pairs. The value can be a string,
an integer, a double or the boolean values true or false. Note, global attributes
like server name can be set using the resource API.
An Event is a time-stamped annotation of the span, consisting of user-supplied text description and key-value pairs.
A Link is a pointer from the current span to another span in the same trace or in a different trace. For example, this can be used in batching operations, where a single batch handler processes multiple requests from different traces or when the handler receives a request from a different project.
Span represents a single operation within a trace. Spans can be nested to form a trace tree. Spans may also be linked to other spans from the same or different trace and form graphs. Often, a trace contains a root span that describes the end-to-end latency, and one or more subspans for its sub-operations. A trace can also contain multiple root spans, or none at all. Spans do not need to be contiguous - there may be gaps or overlaps between spans in a trace.
A SpanContext represents the portion of a Span needed to do operations on a Span. Within a process it acts as a key for looking up and modifying the actual Span. It is also what is serialized and propagated across process boundaries.
SpanId is a unique identifier for a span within a trace, assigned when the span is created. The ID is an 8-byte array. An ID with all zeroes is considered invalid.
An optional final status for this span. Semantically when Status
wasn't set it means span ended without errors and assume ok.
TraceId is a unique identifier for a trace. All spans from the same trace share
the same trace_id. The ID is a 16-byte array. An ID with all zeroes
is considered invalid.
TracerContext refers to the data kept in process by the tracer to track the current SpanContext and the parent.
Tracestate represents tracing-system specific context in a list of key-value pairs. Tracestate allows different vendors propagate additional information and inter-operate with their legacy Id formats.
Functions
Convert a native monotonic timestamp to POSIX time of any :erlang.time_unit/0.
Meaning the time since Epoch. Epoch is defined to be 00:00:00 UTC, 1970-01-01.
Creates a event/0.
Creates a event/0.
Creates a list of event/0 items.
See :opentelemetry.get_tracer/1.
Creates a link/0 from a span_ctx/0.
Creates a link/0 from a span_ctx/0 and list of attributes/0.
Creates a list of link/0 from a list of 4-tuples.
Registering a Named Tracer with the name of an OTP Application enables each module in the Application to be mapped to the Named Tracer, named for the Application and using the version of the currently loaded Application by that name.
See :opentelemetry.register_tracer/2.
See :opentelemetry.set_default_tracer/1.
Creates a Status.
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.
Link to this section Types
Attributes are a collection of key/value pairs. The value can be a string,
an integer, a double or the boolean values true or false. Note, global attributes
like server name can be set using the resource API.
Examples of attributes:
[{"/http/user_agent" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36"}
{"/http/server_latency", 300}
{"abc.com/myattribute", True}
{"abc.com/score", 10.239}]
An Event is a time-stamped annotation of the span, consisting of user-supplied text description and key-value pairs.
A Link is a pointer from the current span to another span in the same trace or in a different trace. For example, this can be used in batching operations, where a single batch handler processes multiple requests from different traces or when the handler receives a request from a different project.
Span represents a single operation within a trace. Spans can be nested to form a trace tree. Spans may also be linked to other spans from the same or different trace and form graphs. Often, a trace contains a root span that describes the end-to-end latency, and one or more subspans for its sub-operations. A trace can also contain multiple root spans, or none at all. Spans do not need to be contiguous - there may be gaps or overlaps between spans in a trace.
A SpanContext represents the portion of a Span needed to do operations on a Span. Within a process it acts as a key for looking up and modifying the actual Span. It is also what is serialized and propagated across process boundaries.
SpanId is a unique identifier for a span within a trace, assigned when the span is created. The ID is an 8-byte array. An ID with all zeroes is considered invalid.
An optional final status for this span. Semantically when Status
wasn't set it means span ended without errors and assume ok.
TraceId is a unique identifier for a trace. All spans from the same trace share
the same trace_id. The ID is a 16-byte array. An ID with all zeroes
is considered invalid.
TracerContext refers to the data kept in process by the tracer to track the current SpanContext and the parent.
Tracestate represents tracing-system specific context in a list of key-value pairs. Tracestate allows different vendors propagate additional information and inter-operate with their legacy Id formats.
It is a tracestate in the w3c-trace-context format. See also https://github.com/w3c/distributed-tracing for more details about this field.
Link to this section Functions
convert_timestamp(timestamp, unit)
convert_timestamp(integer(), :erlang.time_unit()) :: integer()
Convert a native monotonic timestamp to POSIX time of any :erlang.time_unit/0.
Meaning the time since Epoch. Epoch is defined to be 00:00:00 UTC, 1970-01-01.
Creates a event/0.
event(timestamp, name, attributes)
event(integer(), event_name(), attributes()) :: event()
Creates a event/0.
Creates a list of event/0 items.
get_tracer(name)
See :opentelemetry.get_tracer/1.
Creates a link/0 from a span_ctx/0.
link(span_ctx, attributes)
link(span_ctx() | :undefined, attributes()) :: link()
Creates a link/0 from a span_ctx/0 and list of attributes/0.
link(trace_id, span_id, attributes, tracestate)
link(trace_id(), span_id(), attributes(), tracestate()) :: link()
Creates a link/0.
links(link_list)
links([
{integer(), integer(), attributes(), tracestate()}
| span_ctx()
| {span_ctx(), attributes()}
]) :: [link()]
Creates a list of link/0 from a list of 4-tuples.
register_application_tracer(otp_app)
Registering a Named Tracer with the name of an OTP Application enables each module in the Application to be mapped to the Named Tracer, named for the Application and using the version of the currently loaded Application by that name.
Macros in OpenTelemetry.Tracer use the name of the module they are being used in in order
to lookup the Named Tracer registered for that module and using it for trace operations.
register_tracer(name, vsn)
See :opentelemetry.register_tracer/2.
set_default_tracer(t)
See :opentelemetry.set_default_tracer/1.
Creates a Status.
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.
Use convert_timestamp/2 or timestamp_to_nano/1 to convert a native monotonic time to a
system time of either nanoseconds or another unit.
Using these functions allows timestamps to be accurate, used for duration and be exportable as POSIX time when needed.
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.