OpenTracing

edit

Elastic APM RUM agent provides an implementation for the OpenTracing API. The ElasticApmTracer translates OpenTracing API calls to Elastic APM, which allows the reuse of existing instrumentation.

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

Getting started

edit

In order to use OpenTracing API with Elastic APM, you need to first create a Tracer:

const { init: initApm, createTracer } = require('@elastic/apm-rum/dist/bundles/elastic-apm-opentracing.umd.js')
const elasticApm = initApm({
    // ...
})
const elasticTracer = createTracer(elasticApm)

At this point you can either use elasticTracer directly, or register it as a global tracer:

const opentracing = require('opentracing-javascript')
opentracing.initGlobalTracer(elasticTracer);

// ...

const tracer = opentracing.globalTracer();

Please refer to opentracing-javascript documentation for more detail on OpenTracing API.

If you are loading the RUM agent using a script tag, please make sure to use our OpenTracing bundle (@elastic/apm-rum/dist/bundles/elastic-apm-opentracing.umd.js) in your scripts instead, then you can create a tracer using window.elasticApm.createTracer().

Elastic APM specific tags

edit

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

  • type - sets the type of the transaction or span, e.g. "page-load", or "ext.http". If type is not specified, custom would be set instead.

The following tags are relevant only to the root spans, which are translated to Elastic APM transactions. These tags appear in the "User" tab on the transaction details page in the Elastic APM app.

  • user.id - sets the user id
  • user.email - sets the user email
  • user.username - sets the user name

Caveats

edit

Some of the OpenTracing features are not fully supported by Elastic APM RUM agent.

Context propagation

edit

Currently, the only carrier formats supported are FORMAT_HTTP_HEADERS and FORMAT_TEXT_MAP. FORMAT_BINARY is not supported.

Span References

edit

Currently, the Elastic APM Tracer supports REFERENCE_CHILD_OF references. However, only the first REFERENCE_CHILD_OF reference is recorded and the rest are ignored. Other references, e.g. follows_from, are currently not supported.

Baggage

edit

The Span.setBaggageItem method is not supported. Baggage items are silently dropped.

Logs

edit

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