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

« Create and upload source maps (RUM) Parse data using ingest pipelines »

› › ›

Jaeger integration

edit

Jaeger integration

edit

Elastic APM integrates with Jaeger, an open-source, distributed tracing system. This integration allows users with an existing Jaeger setup to switch from the default Jaeger backend, to the Elastic Stack. Best of all, no instrumentation changes are needed in your application code.

Supported architecture

edit

Jaeger architecture supports different data formats and transport protocols that define how data can be sent to a collector. Elastic APM, as a Jaeger collector, supports communication with Jaeger agents via gRPC.

The APM integration serves Jaeger gRPC over the same host and port as the Elastic APM agent protocol.
The APM integration gRPC endpoint supports TLS. If SSL is configured, SSL settings will automatically be applied to the APM integration’s Jaeger gRPC endpoint.
The gRPC endpoint supports probabilistic sampling. Sampling decisions can be configured centrally with APM agent central configuration, or locally in each Jaeger client.

See the Jaeger docs for more information on Jaeger architecture.

Get started

edit

Connect your preexisting Jaeger setup to Elastic APM in three steps:

There are caveats to this integration.

Configure Jaeger agents

edit

The APM integration serves Jaeger gRPC over the same host and port as the Elastic APM agent protocol.

Log into Elastic Cloud and select your deployment. In Kibana, select Add data, then search for and select "Elastic APM". If the integration is already installed, under the polices tab, select Actions > Edit integration. If the integration has not been installed, select Add Elastic APM. Copy the URL. If you’re using Agent authorization, copy the Secret token as well.
Configure the APM Integration as a collector for your Jaeger agents.

As of this writing, the Jaeger agent binary offers the following CLI flags, which can be used to enable TLS, output to Elastic Cloud, and set the APM Integration secret token:
```
--reporter.grpc.tls.enabled=true
--reporter.grpc.host-port=<apm-url:443>
--agent.tags="elastic-apm-auth=Bearer <secret-token>"
```

For the equivalent environment variables, change all letters to upper-case and replace punctuation with underscores (_). See the Jaeger CLI flags documentation for more information.

Configure the APM Integration as a collector for your Jaeger agents. In Kibana, select Add data, then search for and select "Elastic APM". If the integration is already installed, under the polices tab, select Actions > Edit integration. If the integration has not been installed, select Add Elastic APM. Copy the Host. If you’re using Agent authorization, copy the Secret token as well.

As of this writing, the Jaeger agent binary offers the --reporter.grpc.host-port CLI flag. Use this to define the host and port that the APM Integration is listening on:
```
--reporter.grpc.host-port=<apm-endpoint:8200>
```
(Optional) Enable encryption

When TLS is enabled for the APM Integration, Jaeger agents must also enable TLS communication:
```
--reporter.grpc.tls.enabled=true
```
(Optional) Enable token-based authorization

A secret token or API key can be used to ensure only authorized Jaeger agents can send data to the APM Integration. When enabled, use an agent level tag to authorize Jaeger agent communication with the APM Server:
```
--agent.tags="elastic-apm-auth=Bearer <secret-token>"
```

For the equivalent environment variables, change all letters to upper-case and replace punctuation with underscores (_). See the Jaeger CLI flags documentation for more information.

Configure Sampling

edit

The APM integration supports probabilistic sampling, which can be used to reduce the amount of data that your agents collect and send. Probabilistic sampling makes a random sampling decision based on the configured sampling value. For example, a value of .2 means that 20% of traces will be sampled.

There are two different ways to configure the sampling rate of your Jaeger agents:

APM agent central configuration (default)

edit

Central sampling, with APM agent central configuration, allows Jaeger clients to poll APM Server for the sampling rate. This means sample rates can be configured on the fly, on a per-service and per-environment basis. See Central configuration to learn more.

Local sampling in each Jaeger client

edit

If you don’t have access to the APM app, you’ll need to change the Jaeger client’s sampler.type and sampler.param. This enables you to set the sampling configuration locally in each Jaeger client. See the official Jaeger sampling documentation for more information.

Start sending data

edit

That’s it! Data sent from Jaeger clients to the APM Server can now be viewed in the APM app.

Caveats

edit

There are some limitations and differences between Elastic APM and Jaeger that you should be aware of.

Jaeger integration limitations:

Because Jaeger has its own trace context header, and does not currently support W3C trace context headers, it is not possible to mix and match the use of Elastic’s APM agents and Jaeger’s clients.
Elastic APM only supports probabilistic sampling.

Differences between APM Agents and Jaeger Clients:

Jaeger clients only sends trace data. APM agents support a larger number of features, like multiple types of metrics, and application breakdown charts. When using Jaeger, features like this will not be available in the APM app.
Elastic APM’s Data Model is different than Jaegers. For Jaeger trace data to work with Elastic’s data model, we rely on spans being tagged with the appropriate span.kind.
- Server Jaeger spans are mapped to Elastic APM Transactions.
- Client Jaeger spans are mapped to Elastic APM Spans — unless the span is the root, in which case it is mapped to an Elastic APM Transactions.

« Create and upload source maps (RUM) Parse data using ingest pipelines »