OpenTracing Shim for OpenTelemetry

The OpenTelemetry OpenTracing shim is a library which allows an easy migration from OpenTracing to OpenTelemetry.

The shim consists of a set of classes which implement the OpenTracing Python API while using OpenTelemetry constructs behind the scenes. Its purpose is to allow applications which are already instrumented using OpenTracing to start using OpenTelemetry with a minimal effort, without having to rewrite large portions of the codebase.

To use the shim, a TracerShim instance is created and then used as if it were an “ordinary” OpenTracing opentracing.Tracer, as in the following example:

import time

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.ext.opentracing_shim import create_tracer

# Tell OpenTelemetry which Tracer implementation to use.
trace.set_tracer_provider(TracerProvider())

# Create an OpenTelemetry Tracer.
otel_tracer = trace.get_tracer(__name__)

# Create an OpenTracing shim.
shim = create_tracer(otel_tracer)

with shim.start_active_span("ProcessHTTPRequest"):
    print("Processing HTTP request")
    # Sleeping to mock real work.
    time.sleep(0.1)
    with shim.start_active_span("GetDataFromDB"):
        print("Getting data from DB")
        # Sleeping to mock real work.
        time.sleep(0.2)

Note

While the OpenTracing Python API represents time values as the number of seconds since the epoch expressed as float values, the OpenTelemetry Python API represents time values as the number of nanoseconds since the epoch expressed as int values. This fact requires the OpenTracing shim to convert time values back and forth between the two representations, which involves floating point arithmetic.

Due to the way computers represent floating point values in hardware, representation of decimal floating point values in binary-based hardware is imprecise by definition.

The above results in slight imprecisions in time values passed to the shim via the OpenTracing API when comparing the value passed to the shim and the value stored in the OpenTelemetry opentelemetry.trace.Span object behind the scenes. This is not a bug in this library or in Python. Rather, this is a generic problem which stems from the fact that not every decimal floating point number can be correctly represented in binary, and therefore affects other libraries and programming languages as well. More information about this problem can be found in the Floating Point Arithmetic: Issues and Limitations section of the Python documentation.

While testing this library, the aforementioned imprecisions were observed to be of less than a microsecond.

opentelemetry.ext.opentracing_shim.create_tracer(otel_tracer_provider)

Creates a TracerShim object from the provided OpenTelemetry opentelemetry.trace.TracerProvider.

The returned TracerShim is an implementation of opentracing.Tracer using OpenTelemetry under the hood.

Parameters

otel_tracer_provider – A opentelemetry.trace.TracerProvider to be used for constructing the TracerShim. A tracer from this source will be used to perform the actual tracing when user code is instrumented using the OpenTracing API.

Returns

The created TracerShim.

class opentelemetry.ext.opentracing_shim.SpanContextShim(otel_context)

Implements opentracing.SpanContext by wrapping a opentelemetry.trace.SpanContext object.

Parameters

otel_context – A opentelemetry.trace.SpanContext to be used for constructing the SpanContextShim.

unwrap()

Returns the wrapped opentelemetry.trace.SpanContext object.

Returns

The opentelemetry.trace.SpanContext object wrapped by this SpanContextShim.

property baggage

Implements the baggage property from the base class.

Warning

Not implemented yet.

class opentelemetry.ext.opentracing_shim.SpanShim(tracer, context, span)

Implements opentracing.Span by wrapping a opentelemetry.trace.Span object.

Parameters

• tracer – The opentracing.Tracer that created this SpanShim.

• context – A SpanContextShim which contains the context for this SpanShim.

• span – A opentelemetry.trace.Span to wrap.

unwrap()

Returns the wrapped opentelemetry.trace.Span object.

Returns

The opentelemetry.trace.Span object wrapped by this SpanShim.

set_operation_name(operation_name)

Implements the set_operation_name() method from the base class.

Updates the name of the wrapped OpenTelemetry span.

Returns

Returns this SpanShim instance to allow call chaining.

finish(finish_time=None)

Implements the finish() method from the base class.

Ends the OpenTelemetry span wrapped by this SpanShim.

If finish_time is provided, the time value is converted to the OpenTelemetry time format (number of nanoseconds since the epoch, expressed as an integer) and passed on to the OpenTelemetry tracer when ending the OpenTelemetry span. If finish_time isn’t provided, it is up to the OpenTelemetry tracer implementation to generate a timestamp when ending the span.

Parameters

finish_time (float, optional) – An explicit finish time expressed as the number of seconds since the epoch as returned by time.time(). Defaults to None.

set_tag(key, value)

Implements the set_tag() method from the base class.

