opentelemetry.sdk.trace package

Submodules

• opentelemetry.sdk.trace.export

class opentelemetry.sdk.trace.SpanProcessor

Bases: object

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

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

on_start(span)

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)

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

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

Return type

None

force_flush(timeout_millis=30000)

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

Bases: opentelemetry.sdk.trace.SpanProcessor

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

add_span_processor(span_processor)

Adds a SpanProcessor to the list handled by this instance.

Return type

None

on_start(span)

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)

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

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

Return type

None

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)

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 (Union[Span, SpanContext, None]) – This span’s parent, may be a SpanContext if the parent is remote, null if this is a root span

• sampler (Optional[Sampler]) – The sampler used to create this span

• trace_config (None) – TODO

• resource (None) – TODO

• 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.

empty_attributes = BoundedDict({}, maxlen=32)

empty_events = BoundedList([], maxlen=128)

empty_links = BoundedList([], maxlen=32)

property start_time

property end_time

get_context()

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)

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)

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(event)

Adds an Event.

Adds an Event that has previously been created.

Return type

None

start(start_time=None)

Return type

None

end(end_time=None)

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)

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

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)

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

Get a new random span ID. :rtype: int :returns: A random 64-bit int for use as a span ID

opentelemetry.sdk.trace.generate_trace_id()

Get a new random trace ID. :rtype: int :returns: A random 128-bit int for use as a trace ID

class opentelemetry.sdk.trace.InstrumentationInfo(name, version)

Bases: object

Immutable information about an instrumentation library module.

See TracerSource.get_tracer for the meaning of the properties.

property version

Return type

str

property name

Return type

str

class opentelemetry.sdk.trace.Tracer(source, instrumentation_info)

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

See opentelemetry.trace.Tracer.get_current_span.

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

See opentelemetry.trace.Tracer.start_as_current_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)

See opentelemetry.trace.Tracer.start_span.

Return type

Span

use_span(span, end_on_exit=False)

See opentelemetry.trace.Tracer.use_span.

Return type

Iterator[Span]

class opentelemetry.sdk.trace.TracerSource(sampler=<opentelemetry.trace.sampling.StaticSampler object>, shutdown_on_exit=True)

Bases: opentelemetry.trace.TracerSource

get_tracer(instrumenting_module_name, instrumenting_library_version='')

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

Return type

Span

add_span_processor(span_processor)

Registers a new SpanProcessor for this TracerSource.

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

Return type

None

shutdown()

Shut down the span processors added to the tracer.