IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

›

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

Operation Modes

edit

This bridge allows for different operation modes in combination with the Elastic APM javaagent

Noop
If the javaagent is not specified, the bridge is in noop mode and does not actually record and report spans.
Mix and Match
If you want to leverage the auto instrumentation of Elastic APM, but also want do create custom spans or use the OpenTracing API to add custom tags to the spans created by Elastic APM, you can just do that. The OpenTracing bridge and the standard Elastic APM API interact seamlessly.
Manual instrumentation
If you don’t want Elastic APM to auto-instrument known frameworks, but instead only rely on manual instrumentation, disable the auto instrumentation setting the configuration option instrument to false.

Getting started

edit

The first step in getting started with the OpenTracing API bridge ist to declare a dependency to the API:

pom.xml.

<dependency>
    <groupId>co.elastic.apm</groupId>
    <artifactId>apm-opentracing</artifactId>
    <version>${elastic-apm.version}</version>
</dependency>

build.gradle.

compile "co.elastic.apm:apm-opentracing:$elasticApmVersion"

Replace the version placeholders with the latest version from maven central:

Initialize tracer

edit

import co.elastic.apm.opentracing.ElasticApmTracer;
import io.opentracing.Tracer

Tracer tracer = new ElasticApmTracer();

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. If the error tag is set to true, the default value is error.

Caveats

edit

Not all features of the OpenTracing API are supported.

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.setBaggageItem(String, String) 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:

Exception e = ...
span.log(
    Map.of(
        "event", "error",
        "error.object", e
    )
)

« Public API Troubleshooting »