Sets an OpenTelemetry attribute on the wrapped OpenTelemetry span.

Parameters

• key (str) – A tag key.

• value – A tag value. Can be one of str, bool, int, float

Returns

Returns this SpanShim instance to allow call chaining.

log_kv(key_values, timestamp=None)

Implements the log_kv() method from the base class.

Logs an opentelemetry.trace.Event for the wrapped OpenTelemetry span.

Note

The OpenTracing API defines the values of key_values to be of any type. However, the OpenTelemetry API requires that the values be one of str, bool, float. Therefore, only these types are supported as values.

Parameters

key_values (dict) – A dict with str keys and values of type str, bool or float.

Returns

Returns this SpanShim instance to allow call chaining.

log(**kwargs)

log_event(event, payload=None)

set_baggage_item(key, value)

Implements the set_baggage_item() method from the base class.

Warning

Not implemented yet.

get_baggage_item(key)

Implements the get_baggage_item() method from the base class.

Warning

Not implemented yet.

class opentelemetry.ext.opentracing_shim.ScopeShim(manager, span, span_cm=None)

A ScopeShim wraps the OpenTelemetry functionality related to span activation/deactivation while using OpenTracing opentracing.Scope objects for presentation.

Unlike other classes in this package, the ScopeShim class doesn’t wrap an OpenTelemetry class because OpenTelemetry doesn’t have the notion of “scope” (though it does have similar functionality).

There are two ways to construct a ScopeShim object: using the default initializer and using the from_context_manager() class method.

It is necessary to have both ways for constructing ScopeShim objects because in some cases we need to create the object from an OpenTelemetry opentelemetry.trace.Span context manager (as returned by opentelemetry.trace.Tracer.use_span()), in which case our only way of retrieving a opentelemetry.trace.Span object is by calling the __enter__() method on the context manager, which makes the span active in the OpenTelemetry tracer; whereas in other cases we need to accept a SpanShim object and wrap it in a ScopeShim. The former is used mainly when the instrumentation code retrieves the currently-active span using ScopeManagerShim.active. The latter is mainly used when the instrumentation code activates a span using ScopeManagerShim.activate().

Parameters

• manager – The ScopeManagerShim that created this ScopeShim.

• span – The SpanShim this ScopeShim controls.

• span_cm (contextlib.AbstractContextManager, optional) – A Python context manager which yields an OpenTelemetry opentelemetry.trace.Span from its __enter__() method. Used by from_context_manager() to store the context manager as an attribute so that it can later be closed by calling its __exit__() method. Defaults to None.

TODO: Is contextlib.AbstractContextManager the correct

type for span_cm?

classmethod from_context_manager(manager, span_cm)

Constructs a ScopeShim from an OpenTelemetry opentelemetry.trace.Span context manager.

The method extracts a opentelemetry.trace.Span object from the context manager by calling the context manager’s __enter__() method. This causes the span to start in the OpenTelemetry tracer.

Example usage:

span = otel_tracer.start_span("TestSpan")
span_cm = otel_tracer.use_span(span)
scope_shim = ScopeShim.from_context_manager(
    scope_manager_shim,
    span_cm=span_cm,
)

Parameters

• manager – The ScopeManagerShim that created this ScopeShim.

• span_cm – A context manager as returned by opentelemetry.trace.Tracer.use_span().

close()

Implements the close() method from opentracing.Scope.

Closes the ScopeShim. If the ScopeShim was created from a context manager, calling this method sets the active span in the OpenTelemetry tracer back to the span which was active before this ScopeShim was created. In addition, if the span represented by this ScopeShim was activated with the finish_on_close argument set to True, calling this method will end the span.

Warning

In the current state of the implementation it is possible to create a ScopeShim directly from a SpanShim, that is - without using from_context_manager(). For that reason we need to be able to end the span represented by the ScopeShim in this case, too. Please note that closing a ScopeShim created this way (for example as returned by ScopeManagerShim.active()) always ends the associated span, regardless of the value passed in finish_on_close when activating the span.

class opentelemetry.ext.opentracing_shim.ScopeManagerShim(tracer)

Implements opentracing.ScopeManager by setting and getting the active opentelemetry.trace.Span in the OpenTelemetry tracer.

This class keeps a reference to a TracerShim as an attribute. This reference is used to communicate with the OpenTelemetry tracer. It is necessary to have a reference to the TracerShim rather than the opentelemetry.trace.Tracer wrapped by it because when constructing a SpanShim we need to pass a reference to a opentracing.Tracer.

Parameters

tracer – A TracerShim to use for setting and getting active span state.

