You are looking at preliminary documentation for a future release. Not what you want? See the current release documentation.
Elastic Docs› APM Java Agent Reference [master]› Tracing APIs
« OpenTelemetry bridge Plugin API »

OpenTracing bridgeedit

OpenTracing is discontinued in favor of OpenTelemetry. Consider using the OpenTelemetry bridge instead.
Latest supported OpenTracing version: 0.33 (as of agent and OpenTracing-bridge version 1.9.0)

The Elastic APM OpenTracing bridge allows creating 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 startededit

The first step in getting started with the OpenTracing API bridge is 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: Maven Central

Initialize traceredit

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

Tracer tracer = new ElasticApmTracer();

Since version 1.22.0, the OpenTracing bridge supports Tracer lookup and initialization through the ServiceLoader mechanism. An example for a system that relies on this capability is tracer-resolver, which is used by various OpenTracing libraries, for example the Apache Camel OpenTracing component. When such is used, no code changes are required, only the addition of dependencies for the OpenTracing library and the Elastic OpenTracing bridge.

Elastic APM specific tagsedit

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/span, for example request, ext or db
  • subtype - sets the subtype of the span, for example http, mysql or jsf
  • action - sets the action related to a span, for example query, execute or render
  • user.id - sets the user id, appears in the "User" tab in the transaction details in the Elastic APM app
  • user.email - sets the user email, appears in the "User" tab in the transaction details in the Elastic APM app
  • user.username - sets the user name, appears in the "User" tab in the transaction details in the Elastic APM app
  • 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. Setting http.status_code to 200, for example, implicitly sets the result to HTTP 2xx if not explicitly set otherwise.

Caveatsedit

Not all features of the OpenTracing API are supported.

Context propagationedit

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

Span Referencesedit

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

Baggageedit

The Span.setBaggageItem(String, String) method is not supported. Baggage items are silently dropped.

Logsedit

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
    )
)

Other logs are silently dropped.

« OpenTelemetry bridge Plugin API »