opentelemetry.trace.span¶

class opentelemetry.trace.span.Span[source]¶

Bases: abc.ABC

A span represents a single operation within a trace.

abstract end(end_time=None)[source]¶

Sets the current time as the span’s end time.

The span’s end time is the wall time at which the operation finished.

Only the first call to end should modify the span, and implementations are free to ignore or raise on further calls.

Return type: None

abstract get_span_context()[source]¶

Gets the span’s SpanContext.

Get an immutable, serializable identifier for this span that can be used to create new child spans.

Return type: SpanContext
Returns: A opentelemetry.trace.SpanContext with a copy of this span’s immutable state.

abstract set_attribute(key, value)[source]¶

Sets an Attribute.

Sets a single Attribute with the key and value passed as arguments.

Return type: None

abstract add_event(name, attributes=None, timestamp=None)[source]¶

Adds an Event.

Adds a single Event with the name and, optionally, a timestamp and attributes passed as arguments. Implementations should generate a timestamp if the timestamp argument is omitted.

Return type: None

abstract update_name(name)[source]¶

Updates the Span name.

This will override the name provided via opentelemetry.trace.Tracer.start_span().

Upon this update, any sampling behavior based on Span name will depend on the implementation.

Return type: None

abstract is_recording()[source]¶

Returns whether this span will be recorded.

Returns true if this Span is active and recording information like events with the add_event operation and attributes using set_attribute.

Return type: bool

abstract set_status(status)[source]¶

Sets the Status of the Span. If used, this will override the default Span status, which is OK.

Return type: None

abstract record_exception(exception)[source]¶

Records an exception as a span event.

Return type: None

class opentelemetry.trace.span.TraceFlags[source]¶

Bases: int

A bitmask that represents options specific to the trace.

The only supported option is the “sampled” flag (0x01). If set, this flag indicates that the trace may have been sampled upstream.

See the W3C Trace Context - Traceparent spec for details.

DEFAULT = 0¶

SAMPLED = 1¶

classmethod get_default()[source]¶

Return type: TraceFlags

property sampled¶

Return type: bool

class opentelemetry.trace.span.TraceState[source]¶

Bases: dict, typing.Generic

A list of key-value pairs representing vendor-specific trace info.

Keys and values are strings of up to 256 printable US-ASCII characters. Implementations should conform to the W3C Trace Context - Tracestate spec, which describes additional restrictions on valid field values.

classmethod get_default()[source]¶

Return type: TraceState

class opentelemetry.trace.span.SpanContext[source]¶

Bases: tuple, typing.Generic

The state of a Span to propagate between processes.

This class includes the immutable attributes of a Span that must be propagated to a span’s children and across process boundaries.

Parameters

trace_id – The ID of the trace that this span belongs to.
span_id – This span’s ID.
trace_flags – Trace options to propagate.
trace_state – Tracing-system-specific info to propagate.
is_remote – True if propagated from a remote parent.

property trace_id¶

Return type: int

property span_id¶

Return type: int

property is_remote¶

Return type: bool

property trace_flags¶

Return type: TraceFlags

property trace_state¶

Return type: TraceState

property is_valid¶

Return type: bool

class opentelemetry.trace.span.DefaultSpan(context)[source]¶

Bases: opentelemetry.trace.span.Span

The default Span that is used when no Span implementation is available.

All operations are no-op except context propagation.

get_span_context()[source]¶

Gets the span’s SpanContext.

Get an immutable, serializable identifier for this span that can be used to create new child spans.

Return type: SpanContext
Returns: A opentelemetry.trace.SpanContext with a copy of this span’s immutable state.

is_recording()[source]¶

Returns whether this span will be recorded.

Returns true if this Span is active and recording information like events with the add_event operation and attributes using set_attribute.

Return type: bool

end(end_time=None)[source]¶

Sets the current time as the span’s end time.

The span’s end time is the wall time at which the operation finished.

Only the first call to end should modify the span, and implementations are free to ignore or raise on further calls.

Return type: None

set_attribute(key, value)[source]¶

Sets an Attribute.

Sets a single Attribute with the key and value passed as arguments.

Return type: None

add_event(name, attributes=None, timestamp=None)[source]¶

Adds an Event.

Adds a single Event with the name and, optionally, a timestamp and attributes passed as arguments. Implementations should generate a timestamp if the timestamp argument is omitted.

Return type: None

update_name(name)[source]¶

Updates the Span name.

This will override the name provided via opentelemetry.trace.Tracer.start_span().

Upon this update, any sampling behavior based on Span name will depend on the implementation.

Return type: None

set_status(status)[source]¶

Sets the Status of the Span. If used, this will override the default Span status, which is OK.

Return type: None

record_exception(exception)[source]¶

Records an exception as a span event.

Return type: None

opentelemetry.trace.span.format_trace_id(trace_id)[source]¶

Return type: str

opentelemetry.trace.span.format_span_id(span_id)[source]¶

Return type: str

opentelemetry.trace.span.get_hexadecimal_trace_id(trace_id)[source]¶

Return type: str

opentelemetry.trace.span.get_hexadecimal_span_id(span_id)[source]¶

Return type: str