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.shim.opentracing_shim import create_tracer
# Define which OpenTelemetry Tracer provider 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.
API¶
-
opentelemetry.shim.opentracing_shim.
create_tracer
(otel_tracer_provider)[source]¶ Creates a
TracerShim
object from the provided OpenTelemetryopentelemetry.trace.TracerProvider
.The returned
TracerShim
is an implementation ofopentracing.Tracer
using OpenTelemetry under the hood.- Parameters
otel_tracer_provider (
TracerProvider
) – A tracer from this provider will be used to perform the actual tracing when user code is instrumented using the OpenTracing API.- Return type
- Returns
The created
TracerShim
.
-
class
opentelemetry.shim.opentracing_shim.
SpanContextShim
(otel_context)[source]¶ Implements
opentracing.SpanContext
by wrapping aopentelemetry.trace.SpanContext
object.- Parameters
otel_context (
SpanContext
) – Aopentelemetry.trace.SpanContext
to be used for constructing theSpanContextShim
.
-
unwrap
()[source]¶ Returns the wrapped
opentelemetry.trace.SpanContext
object.- Return type
- Returns
The
opentelemetry.trace.SpanContext
object wrapped by thisSpanContextShim
.
-
class
opentelemetry.shim.opentracing_shim.
SpanShim
(tracer, context, span)[source]¶ Wraps a
opentelemetry.trace.Span
object.- Parameters
tracer – The
opentracing.Tracer
that created thisSpanShim
.context (
SpanContextShim
) – ASpanContextShim
which contains the context for thisSpanShim
.span – A
opentelemetry.trace.Span
to wrap.
-
unwrap
()[source]¶ Returns the wrapped
opentelemetry.trace.Span
object.- Returns
The
opentelemetry.trace.Span
object wrapped by thisSpanShim
.
-
set_operation_name
(operation_name)[source]¶ Updates the name of the wrapped OpenTelemetry span.
- Parameters
operation_name (
str
) – The new name to be used for the underlyingopentelemetry.trace.Span
object.- Return type
- Returns
Returns this
SpanShim
instance to allow call chaining.
-
finish
(finish_time=None)[source]¶ 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 (
Optional
[float
]) – A value that represents the finish time expressed as the number of seconds since the epoch as returned bytime.time()
.
-
log_kv
(key_values, timestamp=None)[source]¶ Logs an 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 any one of the types defined in
opentelemetry.trace.util.Attributes
therefore, only these types are supported as values.- Parameters
key_values (
Optional
[Mapping
[str
,Union
[str
,bool
,int
,float
,Sequence
[str
],Sequence
[bool
],Sequence
[int
],Sequence
[float
]]]]) – A dictionary as specified inopentelemetry.trace.util.Attributes
.timestamp (
Optional
[float
]) – Timestamp of the OpenTelemetry event, will be generated automatically if omitted.
- Return type
- Returns
Returns this
SpanShim
instance to allow call chaining.
-
class
opentelemetry.shim.opentracing_shim.
ScopeShim
(manager, span, span_cm=None)[source]¶ A
ScopeShim
wraps the OpenTelemetry functionality related to span activation/deactivation while using OpenTracingopentracing.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 thefrom_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 OpenTelemetryopentelemetry.trace.Span
context manager (as returned byopentelemetry.trace.use_span()
), in which case our only way of retrieving aopentelemetry.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 aSpanShim
object and wrap it in aScopeShim
. The former is used mainly when the instrumentation code retrieves the currently-active span usingScopeManagerShim.active
. The latter is mainly used when the instrumentation code activates a span usingScopeManagerShim.activate()
.- Parameters
manager (
ScopeManagerShim
) – TheScopeManagerShim
that created thisScopeShim
.span_cm – A Python context manager which yields an OpenTelemetry
opentelemetry.trace.Span
from its__enter__()
method. Used byfrom_context_manager()
to store the context manager as an attribute so that it can later be closed by calling its__exit__()
method. Defaults toNone
.
-
classmethod
from_context_manager
(manager, span_cm)[source]¶ Constructs a
ScopeShim
from an OpenTelemetryopentelemetry.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 = opentelemetry.trace.use_span(span) scope_shim = ScopeShim.from_context_manager( scope_manager_shim, span_cm=span_cm, )
- Parameters
manager (
ScopeManagerShim
) – TheScopeManagerShim
that created thisScopeShim
.span_cm – A context manager as returned by
opentelemetry.trace.use_span()
.
-
close
()[source]¶ Closes the
ScopeShim
. If theScopeShim
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 thisScopeShim
was created. In addition, if the span represented by thisScopeShim
was activated with the finish_on_close argument set toTrue
, calling this method will end the span.Warning
In the current state of the implementation it is possible to create a
ScopeShim
directly from aSpanShim
, that is - without usingfrom_context_manager()
. For that reason we need to be able to end the span represented by theScopeShim
in this case, too. Please note that closing aScopeShim
created this way (for example as returned byScopeManagerShim.active()
) always ends the associated span, regardless of the value passed in finish_on_close when activating the span.
-
class
opentelemetry.shim.opentracing_shim.
ScopeManagerShim
(tracer)[source]¶ Implements
opentracing.ScopeManager
by setting and getting the activeopentelemetry.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 theTracerShim
rather than theopentelemetry.trace.Tracer
wrapped by it because when constructing aSpanShim
we need to pass a reference to aopentracing.Tracer
.- Parameters
tracer (
TracerShim
) – ATracerShim
to use for setting and getting active span state.
-
activate
(span, finish_on_close)[source]¶ Activates a
SpanShim
and returns aScopeShim
which represents the active span.
-
property
active
¶ Returns a
ScopeShim
object representing the currently-active span in the OpenTelemetry tracer.- Return type
- Returns
A
ScopeShim
representing the active span in the OpenTelemetry tracer, orNone
if no span is currently active.
Warning
Calling
ScopeShim.close()
on theScopeShim
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 thisScopeManagerShim
for setting and getting the active span from the OpenTelemetry tracer.- Return type
- Returns
The
TracerShim
used for setting and getting the active span.
Warning
This property is not a part of the OpenTracing API. It is used internally by the current implementation of the OpenTracing shim and will likely be removed in future versions.
-
class
opentelemetry.shim.opentracing_shim.
TracerShim
(tracer)[source]¶ Wraps 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 (
Tracer
) – Aopentelemetry.trace.Tracer
to use for tracing. This tracer will be invoked by the shim to create actual spans.
-
unwrap
()[source]¶ Returns the
opentelemetry.trace.Tracer
object that is wrapped by thisTracerShim
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)[source]¶ 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 (
Union
[SpanShim
,SpanContextShim
,None
]) – ASpanShim
orSpanContextShim
representing the parent in a “child of” reference. If specified, the references parameter must be omitted.references (
Optional
[list
]) – A list ofopentracing.Reference
objects that identify one or more parents of typeSpanContextShim
.tags (
Optional
[Mapping
[str
,Union
[str
,bool
,int
,float
,Sequence
[str
],Sequence
[bool
],Sequence
[int
],Sequence
[float
]]]]) – A dictionary of tags.start_time (
Optional
[float
]) – An explicit start time expressed as the number of seconds since the epoch as returned bytime.time()
.ignore_active_span (
bool
) – Ignore the currently-active span in the OpenTelemetry tracer and make the created span the root span of a new trace.finish_on_close (
bool
) – Determines whether the created span should end automatically when closing the returnedScopeShim
.
- Return type
- Returns
A
ScopeShim
that is already activated by theScopeManagerShim
.
-
start_span
(operation_name=None, child_of=None, references=None, tags=None, start_time=None, ignore_active_span=False)[source]¶ 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 (
Optional
[str
]) – Name of the operation represented by the new span from the perspective of the current service.child_of (
Union
[SpanShim
,SpanContextShim
,None
]) – ASpanShim
orSpanContextShim
representing the parent in a “child of” reference. If specified, the references parameter must be omitted.references (
Optional
[list
]) – A list ofopentracing.Reference
objects that identify one or more parents of typeSpanContextShim
.tags (
Optional
[Mapping
[str
,Union
[str
,bool
,int
,float
,Sequence
[str
],Sequence
[bool
],Sequence
[int
],Sequence
[float
]]]]) – A dictionary of tags.start_time (
Optional
[float
]) – An explicit start time expressed as the number of seconds since the epoch as returned bytime.time()
.ignore_active_span (
bool
) – Ignore the currently-active span in the OpenTelemetry tracer and make the created span the root span of a new trace.
- Return type
- Returns
An already-started
SpanShim
instance.
-
inject
(span_context, format, carrier)[source]¶ Injects
span_context
intocarrier
.See base class for more details.