Revert "Clean up OpenTelemetry content" (#1129)

Reverts #985

See
elastic/observability-docs#4843 (comment)

Author: theletterf

redirects.yml

@@ -30,16 +30,10 @@ redirects:
   'solutions/observability/apps/real-user-monitoring-rum.md': 'solutions/observability/apm/real-user-monitoring-rum.md'
   'solutions/observability/apps/create-upload-source-maps-rum.md': 'solutions/observability/apm/create-upload-source-maps-rum.md'
   'solutions/observability/apps/use-opentelemetry-with-apm.md': 'solutions/observability/apm/use-opentelemetry-with-apm.md'
-  'solutions/observability/apps/upstream-opentelemetry-collectors-language-sdks.md': 'solutions/observability/apm/use-opentelemetry-with-apm.md'
-  'solutions/observability/apps/collect-metrics.md': 'solutions/observability/apm/use-opentelemetry-with-apm.md'
-  'solutions/observability/apps/limitations.md': 'solutions/observability/apm/use-opentelemetry-with-apm.md'
-  'solutions/observability/apps/resource-atrributes.md': 'solutions/observability/apm/use-opentelemetry-with-apm.md'
-  'solutions/observability/apm/collect-metrics.md': 'solutions/observability/apm/use-opentelemetry-with-apm.md'
-  'solutions/observability/apm/limitations.md': 'solutions/observability/apm/use-opentelemetry-with-apm.md'
-  'solutions/observability/apm/resource-attributes.md': 'solutions/observability/apm/use-opentelemetry-with-apm.md'
-  'solutions/observability/apm/upstream-opentelemetry-collectors-language-sdks.md': 'solutions/observability/apm/use-opentelemetry-with-apm.md'
-  'solutions/observability/get-started/quickstart-monitor-hosts-with-opentelemetry.md': 'solutions/observability/get-started.md'
-  'solutions/observability/get-started/quickstart-unified-kubernetes-observability-with-elastic-distributions-of-opentelemetry-edot.md': 'solutions/observability/get-started.md'
+  'solutions/observability/apps/upstream-opentelemetry-collectors-language-sdks.md': 'solutions/observability/apm/upstream-opentelemetry-collectors-language-sdks.md'
+  'solutions/observability/apps/collect-metrics.md': 'solutions/observability/apm/collect-metrics.md'
+  'solutions/observability/apps/limitations.md': 'solutions/observability/apm/limitations.md'
+  'solutions/observability/apps/resource-atrributes.md': 'solutions/observability/apm/resource-attributes.md'
   'solutions/observability/apps/apm-k8s-attacher.md': 'solutions/observability/apm/apm-k8s-attacher.md'
   'solutions/observability/apps/monitoring-aws-lambda-functions.md': 'solutions/observability/apm/monitor-aws-lambda-functions.md'
   'solutions/observability/apps/integrate-with-jaeger-deprecated.md': 'solutions/observability/apm/jaeger.md'

solutions/observability/apm/collect-metrics.md

@@ -0,0 +1,54 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/observability/current/apm-open-telemetry-collect-metrics.html
+  - https://www.elastic.co/guide/en/serverless/current/observability-apm-agents-opentelemetry-collect-metrics.html
+applies_to:
+  stack:
+  serverless:
+---
+
+# Collect metrics [apm-open-telemetry-collect-metrics]
+
+::::{important}
+When collecting metrics, note that the [`DoubleValueRecorder`](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/latest/io/opentelemetry/api/metrics/DoubleValueRecorder.md) and [`LongValueRecorder`](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/latest/io/opentelemetry/api/metrics/LongValueObserver.md) metrics are not yet supported.
+::::
+
+Here’s an example of how to capture business metrics from a Java application.
+
+```java
+// initialize metric
+Meter meter = GlobalMetricsProvider.getMeter("my-frontend");
+DoubleCounter orderValueCounter = meter.doubleCounterBuilder("order_value").build();
+
+public void createOrder(HttpServletRequest request) {
+
+   // create order in the database
+   ...
+   // increment business metrics for monitoring
+   orderValueCounter.add(orderPrice);
+}
+```
+
+See the [Open Telemetry Metrics API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md) for more information.
+
+## Verify OpenTelemetry metrics data [apm-open-telemetry-verify-metrics]
+
+Use **Discover** to validate that metrics are successfully reported to {{kib}}.
+
+1. Open your Observability instance.
+2. Find **Discover** in the main menu or use the [global search field](/get-started/the-stack.md#kibana-navigation-search).
+3. Click **All logs** → **Data Views** then select **APM**.
+4. Filter the data to only show documents with metrics: `processor.name :"metric"`
+5. Narrow your search with a known OpenTelemetry field. For example, if you have an `order_value` field, add `order_value: *` to your search to return only OpenTelemetry metrics documents.
+
+## Visualize your metrics[apm-open-telemetry-visualize]
+
+Use **Lens** to create visualizations for OpenTelemetry metrics. Lens enables you to build visualizations by dragging and dropping data fields. It makes smart visualization suggestions for your data, allowing you to switch between visualization types.
+
+To get started with a new Lens visualization:
+
+1. Go to **Visualizations**.
+2. Click **Create new visualization**.
+3. Select **Lens**.
+
+For more information on using Lens, refer to the [Lens documentation](/explore-analyze/visualize/lens.md).

solutions/observability/apm/get-started-apm-server-binary.md

@@ -732,9 +732,9 @@ const apm = initApm({
 ::::::
 
 ::::::{tab-item} OpenTelemetry
-Elastic integrates with OpenTelemetry using the Elastic Distribution of OpenTelemetry (EDOT), allowing you to reuse your existing instrumentation to easily send observability data to the {{stack}}.
+Elastic integrates with OpenTelemetry, allowing you to reuse your existing instrumentation to easily send observability data to the {{stack}}.
 
-For more information on how to combine Elastic and OpenTelemetry, see the [EDOT documentation](https://elastic.github.io/opentelemetry/).
+For more information on how to combine Elastic and OpenTelemetry, see [OpenTelemetry integration](/solutions/observability/apm/use-opentelemetry-with-apm.md).
 ::::::
 
 :::::::

solutions/observability/apm/get-started-fleet-managed-apm-server.md

@@ -773,9 +773,9 @@ const apm = initApm({
 ::::::
 
 ::::::{tab-item} OpenTelemetry
-Elastic integrates with OpenTelemetry using the Elastic Distribution of OpenTelemetry (EDOT), allowing you to reuse your existing instrumentation to easily send observability data to the {{stack}}.
+Elastic integrates with OpenTelemetry, allowing you to reuse your existing instrumentation to easily send observability data to the {{stack}}.
 
-For more information on how to combine Elastic and OpenTelemetry, see the [EDOT documentation](https://elastic.github.io/opentelemetry/).
+For more information on how to combine Elastic and OpenTelemetry, see [OpenTelemetry integration](/solutions/observability/apm/use-opentelemetry-with-apm.md).
 ::::::
 
 :::::::

solutions/observability/apm/limitations.md

@@ -0,0 +1,49 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/observability/current/apm-open-telemetry-known-limitations.html
+  - https://www.elastic.co/guide/en/serverless/current/observability-apm-agents-opentelemetry-limitations.html
+applies_to:
+  stack:
+  serverless:
+---
+
+# Limitations [apm-open-telemetry-known-limitations]
+
+## OpenTelemetry traces [apm-open-telemetry-traces-limitations]
+
+* Traces of applications using `messaging` semantics might be wrongly displayed as `transactions` in the Applications UI, while they should be considered `spans` (see issue [#7001](https://github.com/elastic/apm-server/issues/7001)).
+* Inability to see Stack traces in spans.
+* Inability in APM views to view the "Time Spent by Span Type"  (see issue [#5747](https://github.com/elastic/apm-server/issues/5747)).
+
+## OpenTelemetry logs [apm-open-telemetry-logs-intake]
+
+* [preview] The OpenTelemetry logs intake via Elastic is in technical preview.
+* The application logs data stream (`app_logs`) has dynamic mapping disabled. This means the automatic detection and mapping of new fields is disabled (see issue [#9093](https://github.com/elastic/apm-server/issues/9093)).
+
+## OpenTelemetry Line Protocol (OTLP) [apm-open-telemetry-otlp-limitations]
+
+Elastic supports both the  [OTLP/gRPC](https://opentelemetry.io/docs/specs/otlp/#otlpgrpc) and [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/#otlphttp) protocol with ProtoBuf payload. Elastic does not yet support JSON Encoding for OTLP/HTTP.
+
+## OpenTelemetry Collector exporter for Elastic [apm-open-telemetry-collector-exporter]
+
+The [OpenTelemetry Collector exporter for Elastic](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.57.2/exporter/elasticexporter) has been deprecated and replaced by the native support of the OpenTelemetry Line Protocol in Elastic Observability (OTLP).
+
+The [OpenTelemetry Collector exporter for Elastic](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/elasticsearchexporter) (which is different from the legacy exporter mentioned above) is not intended to be used with Elastic APM and Elastic Observability. Use [Elastic’s native OTLP support](/solutions/observability/apm/upstream-opentelemetry-collectors-language-sdks.md) instead.
+
+% Statefull only for tail-based sampling?
+
+## OpenTelemetry’s tail-based sampling [apm-open-telemetry-tbs]
+```{applies_to}
+stack: all
+```
+
+Tail-based sampling allows to make sampling decisions after all spans of a trace have been completed. This allows for more powerful and informed sampling rules.
+
+When using OpenTelemetry with Elastic APM, there are two different implementations available for tail-based sampling:
+
+* Tail-based sampling using the [tailsamplingprocessor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/tailsamplingprocessor) in the OpenTelemetry Collector
+* Native [tail-based sampling in the Elastic APM backend](/solutions/observability/apm/transaction-sampling.md#apm-tail-based-sampling)
+
+Using the [tailsamplingprocessor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/tailsamplingprocessor) in the OpenTelemetry Collector comes with an important limitation. Elastic’s APM backend calculates span and transaction metrics based on the incoming span events. These metrics are accurate for 100% sampling scenarios. In scenarios with probabilistic sampling, Elastic’s APM backend is being informed about the sampling rate of spans and can extrapolate throughput metrics based on the incoming, partial data. However, with tail-based sampling there’s no clear probability for sampling decisions as the rules can be more complex and the OpenTelemetry Collector does not provide sampling probability information to the Elastic backend that could be used for extrapolation of data. Therefore, there’s no way for Elastic APM to properly extrapolate throughput and count metrics that are derived from span events that have been tail-based sampled in the OpenTelemetry Collector. In these scenarios, derived throughput and count metrics are likely to be inaccurate.
+
+Therefore, we recommend using Elastic’s native tail-based sampling when integrating with OpenTelemetry.

solutions/observability/apm/managed-intake-service-event-api.md

@@ -4476,5 +4476,7 @@ The managed intake service supports two OTLP communication protocols on the same
 | OTLP logs intake | `/v1/logs` |
 
 ::::{tip}
-See our [OpenTelemetry documentation](https://elastic.github.io/opentelemetry/) to learn how to send data to the managed intake service.
+See our [OpenTelemetry docs](/solutions/observability/apm/upstream-opentelemetry-collectors-language-sdks.md) to learn how to send data to the managed intake service from an OpenTelemetry agent OpenTelemetry collector.
+
 ::::
+

solutions/observability/apm/opentelemetry-intake-api.md

@@ -1,6 +1,8 @@
 ---
 mapped_pages:
   - https://www.elastic.co/guide/en/observability/current/apm-api-otlp.html
+applies_to:
+  stack:
 ---
 
 # OpenTelemetry intake API [apm-api-otlp]
@@ -29,6 +31,6 @@ APM Server supports two OTLP communication protocols on the same port:
 | OTLP logs intake | `/v1/logs` |
 
 ::::{tip}
-See our [OpenTelemetry documentation](https://elastic.github.io/opentelemetry/) to learn how to send data to the APM Server.
+See our OpenTelemetry documentation to learn how to send data to the APM Server from an [OpenTelemetry agent](/solutions/observability/apm/upstream-opentelemetry-collectors-language-sdks.md#apm-instrument-apps-otel) or [OpenTelemetry collector](/solutions/observability/apm/upstream-opentelemetry-collectors-language-sdks.md#apm-connect-open-telemetry-collector).
 ::::
 

solutions/observability/apm/resource-attributes.md

@@ -0,0 +1,48 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/observability/current/apm-open-telemetry-resource-attributes.html
+  - https://www.elastic.co/guide/en/serverless/current/observability-apm-agents-opentelemetry-resource-attributes.html
+applies_to:
+  stack:
+  serverless:
+---
+
+# Resource attributes [apm-open-telemetry-resource-attributes]
+
+A resource attribute is a key/value pair containing information about the entity producing telemetry. Resource attributes are mapped to Elastic Common Schema (ECS) fields like `service.*`, `cloud.*`, `process.*`, etc. These fields describe the service and the environment that the service runs in.
+
+The examples shown here set the Elastic (ECS) `service.environment` field for the resource, i.e. service, that is producing trace events. Note that Elastic maps the OpenTelemetry `deployment.environment` field to the ECS `service.environment` field on ingestion.
+
+**OpenTelemetry agent**
+
+Use the `OTEL_RESOURCE_ATTRIBUTES` environment variable to pass resource attributes at process invocation.
+
+```bash
+export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production
+```
+
+**OpenTelemetry collector**
+
+Use the [resource processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourceprocessor) to set or apply changes to resource attributes.
+
+```yaml
+...
+processors:
+  resource:
+    attributes:
+    - key: deployment.environment
+      action: insert
+      value: production
+...
+```
+
+::::{tip}
+Need to add event attributes instead? Use attributes—​not to be confused with resource attributes—​to add data to span, log, or metric events. Attributes can be added as a part of the OpenTelemetry instrumentation process or with the [attributes processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/attributesprocessor).
+
+::::
+
+% Stateful only after this?
+
+Elastic integrates with OpenTelemetry, allowing you to reuse your existing instrumentation to easily send observability data to the {{stack}}.
+
+For more information on how to combine Elastic and OpenTelemetry, see [OpenTelemetry integration](/solutions/observability/apm/use-opentelemetry-with-apm.md).

solutions/observability/apm/traces.md

@@ -37,6 +37,12 @@ In this example, Elastic’s Ruby agent communicates with Elastic’s Java agent
 :alt: How traceparent propagation works
 :::
 
+In this example, Elastic’s Ruby agent communicates with OpenTelemetry’s Java agent. Both support the `traceparent` header, and trace data is successfully propagated.
+
+:::{image} /solutions/images/observability-dt-trace-ex2.png
+:alt: How traceparent propagation works
+:::
+
 In this example, the trace meets a piece of middleware that doesn’t propagate the `traceparent` header. The distributed trace ends and any further communication will result in a new trace.
 
 :::{image} /solutions/images/observability-dt-trace-ex3.png

solutions/observability/apm/transaction-sampling.md

@@ -84,6 +84,23 @@ In the example in *Figure 4*, `Service A` and `Service B` are Elastic-monitored
 :title: Using the `restart` trace continuation strategy
 :::
 
+### OpenTelemetry [_opentelemetry]
+
+Head-based sampling is implemented directly in the APM agents and SDKs. The sample rate must be propagated between services and the managed intake service in order to produce accurate metrics.
+
+OpenTelemetry offers multiple samplers. However, most samplers do not propagate the sample rate. This results in inaccurate span-based metrics, like APM throughput, latency, and error metrics.
+
+For accurate span-based metrics when using head-based sampling with OpenTelemetry, you must use a [consistent probability sampler](https://opentelemetry.io/docs/specs/otel/trace/tracestate-probability-sampling/). These samplers propagate the sample rate between services and the managed intake service, resulting in accurate metrics.
+
+::::{note}
+OpenTelemetry does not offer consistent probability samplers in all languages. OpenTelemetry users should consider using tail-based sampling instead.
+
+Refer to the documentation of your favorite OpenTelemetry agent or SDK for more information on the availability of consistent probability samplers.
+
+::::
+
+% Stateful only for tail-based sampling
+
 ## Tail-based sampling [apm-tail-based-sampling]
 
 ```{applies_to}
@@ -116,6 +133,12 @@ In this example, `Service A` initiates four transactions. If our sample rate is
 :alt: Distributed tracing and tail based sampling example one
 :::
 
+### OpenTelemetry with tail-based sampling [_opentelemetry_with_tail_based_sampling]
+
+Tail-based sampling is implemented entirely in APM Server, and will work with traces sent by either Elastic APM agents or OpenTelemetry SDKs.
+
+Due to [OpenTelemetry tail-based sampling limitations](/solutions/observability/apm/limitations.md#apm-open-telemetry-tbs) when using [tailsamplingprocessor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/tailsamplingprocessor), we recommend using APM Server tail-based sampling instead.
+
 ### Tail-based sampling performance and requirements [_tail_based_sampling_performance_and_requirements]
 
 Tail-based sampling (TBS), by definition, requires storing events locally temporarily, such that they can be retrieved and forwarded when a sampling decision is made.