IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Metric Sets Advanced Topics »
Elastic Docs ›

Elastic APM OpenTracing bridge

edit

Elastic APM OpenTracing bridge

edit

The Elastic APM OpenTracing bridge allows to create Elastic APM Transactions and Spans, using the OpenTracing API. In other words, it translates the calls to the OpenTracing API to Elastic APM and thus allows for reusing 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 behaviour.

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
        })
« Metric Sets Advanced Topics »