opentelemetry.sdk.trace package¶

Submodules¶

class opentelemetry.sdk.trace.SpanProcessor[source]¶

Bases: object

Interface which allows hooks for SDK’s Span start and end method invocations.

Span processors can be registered directly using TracerProvider.add_span_processor() and they are invoked in the same order as they were registered.

on_start(span)[source]¶

Called when a opentelemetry.trace.Span is started.

This method is called synchronously on the thread that starts the span, therefore it should not block or throw an exception.

Parameters: span (Span) – The opentelemetry.trace.Span that just started.
Return type: None

on_end(span)[source]¶

Called when a opentelemetry.trace.Span is ended.

This method is called synchronously on the thread that ends the span, therefore it should not block or throw an exception.

Parameters: span (Span) – The opentelemetry.trace.Span that just ended.
Return type: None

shutdown()[source]¶

Called when a opentelemetry.sdk.trace.Tracer is shutdown.

Return type: None

force_flush(timeout_millis=30000)[source]¶

Export all ended spans to the configured Exporter that have not yet been exported.

Parameters: timeout_millis (int) – The maximum amount of time to wait for spans to be exported.
Return type: bool
Returns: False if the timeout is exceeded, True otherwise.

class opentelemetry.sdk.trace.MultiSpanProcessor[source]¶

Bases: opentelemetry.sdk.trace.SpanProcessor

Implementation of SpanProcessor that forwards all received events to a list of SpanProcessor.

add_span_processor(span_processor)[source]¶

Adds a SpanProcessor to the list handled by this instance.

Return type: None

on_start(span)[source]¶

Called when a opentelemetry.trace.Span is started.

This method is called synchronously on the thread that starts the span, therefore it should not block or throw an exception.

Parameters: span (Span) – The opentelemetry.trace.Span that just started.
Return type: None

on_end(span)[source]¶

Called when a opentelemetry.trace.Span is ended.

This method is called synchronously on the thread that ends the span, therefore it should not block or throw an exception.

Parameters: span (Span) – The opentelemetry.trace.Span that just ended.
Return type: None

shutdown()[source]¶

Called when a opentelemetry.sdk.trace.Tracer is shutdown.

Return type: None

class opentelemetry.sdk.trace.EventBase(name, timestamp=None)[source]¶

Bases: abc.ABC

property name¶

Return type: str

property timestamp¶

Return type: int

abstract property attributes¶

