[−][src]Module opentelemetry::api::trace
OpenTelemetry Tracing API.
The tracing API consist of a few main traits:
- The
Tracertrait which describes all tracing operations. - The
Spantrait with is a mutable object storing information about the current operation execution. - The
SpanContextstruct is the portion of aSpanwhich 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
SpanContextthat uniquely identifies theSpan - 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 otherSpans - 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.
Modules
| b3_propagator | B3 Propagator |
| context | Context extensions for tracing |
| event | OpenTelemetry Trace Event Interface |
| futures | OpenTelemetry Futures Compatibility |
| id_generator | OpenTelemetry Id Generator Interface |
| link | OpenTelemetry Trace Link Interface |
| noop | No-op OpenTelemetry Trace Implementation |
| provider | OpenTelemetry Tracer Provider Interface |
| sampler | OpenTelemetry Sampler Interface |
| span | OpenTelemetry Span interface |
| span_context | OpenTelemetry SpanContext interface |
| span_processor | OpenTelemetry Span Processor Interface |
| trace_context_propagator | Trace Context Propagator |
| tracer | OpenTelemetry Tracer interface |