Module opentelemetry::trace

OpenTelemetry Tracing API.

The tracing API consist of a few main traits:

• The Tracer trait which describes all tracing operations.
• The Span trait with is a mutable object storing information about the current operation execution.
• The SpanContext struct is the portion of a Span which must be serialized and propagated along side of a distributed context

Tracer

The OpenTelemetry library achieves in-process context propagation of Spans by way of the Tracer.

The Tracer is responsible for tracking the currently active Span, and exposes methods for creating and activating new Spans. The Tracer is configured with Propagators which support transferring span context across process boundaries.

Tracers are generally expected to be used as singletons. Implementations SHOULD provide a single global default Tracer.

Some applications may require multiple Tracer instances, e.g. to create Spans on behalf of other applications. Implementations MAY provide a global registry of Tracers for such applications.

Span

A Span represents a single operation within a trace. Spans can be nested to form a trace tree. Each trace contains a root span, which typically describes the end-to-end latency and, optionally, one or more sub-spans for its sub-operations.

Spans encapsulate:

• The span name
• An immutable SpanContext that uniquely identifies the Span
• A parent span in the form of a SpanContext, or None
• A start timestamp
• An end timestamp
• An ordered mapping of Attributes
• A list of Links to other Spans
• A list of timestamped Events
• A Status.

The span name is a human-readable string which concisely identifies the work represented by the Span, for example, an RPC method name, a function name, or the name of a subtask or stage within a larger computation. The span name should be the most general string that identifies a (statistically) interesting class of Spans, rather than individual Span instances. That is, "get_user" is a reasonable name, while "get_user/314159", where "314159" is a user ID, is not a good name due to its high cardinality.

For example, here are potential span names for an endpoint that gets a hypothetical account information:

Span Name	Guidance
get	Too general
get_account/42	Too specific
get_account	Good, and account_id=42 would make a nice Span attribute
get_account/{accountId}	Also good (using the "HTTP route")

The Span's start and end timestamps reflect the elapsed real time of the operation. A Span's start time SHOULD be set to the current time on span creation. After the Span is created, it SHOULD be possible to change the its name, set its Attributes, and add Links and Events. These MUST NOT be changed after the Span's end time has been set.

Spans are not meant to be used to propagate information within a process. To prevent misuse, implementations SHOULD NOT provide access to a Span's attributes besides its SpanContext.

Vendors may implement the Span interface to effect vendor-specific logic. However, alternative implementations MUST NOT allow callers to create Spans directly. All Spans MUST be created via a Tracer.

SpanContext

A SpanContext represents the portion of a Span which must be serialized and propagated along side of a distributed context. SpanContexts are immutable. SpanContext.

The OpenTelemetry SpanContext representation conforms to the w3c TraceContext specification. It contains two identifiers - a TraceId and a SpanId - along with a set of common TraceFlags and system-specific TraceState values.

TraceId A valid trace identifier is a non-zero u128

SpanId A valid span identifier is a non-zero u64 byte.

TraceFlags contain details about the trace. Unlike Tracestate values, TraceFlags are present in all traces. Currently, the only TraceFlags is a boolean sampled flag.

Tracestate carries system-specific configuration data, represented as a list of key-value pairs. TraceState allows multiple tracing systems to participate in the same trace.

IsValid is a boolean flag which returns true if the SpanContext has a non-zero TraceID and a non-zero SpanID.

IsRemote is a boolean flag which returns true if the SpanContext was propagated from a remote parent. When creating children from remote spans, their IsRemote flag MUST be set to false.

Please review the W3C specification for details on the Tracestate field.

Structs

Event	A Span has the ability to add events. Events have a time associated with the moment when they are added to the Span.
Link	During the Span creation user MUST have the ability to record links to other Spans. Linked Spans can be from the same or a different trace.
NoopSpan	A no-op instance of a Span.
NoopSpanExporter	A no-op instance of an SpanExporter.
NoopTracer	A no-op instance of a Tracer.
NoopTracerProvider	A no-op instance of a TracerProvider.
SpanBuilder	SpanBuilder allows span attributes to be configured before the span has started.
SpanContext	Immutable portion of a Span which can be serialized and propagated.
SpanId	SpanId is an 8-byte value which uniquely identifies a given span within a trace The actual u64 value is wrapped in a tuple struct in order to leverage the newtype pattern
TraceId	TraceId is an 16-byte value which uniquely identifies a given trace The actual u128 value is wrapped in a tuple struct in order to leverage the newtype pattern
TraceState	TraceState carries system-specific configuration data, represented as a list of key-value pairs. TraceState allows multiple tracing systems to participate in the same trace.

Enums

SpanKind	SpanKind describes the relationship between the Span, its parents, and its children in a Trace. SpanKind describes two independent properties that benefit tracing systems during analysis.
StatusCode	The StatusCode interface represents the status of a finished Span. It's composed of a canonical code in conjunction with an optional descriptive message.
TraceError	Errors returned by the trace API.

Constants

TRACE_FLAG_DEBUG	TRACE_FLAGS_DEBUG is a bitmask with the debug bit set.
TRACE_FLAG_DEFERRED	TRACE_FLAGS_DEFERRED is a bitmask with the deferred bit set. A SpanContext with the deferred bit set means the sampling decision has been defered to the receiver.
TRACE_FLAG_NOT_SAMPLED	A SpanContext with TRACE_FLAG_NOT_SAMPLED means the span is not sampled.
TRACE_FLAG_SAMPLED	TRACE_FLAG_SAMPLED is a bitmask with the sampled bit set. A SpanContext with the sampling bit set means the span is sampled.

Traits

FutureExt	Extension trait allowing futures, streams, and sinks to be traced with a span.
IdGenerator	Interface for generating IDs
Span	Interface for a single operation within a trace.
TraceContextExt	Methods for storing and retrieving trace data in a context.
Tracer	Interface for constructing Spans.
TracerProvider	An interface to create Tracer instances.

Functions

get_active_span	Executes a closure with a reference to this thread's current span.
mark_span_as_active	Mark a given Span as active.

Type Definitions

TraceResult

Describe the result of operations in tracing API.