activate(span, finish_on_close)

Implements the activate() method from the base class.

Activates a SpanShim and returns a ScopeShim which represents the active span.

Parameters

• span – A SpanShim to be activated.

• finish_on_close (bool) – Determines whether the OpenTelemetry span should be ended when the returned ScopeShim is closed.

Returns

A ScopeShim representing the activated span.

property active

Implements the active property from the base class.

Returns a ScopeShim object representing the currently-active span in the OpenTelemetry tracer.

Returns

A ScopeShim representing the active span in the OpenTelemetry tracer, or None if no span is currently active.

Warning

Calling ScopeShim.close() on the ScopeShim returned by this property always ends the corresponding span, regardless of the finish_on_close value used when activating the span. This is a limitation of the current implementation of the OpenTracing shim and is likely to be handled in future versions.

property tracer

Returns the TracerShim reference used by this ScopeManagerShim for setting and getting the active span from the OpenTelemetry tracer.

Returns

The TracerShim used for setting and getting the active span.

Warning

This property is not a part of the OpenTracing API. It used internally by the current implementation of the OpenTracing shim and will likely be removed in future versions.

class opentelemetry.ext.opentracing_shim.TracerShim(tracer)

Implements opentracing.Tracer by wrapping a opentelemetry.trace.Tracer object.

This wrapper class allows using an OpenTelemetry tracer as if it were an OpenTracing tracer. It exposes the same methods as an “ordinary” OpenTracing tracer, and uses OpenTelemetry transparently for performing the actual tracing.

This class depends on the OpenTelemetry API. Therefore, any implementation of a opentelemetry.trace.Tracer should work with this class.

Parameters

tracer – A opentelemetry.trace.Tracer to use for tracing. This tracer will be invoked by the shim to create actual spans.

unwrap()

Returns the opentelemetry.trace.Tracer object that is wrapped by this TracerShim and used for actual tracing.

Returns

The opentelemetry.trace.Tracer used for actual tracing.

start_active_span(operation_name, child_of=None, references=None, tags=None, start_time=None, ignore_active_span=False, finish_on_close=True)

Implements the start_active_span() method from the base class.

Starts and activates a span. In terms of functionality, this method behaves exactly like the same method on a “regular” OpenTracing tracer. See opentracing.Tracer.start_active_span() for more details.

Parameters

• operation_name (str) – Name of the operation represented by the new span from the perspective of the current service.

• child_of (SpanShim or SpanContextShim, optional) – A SpanShim or SpanContextShim representing the parent in a “child of” reference. If specified, the references parameter must be omitted. Defaults to None.

• references (list, optional) – A list of opentracing.Reference objects that identify one or more parents of type SpanContextShim. Defaults to None.

• tags (dict, optional) – A dictionary of tags. The keys must be of type str. The values may be one of str, bool, int, float. Defaults to None.

• start_time (float, optional) – An explicit start time expressed as the number of seconds since the epoch as returned by time.time(). Defaults to None.

• ignore_active_span (bool, optional) – Ignore the currently-active span in the OpenTelemetry tracer and make the created span the root span of a new trace. Defaults to False.

• finish_on_close (bool, optional) – Determines whether the created span should end automatically when closing the returned ScopeShim. Defaults to True.

Returns

A ScopeShim that is already activated by the ScopeManagerShim.

start_span(operation_name=None, child_of=None, references=None, tags=None, start_time=None, ignore_active_span=False)

Implements the start_span() method from the base class.

Starts a span. In terms of functionality, this method behaves exactly like the same method on a “regular” OpenTracing tracer. See opentracing.Tracer.start_span() for more details.

Parameters

• operation_name (str) – Name of the operation represented by the new span from the perspective of the current service.

• child_of (SpanShim or SpanContextShim, optional) – A SpanShim or SpanContextShim representing the parent in a “child of” reference. If specified, the references parameter must be omitted. Defaults to None.

• references (list, optional) – A list of opentracing.Reference objects that identify one or more parents of type SpanContextShim. Defaults to None.

• tags (dict, optional) – A dictionary of tags. The keys must be of type str. The values may be one of str, bool, int, float. Defaults to None.

• start_time (float, optional) – An explicit start time expressed as the number of seconds since the epoch as returned by time.time(). Defaults to None.

• ignore_active_span (bool, optional) – Ignore the currently-active span in the OpenTelemetry tracer and make the created span the root span of a new trace. Defaults to False.

Returns

An already-started SpanShim instance.

inject(span_context, format, carrier)

Implements the inject method from the base class.

extract(format, carrier)

Implements the extract method from the base class.