Elastic APM OpenTracing bridgeedit
Latest supported OpenTracing version: 0.33 (as of agent and OpenTracing-bridge version 1.9.0)
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
.
Operation Modesedit
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
tofalse
.
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:
Initialize traceredit
import co.elastic.apm.opentracing.ElasticApmTracer; import io.opentracing.Tracer; Tracer tracer = new ElasticApmTracer();
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 examplerequest
,ext
ordb
-
subtype
- sets the subtype of the span, for examplehttp
,mysql
orjsf
-
action
- sets the action related to a span, for examplequery
,execute
orrender
-
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 ofsuccess
. If theerror
tag is set totrue
, the default value iserror
. Settinghttp.status_code
to200
, for example, implicitly sets the result toHTTP 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.