docs: update Jaeger integration (#5398)

docs/jaeger-reference.asciidoc

@@ -5,14 +5,14 @@
 <titleabbrev>Jaeger</titleabbrev>
 ++++
 
+experimental::[]
+
 // this content is reused in the how-to guides
 // tag::jaeger-intro[]
-experimental::["This feature is experimental and may be changed in a future release. It is not yet available on Elastic Cloud. For feature status on Elastic Cloud, see https://github.com/elastic/apm/issues/212[#212]."]
-
 Elastic APM integrates with https://www.jaegertracing.io/[Jaeger], an open-source, distributed tracing system.
 This integration allows users with an existing Jaeger setup to switch from the default Jaeger backend,
-to ingesting data with Elastic's APM Server, storing data in {es}, and visualizing traces in the APM app.
-Best of all, this can be done without any instrumentation changes in your application code.
+to the Elastic Stack -- transform data with APM Server, store data in {es}, and visualize traces in the Kibana APM app.
+Best of all, no instrumentation changes are needed in your application code.
 // end::jaeger-intro[]
 
 Ready to get started? See the <<jaeger,How to integrate with Jaeger>> guide.
@@ -22,24 +22,50 @@ Ready to get started? See the <<jaeger,How to integrate with Jaeger>> guide.
 === Supported architecture
 
 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:
+that define how data can be sent to a collector. Elastic APM, as a Jaeger collector,
+supports communication with *Jaeger agents* via gRPC.
 
-* Communication with *Jaeger Agents* via gRPC
-+
-The gRPC endpoint supports TLS. If the Jaeger gRPC collector service is enabled,
-and `apm-server.ssl` is configured, SSL settings will automatically be applied to APM Server's Jaeger gRPC endpoint.
-+
-The gRPC endpoint supports probabilistic sampling.
-APM Server automatically enables the sampling endpoint when `grpc.enabled` is set to `true`.
-Sampling decisions can be configured <<jaeger-configure-sampling-central,centrally>>, with APM Agent configuration, or <<jaeger-configure-sampling-local,locally>>, in each Jaeger client.
+* APM Server serves Jaeger gRPC over the same <<host,host and port>> as the Elastic APM agent protocol.
 
-* Communication with *Jaeger Clients* via thrift over HTTP
-+
-The Client HTTP endpoint does not support TLS or sampling.
+* The APM Server gRPC endpoint supports TLS. If `apm-server.ssl` is configured,
+SSL settings will automatically be applied to APM Server's Jaeger gRPC endpoint.
+
+* The gRPC endpoint supports probabilistic sampling.
+Sampling decisions can be configured <<jaeger-configure-sampling-central,centrally>> with APM Agent central configuration, or <<jaeger-configure-sampling-local,locally>> in each Jaeger client.
 
-TIP: See the https://www.jaegertracing.io/docs/1.14/architecture[Jaeger docs]
+See the https://www.jaegertracing.io/docs/1.22/architecture[Jaeger docs]
 for more information on Jaeger architecture.
 
+[%collapsible]
+.Communication with *Jaeger Clients* via thrift over HTTP (deprecated)
+====
+****
+
+deprecated::[7.13.0, To be removed in 8.0.0]
+
+If you've configured your Jaeger clients to send spans directly to collectors (bypassing Jaeger agents),
+enable the APM Server HTTP endpoint by setting `apm-server.jaeger.http.enabled` to `true`.
+Use `apm-server.jaeger.http.host` to change the default port.
+
+* The Client HTTP endpoint does not support TLS or sampling,
+and is not supported by our hosted {ess} on {ecloud}.
+
+* If you're using an officially supported Jaeger Client library and want to connect directly to APM Server,
+you need to update the `JAEGER_ENDPOINT` configuration property.
+This is the HTTP endpoint the Client will send spans to.
+The `host:port` set here should correspond to the value set in `apm-server.jaeger.http.host`.
+See the relevant supported Jaeger library for more information.
++
+** https://github.com/jaegertracing/jaeger-client-go[Go]
+** https://github.com/jaegertracing/jaeger-client-java[Java]
+** https://github.com/jaegertracing/jaeger-client-node[Node.js]
+** https://github.com/jaegertracing/jaeger-client-python[Python]
+** https://github.com/jaegertracing/jaeger-client-cpp[C++]
+** https://github.com/jaegertracing/jaeger-client-csharp[C#]
+
+****
+====
+
 [float]
 [[jaeger-caveats]]
 === Caveats
@@ -49,14 +75,14 @@ There are some limitations and differences between Elastic APM and Jaeger that y
 *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.
+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.
 * We currently only support exception logging. Span logs are not supported.
 
 *Differences between APM Agents and Jaeger Clients:*
 
-* Jaeger Clients only sends trace data.
-APM Agents support a larger number of features, like
+* 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 {apm-overview-ref-v}/apm-data-model.html[data model] is different than Jaegers.
@@ -69,6 +95,8 @@ https://github.com/opentracing/specification/blob/master/semantic_conventions.md
 [[jaeger-configuration]]
 === Configuration options
 
+deprecated::[7.13.0, APM Server serves Jaeger gRPC over the same port as the Elastic APM agent protocol. The following configuration options have been deprecated, and will be removed in 8.0.0]
+
 You can specify the following options in the `apm-server.jaeger.*` section of the
 +{beatname_lc}.yml+ configuration file.
 

docs/jaeger-support.asciidoc

@@ -5,138 +5,68 @@
 <titleabbrev>Integrate with Jaeger</titleabbrev>
 ++++
 
+experimental::[]
+
 include::./jaeger-reference.asciidoc[tag=jaeger-intro]
 
 [float]
 [[jaeger-get-started]]
 ==== Get started
 
-Connecting your preexisting Jaeger setup to Elastic APM is easy!
-Configure APM Server to receive Jaeger data,
-set up sampling, and configure your Jaeger Agents or Jaeger Clients to start sending spans to APM Server.
+Connect your preexisting Jaeger setup to Elastic APM in three steps:
 
-* <<jaeger-configure-apm-server>>
-* <<jaeger-configure-sampling>>
 * <<jaeger-configure-agent-client>>
+* <<jaeger-configure-sampling>>
 * <<jaeger-configure-start>>
 
-IMPORTANT: There are important <<jaeger-caveats>> to understand about this integration.
+IMPORTANT: There are <<jaeger-caveats,caveats>> to this integration.
 
 [float]
-[[jaeger-configure-apm-server]]
-==== Configure APM Server
-
-. Enable the correct jaeger endpoint in the `apm-server.yml` configuration file.
-+
-In a typical Jaeger deployment, Clients send spans to Agents, who forward them to Collectors.
-If this matches your architecture, enable the gRPC endpoint by setting
-`apm-server.jaeger.grpc.enabled` to `true`.
-+
-Alternatively, if you've configured your Clients to send spans directly to Collectors (bypassing Jaeger Agents),
-enable the HTTP endpoint by setting `apm-server.jaeger.http.enabled` to `true`.
-
-. Configure the host and port that APM Server listens on.
-+
-Based on the endpoint enabled in the previous step, configure the relevant host and port:
-+
-* `apm-server.jaeger.grpc.host` defaults to `localhost:14250`.
-* `apm-server.jaeger.http.host` defaults to `localhost:14268`.
+[[jaeger-configure-agent-client]]
+==== Configure Jaeger agents
+
+APM Server serves Jaeger gRPC over the same <<host,host and port>> as the Elastic APM agent protocol.
+
+include::./tab-widgets/jaeger-widget.asciidoc[]
 
 [float]
 [[jaeger-configure-sampling]]
 ==== Configure Sampling
 
-The gRPC endpoint supports probabilistic sampling, which can be used to reduce the amount of data that your agents collect and send.
+APM Server 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.
 
-APM Server automatically enables the sampling endpoint when `grpc.enabled` is set to `true`.
-There are two different ways to configure the sampling rate of your Jaeger Agents:
+There are two different ways to configure the sampling rate of your Jaeger agents:
 
-* <<jaeger-configure-sampling-central,Centrally>>, with APM Agent configuration (default).
-* <<jaeger-configure-sampling-local,Locally>>, in each Jaeger client.
+* <<jaeger-configure-sampling-central,APM Agent central configuration (default)>>
+* <<jaeger-configure-sampling-local,Local sampling in each Jaeger client>>
 
 [float]
 [[jaeger-configure-sampling-central]]
-===== Central sampling
+===== APM Agent central configuration (default)
 
-Central sampling, with APM Agent configuration,
-requires the <<setup-kibana-endpoint,Kibana endpoint>> to be enabled.
-This allows Jaeger clients to poll APM Server for the sampling rate.
-To enable the kibana endpoint, set <<kibana-enabled>> to `true`, and point <<kibana-host>> at the Kibana host that APM Server will communicate with.
+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.
 
-The default sampling ratio, as well as per-service sampling rates,
-can then be configured via the {kibana-ref}/agent-configuration.html[Agent configuration] page in the APM app.
+include::./tab-widgets/jaeger-sampling-widget.asciidoc[]
 
 [float]
 [[jaeger-configure-sampling-local]]
-===== Local sampling
+===== Local sampling in each Jaeger client
 
 If you don't have access to the APM app,
-you'll need to change the Jaeger Client's `sampler.type` and `sampler.param`,
-enabling you to set the sampling configuration locally in each Client.
-See the official https://www.jaegertracing.io/docs/1.17/sampling/[Jaeger sampling documentation]
+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 https://www.jaegertracing.io/docs/1.22/sampling/[Jaeger sampling documentation]
 for more information.
 
-[float]
-[[jaeger-configure-agent-client]]
-==== Configure Jaeger communication
-
-[float]
-[[jaeger-configure-grpc]]
-===== Jaeger Agent communication with APM Server (gRPC)
-
-As of this writing, the Jaeger Agent binary offers the `--reporter.grpc.host-port` CLI flag,
-which can be used to set a static list of collectors for the Jaeger Agent to connect to.
-The `host:port` set here should correspond with the value set in `apm-server.jaeger.grpc.host`.
-
-*Optional token-based authorization**
-
-A <<secret-token,secret token>> or <<api-key,API key>> can be used to ensure only authorized
-Jaeger Agents can send data to the APM Server.
-Authorization is off by default, but can be enabled by setting a value in `apm-server.jaeger.grpc.auth_tag`.
-When enabled, APM Server looks for a _Process tag_ in each incoming event,
-and uses it to authorize the Jaeger Agent against the configured `auth_tag` and secret token or API key.
-Auth tags will be removed from events after being verified.
-
-Here's an example that sets the `auth_tag` and `secret_token` in APM Server:
-
-[source,yaml]
-----
-apm-server.jaeger.grpc.enabled=true
-apm-server.jaeger.grpc.auth_tag=authorization
-apm-server.secret_token=qwerty1234
-----
-
-To authorize Jaeger Agent communication, use the `--agent.tags` CLI flag to pass the corresponding Process tag to the APM Server:
-
-[source,console]
-----
---agent.tags "authorization=Bearer qwerty1234"
-----
-
-See the https://www.jaegertracing.io/docs/1.16/cli/[Jaeger CLI flags documentation] for more information.
-
-[float]
-[[jaeger-configure-http]]
-===== Jaeger Client communication with APM Server (HTTP)
-
-If you're using an officially supported Jaeger Client library and want to connect directly to APM Server,
-you need to update the `JAEGER_ENDPOINT` configuration property.
-This is the HTTP endpoint the Client will send spans to.
-The `host:port` set here should correspond to the value set in `apm-server.jaeger.http.host`.
-
-See the relevant supported Jaeger library for more information.
-
-* https://github.com/jaegertracing/jaeger-client-go[Go]
-* https://github.com/jaegertracing/jaeger-client-java[Java]
-* https://github.com/jaegertracing/jaeger-client-node[Node.js]
-* https://github.com/jaegertracing/jaeger-client-python[Python]
-* https://github.com/jaegertracing/jaeger-client-cpp[C++]
-* https://github.com/jaegertracing/jaeger-client-csharp[C#]
-
 [float]
 [[jaeger-configure-start]]
 ==== Start sending span data
 
-Data sent from Jaeger Agents or Clients to APM Server should now be visible in the APM app!
+That's it! Data sent from Jaeger clients to the APM Server can now be viewed in the APM app.
+
+// Make tab-widgets work
+include::./tab-widgets/code.asciidoc[]

docs/tab-widgets/jaeger-sampling-widget.asciidoc

@@ -0,0 +1,40 @@
+++++
+<div class="tabs" data-tab-group="jaeger">
+  <div role="tablist" aria-label="jaeger sampling instructions">
+    <button role="tab"
+            aria-selected="true"
+            aria-controls="jaeger-cloud-tab-sampling"
+            id="jaeger-cloud-sampling">
+      Elasticsearch Service
+    </button>
+    <button role="tab"
+            aria-selected="false"
+            aria-controls="jaeger-self-managed-tab-sampling"
+            id="jaeger-self-managed-sampling"
+            tabindex="-1">
+      Self-managed
+    </button>
+  </div>
+  <div tabindex="0"
+       role="tabpanel"
+       id="jaeger-cloud-tab-sampling"
+       aria-labelledby="jaeger-cloud-sampling">
+++++
+
+include::jaeger-sampling.asciidoc[tag=ess]
+
+++++
+  </div>
+  <div tabindex="0"
+       role="tabpanel"
+       id="jaeger-self-managed-tab-sampling"
+       aria-labelledby="jaeger-self-managed-sampling"
+       hidden="">
+++++
+
+include::jaeger-sampling.asciidoc[tag=self-managed]
+
+++++
+  </div>
+</div>
+++++

docs/tab-widgets/jaeger-sampling.asciidoc

@@ -0,0 +1,14 @@
+// tag::ess[]
+Visit the {kibana-ref}/agent-configuration.html[Agent configuration] page in the APM app to add a new sampling rate.
+
+// end::ess[]
+
+// tag::self-managed[]
+APM Agent central configuration requires the <<setup-kibana-endpoint,Kibana endpoint>> to be configured.
+To enable the kibana endpoint, set <<kibana-enabled>> to `true`,
+and point <<kibana-host>> at the Kibana host that APM Server will communicate with.
+
+Once configured,
+visit the {kibana-ref}/agent-configuration.html[Agent configuration] page in the APM app to add a new sampling rate.
+
+// end::self-managed[]

docs/tab-widgets/jaeger-widget.asciidoc

@@ -0,0 +1,40 @@
+++++
+<div class="tabs" data-tab-group="jaeger">
+  <div role="tablist" aria-label="jaeger instructions">
+    <button role="tab"
+            aria-selected="true"
+            aria-controls="jaeger-cloud-tab"
+            id="jaeger-cloud">
+      Elasticsearch Service
+    </button>
+    <button role="tab"
+            aria-selected="false"
+            aria-controls="jaeger-self-managed-tab"
+            id="jaeger-self-managed"
+            tabindex="-1">
+      Self-managed
+    </button>
+  </div>
+  <div tabindex="0"
+       role="tabpanel"
+       id="jaeger-cloud-tab"
+       aria-labelledby="jaeger-cloud">
+++++
+
+include::jaeger.asciidoc[tag=ess]
+
+++++
+  </div>
+  <div tabindex="0"
+       role="tabpanel"
+       id="jaeger-self-managed-tab"
+       aria-labelledby="jaeger-self-managed"
+       hidden="">
+++++
+
+include::jaeger.asciidoc[tag=self-managed]
+
+++++
+  </div>
+</div>
+++++