[docs] Document experimental Jaeger support

[simitt]

With #2886 we added experimental Jaeger support to the APM Server.

The APM Server Jaeger integration allows the APM Server to act as a Jaeger collector. This enables users with existing Jaeger instrumentation to use the Elastic APM backend for collecting, storing and visualizing their data, without any changes in their code instrumentation.
See the Jaeger architecture for a description of the Jaeger components.

The Jaeger universe supports different data formats and transport protocols how data can be sent to a collector. APM Server supports data being sent from a Jaeger agent via gRPC, and data sent directly from a Jaeger client via thrift over HTTP. With the current version TChannels are not supported.

The APM Server acting as Jaeger collector does not support probabilistic sampling, which means that the sampling rate cannot be changed via the APM Server.

The implemented gRPC endpoint supports TLS. If apm-server.ssl is configured, the settings are automatically applied to the APM Server's Jaeger gRPC endpoint.
The implemented HTTP endpoint does not support TLS or using a secret token for now.

This feature is experimental, for reasons listed in #3121.

@bmorelli25 for more information - @axw and I have worked on the feature and can provide more details.

[axw]

Some caveats that we should probably point out:

• As mentioned in the description, we don't support pushing down sampling config, and we won't currently visualise sampled stats correctly. This will be addressed in a future version.
• Jaeger only sends trace data, so not all features in the APM UI will be available. In particular: no system/process/runtime metrics, no breakdowns.
• Jaeger has its own trace context header, and does not currently support W3C Trace-Context. If/when they do then it will be possible to mix Jaeger clients with Elastic APM agents. Until then, to do that it would be necessary to modify the application's instrumentation to inject/extract W3C "traceparent" headers alongside the Jaeger headers.
• To convert from Jaeger's model to Elastic APM's, we rely on spans being tagged with the appropriate "span kind" (see https://github.com/opentracing/specification/blob/master/semantic_conventions.md). Server-kind Jaeger spans are mapped to Elastic APM transactions, and client-kind Jaeger spans are mapped to Elastic APM spans -- except where the span is the root, in which case it's a transaction.
• We do not currently record Span Logs (OpenTracing spec), apart from errors.

[ckho]

• Jaeger has its own trace context header, and does not currently support W3C Trace-Context. If/when they do then it will be possible to mix Jaeger clients with Elastic APM agents. Until then, to do that it would be necessary to modify the application's instrumentation to inject/extract W3C "traceparent" headers alongside the Jaeger headers.

@axw I found out that Jaeger has already in the progress of supporting W3C Trace-Context in recent merges. Add W3C TraceContext codec/propagation
Does that mean once they have completed, it will be possible to mix Jaeger clients with Elastic APM agents?

[axw]

@ckho awesome, thanks for pointing that out!

It would need some testing to be sure, but yes I think so.

[Renz2018]

@axw Is that elastic apm support W3C trace context all? I remember elastic apm use elastic-apm-traceparent header as trace context not w3c's traceparent

[axw]

@Renz2018 all Elastic APM agents send and receive the tracecontext header now.

In earlier versions we prefixed the header with elastic-apm-, to avoid breaking users as the Trace-Context spec progressed. Once it settled, we updated all agents to use the canonical (tracecontext) header name by default.

[Renz2018]

@axw Thanks for your reply!