OpenTracing API

The Elastic APM OpenTracing bridge allows you to create Elastic APM Transactions and Spans, using the OpenTracing API. In other words, it translates calls to the OpenTracing API to Elastic APM events, which allows for the reuse of existing instrumentation.

The first span of a service will be converted to an Elastic APM Transaction, subsequent spans are mapped to Elastic APM Span.

Getting started

edit

The first step in getting started with the OpenTracing API bridge is to install the opentracing library:

pip install elastic-apm[opentracing]

Or if you already have installed elastic-apm

pip install opentracing>=2.0.0

Initialize tracer

edit

from elasticapm.contrib.opentracing import Tracer

tracer = Tracer();

Tracer accepts the following optional arguments:

client_instance: an already instantiated Elastic APM client
config: a configuration dictionary, which will be used to instantiate a new Elastic APM client, e.g. {"SERVER_URL": "https://example.org"}. See configuration for more information.
scope_manager: a scope manager instance. Defaults to ThreadLocalScopeManager (see

Elastic APM specific tags

edit

Elastic APM defines some tags which are not included in the OpenTracing API but are relevant in the context of Elastic APM.

type - sets the type of the transaction, for example request, ext or db
user.id - sets the user id, appears in the "User" tab in the transaction details in the Elastic APM UI
user.email - sets the user email, appears in the "User" tab in the transaction details in the Elastic APM UI
user.username - sets the user name, appears in the "User" tab in the transaction details in the Elastic APM UI
result - sets the result of the transaction. Overrides the default value of success.

these tags need to be set on the first span of an operation (e.g. an incoming request of your webapp).

Caveats

edit

Not all features of the OpenTracing API are supported.

Scope Managers

edit

Currently, only the ThreadLocalScopeManager is supported. Using other scope managers will lead to unpredictable and possibly app-breaking behavior.

Instrumentation

edit

It is recommended to not use the built-in instrumentations of Elastic APM together with third-party OpenTracing instrumentations like opentracing_instrumentation in the same service. If you would like to use such instrumentations, we recommend to disable the built-in instrumentation using the instrument config option.

Context propagation

edit

This bridge only supports the formats Format.Builtin.TEXT_MAP and Format.Builtin.HTTP_HEADERS. Format.Builtin.BINARY is currently not supported.

Span references

edit

Currently, this bridge only supports child_of references. Other references, like follows_from are not supported yet.

Baggage

edit

The Span.set_baggage_item(key, value) method is not supported. Baggage items are silently dropped.

Logs

edit

Only exception logging is supported. Logging an Exception on the OpenTracing span will create an Elastic APM Error. Example:

with tracer.start_active_span("transaction") as tx_scope:
    try:
        raise ValueError("oops")
    except ValueError:
        exc_type, exc_val, exc_tb = sys.exc_info()[:3]
        tx_scope.span.log_kv({
            "python.exception.type": exc_type,
            "python.exception.val": exc_val,
            "python.exception.tb": exc_tb
        })

« Metrics Log correlation »