Return type: Optional[Dict[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

class opentelemetry.sdk.trace.Event(name, attributes=None, timestamp=None)[source]¶

Bases: opentelemetry.sdk.trace.EventBase

A text annotation with a set of attributes.

Parameters

name (str) – Name of the event.
attributes (Optional[Dict[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]) – Attributes of the event.
timestamp (Optional[int]) – Timestamp of the event. If None it will filled automatically.

property attributes¶

Return type: Optional[Dict[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

class opentelemetry.sdk.trace.LazyEvent(name, event_formatter, timestamp=None)[source]¶

Bases: opentelemetry.sdk.trace.EventBase

A text annotation with a set of attributes.

Parameters

name (str) – Name of the event.
event_formatter (Callable[[], Optional[Dict[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]]) – Callable object that returns the attributes of the event.
timestamp (Optional[int]) – Timestamp of the event. If None it will filled automatically.

property attributes¶

Return type: Optional[Dict[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

class opentelemetry.sdk.trace.Span(name, context, parent=None, sampler=None, trace_config=None, resource=None, attributes=None, events=None, links=(), kind=<SpanKind.INTERNAL: 0>, span_processor=<opentelemetry.sdk.trace.SpanProcessor object>, instrumentation_info=None, set_status_on_exception=True)[source]¶

Bases: opentelemetry.trace.Span

See opentelemetry.trace.Span.

Users should create Span objects via the Tracer instead of this constructor.

Parameters

name (str) – The name of the operation this span represents
context (SpanContext) – The immutable span context
parent (Optional[SpanContext]) – This span’s parent’s SpanContext, or null if this is a root span
sampler (Optional[Sampler]) – The sampler used to create this span
trace_config (None) – TODO
resource (None) – Entity producing telemetry
attributes (Optional[Dict[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]) – The span’s attributes to be exported
events (Optional[Sequence[Event]]) – Timestamped events to be exported
links (Sequence[Link]) – Links to other spans to be exported
span_processor (SpanProcessor) – SpanProcessor to invoke when starting and ending this Span.

property start_time¶

property end_time¶

to_json()[source]¶

get_context()[source]¶

Gets the span’s SpanContext.

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

Returns: A SpanContext with a copy of this span’s immutable state.

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

add_lazy_event(name, event_formatter, timestamp=None)[source]¶

Adds an Event.

Adds a single Event with the name, an event formatter that calculates the attributes lazily and, optionally, a timestamp. Implementations should generate a timestamp if the timestamp argument is omitted.

Return type: None

start(start_time=None)[source]¶

Return type: None

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

update_name(name)[source]¶

Updates the Span name.

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

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

Return type: None

is_recording_events()[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

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

opentelemetry.sdk.trace.generate_span_id()[source]¶

Get a new random span ID.

Return type: int
Returns: A random 64-bit int for use as a span ID

opentelemetry.sdk.trace.generate_trace_id()[source]¶

Get a new random trace ID.

Return type: int
Returns: A random 128-bit int for use as a trace ID

class opentelemetry.sdk.trace.Tracer(source, instrumentation_info)[source]¶

Bases: opentelemetry.trace.Tracer

See opentelemetry.trace.Tracer.

Parameters

name – The name of the tracer.
shutdown_on_exit – Register an atexit hook to shut down the tracer when the application exits.

get_current_span()[source]¶

Gets the currently active span from the context.

If there is no current span, return a placeholder span with an invalid context.

Returns: The currently active Span, or a placeholder span with an invalid SpanContext.

start_as_current_span(name, parent=<opentelemetry.trace.DefaultSpan object>, kind=<SpanKind.INTERNAL: 0>, attributes=None, links=())[source]¶

Context manager for creating a new span and set it as the current span in this tracer’s context.

On exiting the context manager stops the span and set its parent as the current span.

Example:

with tracer.start_as_current_span("one") as parent:
    parent.add_event("parent's event")
    with tracer.start_as_current_span("two") as child:
        child.add_event("child's event")
        tracer.get_current_span()  # returns child
    tracer.get_current_span()      # returns parent
tracer.get_current_span()          # returns previously active span

This is a convenience method for creating spans attached to the tracer’s context. Applications that need more control over the span lifetime should use start_span() instead. For example:

with tracer.start_as_current_span(name) as span:
    do_work()

is equivalent to:

span = tracer.start_span(name)
with tracer.use_span(span, end_on_exit=True):
    do_work()

Parameters

name (str) – The name of the span to be created.
parent (Union[Span, SpanContext, None]) – The span’s parent. Defaults to the current span.
kind (SpanKind) – The span’s kind (relationship to parent). Note that is meaningful even if there is no parent.
attributes (Optional[Dict[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]) – The span’s attributes.
links (Sequence[Link]) – Links span to other spans

Yields

The newly-created span.

Return type

Iterator[Span]

start_span(name, parent=<opentelemetry.trace.DefaultSpan object>, kind=<SpanKind.INTERNAL: 0>, attributes=None, links=(), start_time=None, set_status_on_exception=True)[source]¶

Starts a span.

Create a new span. Start the span without setting it as the current span in this tracer’s context.

By default the current span will be used as parent, but an explicit parent can also be specified, either a Span or a SpanContext. If the specified value is None, the created span will be a root span.

The span can be used as context manager. On exiting, the span will be ended.

Example:

# tracer.get_current_span() will be used as the implicit parent.
# If none is found, the created span will be a root instance.
with tracer.start_span("one") as child:
    child.add_event("child's event")

Applications that need to set the newly created span as the current instance should use start_as_current_span() instead.

Parameters

name (str) – The name of the span to be created.
parent (Union[Span, SpanContext, None]) – The span’s parent. Defaults to the current span.
kind (SpanKind) – The span’s kind (relationship to parent). Note that is meaningful even if there is no parent.
attributes (Optional[Dict[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]) – The span’s attributes.
links (Sequence[Link]) – Links span to other spans
start_time (Optional[int]) – Sets the start time of a span
set_status_on_exception (bool) – Only relevant if the returned span is used in a with/context manager. Defines wether the span status will be automatically set to UNKNOWN when an uncaught exception is raised in the span with block. The span status won’t be set by this mechanism if it was previousy set manually.

Return type

Span

Returns

The newly-created span.

use_span(span, end_on_exit=False)[source]¶

Context manager for controlling a span’s lifetime.

Set the given span as the current span in this tracer’s context.

On exiting the context manager set the span that was previously active as the current span (this is usually but not necessarily the parent of the given span). If end_on_exit is True, then the span is also ended when exiting the context manager.

Parameters

span (Span) – The span to start and make current.
end_on_exit (bool) – Whether to end the span automatically when leaving the context manager.

Return type

Iterator[Span]

class opentelemetry.sdk.trace.TracerProvider(sampler=<opentelemetry.trace.sampling.StaticSampler object>, resource=<opentelemetry.sdk.resources.Resource object>, shutdown_on_exit=True)[source]¶

Bases: opentelemetry.trace.TracerProvider

get_tracer(instrumenting_module_name, instrumenting_library_version='')[source]¶

Returns a Tracer for use by the given instrumentation library.

For any two calls it is undefined whether the same or different Tracer instances are returned, even for different library names.

This function may return different Tracer types (e.g. a no-op tracer vs. a functional tracer).

Parameters

instrumenting_module_name (str) –
The name of the instrumenting module (usually just __name__).

This should not be the name of the module that is instrumented but the name of the module doing the instrumentation. E.g., instead of "requests", use "opentelemetry.ext.http_requests".
instrumenting_library_version (str) – Optional. The version string of the instrumenting library. Usually this should be the same as pkg_resources.get_distribution(instrumenting_library_name).version.

Return type

Tracer

static get_current_span()[source]¶

Return type: Span

add_span_processor(span_processor)[source]¶

Registers a new SpanProcessor for this TracerProvider.

The span processors are invoked in the same order they are registered.

Return type: None

shutdown()[source]¶: Shut down the span processors added to the tracer.