remove outdated APM Server references from upstream OTel collector/SDK page by alexandra5000 · Pull Request #6880 · elastic/docs-content

alexandra5000 · 2026-06-09T15:11:22Z

NOTE: This PR is AI-generated for the purpose of testing some workflows etc.
NOTE 2: The PR has been reviewed both by the docs-review workflow and my human 👀 . I have also applied some additional changes. The final change is reasonable and closes an existing issue.

Context

Flagged in elastic/opentelemetry-dev#801 by @hegerchr: "I think the content is a bit outdated as I do see APM server mentioned. We expect our users to use an EDOT collector or an EDOT-like custom collector or send the data to the managed OTLP endpoint."

Closes #6706

Summary

Replaces APM Server-specific language with mOTLP endpoint terminology.

More specifically:

Updates example env var names (ELASTIC_APM_SERVER_ENDPOINT → ELASTIC_OTLP_ENDPOINT, ELASTIC_APM_SECRET_TOKEN → ELASTIC_SECRET_TOKEN, ELASTIC_APM_API_KEY → ELASTIC_API_KEY) to remove the misleading APM-specific prefix
Fixes the serverless Collector config: footnote 5 previously showed elastic-apm-server:8200 as an example; now correctly points to the Managed OTLP endpoint
Fixes the serverless SDK config: endpoint placeholder updated from apm_server_url:8200 to your-motlp-endpoint
Scopes the "Proxy requests to APM Server" section to stack: ga only (was incorrectly using invalid product: preview syntax)
Fixes four instances of invalid {applies_to}\ product: preview\ inline syntax → correctly scoped stack: preview or serverless: preview

🤖 Generated with Claude Code

…page Replaces APM Server-specific language with generic Elastic endpoint terminology. Updates env var examples (ELASTIC_APM_* → ELASTIC_OTLP_*), fixes invalid `product: preview` applies_to syntax, and aligns the serverless section to reference the Managed OTLP endpoint instead of elastic-apm-server:8200. Closes elastic#6706 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions · 2026-06-09T15:12:06Z

Elastic Docs AI PR menu

Check the box to run an AI review for this pull request.

Review docs changes (docs-review). Status: queued.

Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team.

github-actions · 2026-06-09T15:13:26Z

🔍 Preview links for changed docs

solutions/observability/apm/opentelemetry/upstream-opentelemetry-collectors-language-sdks.md

github-actions · 2026-06-09T15:13:30Z

Elastic Docs Style Checker (Vale)

Summary: 1 warning, 2 suggestions found

⚠️ Warnings (1): Fix when the suggestion improves clarity or correctness.

File	Line	Rule	Message
solutions/observability/apm/opentelemetry/upstream-opentelemetry-collectors-language-sdks.md	267	Elastic.Spelling	'Muxing' is a possible misspelling.

💡 Suggestions (2): Optional style improvements. Apply when helpful.

File	Line	Rule	Message
solutions/observability/apm/opentelemetry/upstream-opentelemetry-collectors-language-sdks.md	144	Elastic.Wordiness	Consider using 'all' instead of 'all of '.
solutions/observability/apm/opentelemetry/upstream-opentelemetry-collectors-language-sdks.md	144	Elastic.Wordiness	Consider using 'also' instead of 'In addition'.

The Vale linter checks documentation changes against the Elastic Docs style guide. To use Vale locally or report issues, refer to Elastic style guide for Vale.

alexandra5000 · 2026-06-09T15:19:14Z

/docs-review

alexandra5000

Docs review summary

Focus areas

Style and clarity: Two e.g. instances in changed lines (prohibited Latin abbreviation → for example,). One code comment introduces a minor auth-format ambiguity (see inline). Remaining prose is clear and well-updated.
Jargon: ECH is spelled out on first use in footnote 5 — correct. No unexplained internal abbreviations in changed content.
Frontmatter and applies_to: All four inline applies_to fixes are correct and verified against the published schema. product: preview (no subkey) was invalid; replacements with stack: preview, serverless: preview, and stack: ga are all valid.
Content type fit: How-to structure intact. No regressions.
Parent issue satisfaction: Substantially satisfied. Issue #6706 asked to investigate outdated APM Server references. The PR correctly updates configuration examples, env var names, footnotes, and example placeholders. The "Proxy requests to APM Server" section is intentionally preserved — it's genuinely about APM Server proxy setup.

Nits

Footnote 7 in both sections also uses documented [here](...) — "here" is non-descriptive link text. Suggest: documented in the [OpenTelemetry Collector environment variables reference](...).
Changed callout reads "...is currently in technical preview." Style discourages "currently" in static docs. Suggest: "...is in technical preview."

Reviewed with /docs-review (local fork-friendly adaptation)

jmikell821

Love all the fixes, I just had one super tiny nit that Vale also recommended. Great work!

jmikell821 · 2026-06-17T17:04:38Z


 ::::{important}
-When using the OpenTelemetry Collector, send data through the [`OTLP` exporter](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/otlphttpexporter). Using other methods, like the [`elasticsearch` exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/elasticsearchexporter), bypasses all of the validation and data processing that Elastic performs. In addition, your data will not be viewable in your Observability project if you use the `elasticsearch` exporter.
+When using the OpenTelemetry Collector, send data through the [`OTLP` exporter](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/otlphttpexporter). Using other methods, like the [`elasticsearch` exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/elasticsearchexporter), bypasses all of the validation and data processing that Elastic performs. In addition, your data will not be viewable in your {{observability}} project if you use the `elasticsearch` exporter.


Suggested change

When using the OpenTelemetry Collector, send data through the [`OTLP` exporter](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/otlphttpexporter). Using other methods, like the [`elasticsearch` exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/elasticsearchexporter), bypasses all of the validation and data processing that Elastic performs. In addition, your data will not be viewable in your {{observability}} project if you use the `elasticsearch` exporter.

When using the OpenTelemetry Collector, send data through the [`OTLP` exporter](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/otlphttpexporter). Using other methods, like the [`elasticsearch` exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/elasticsearchexporter), bypasses all the validation and data processing that Elastic performs. In addition, your data will not be viewable in your {{observability}} project if you use the `elasticsearch` exporter.

hegerchr

I spotted a few things to discuss.

hegerchr · 2026-06-18T07:40:53Z

@@ -75,13 +75,13 @@ service:
 ```

 1. The receivers, like the [OTLP receiver](https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver), that forward data emitted by APM agents, or the [host metrics receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/hostmetricsreceiver).


Suggested change

1. The receivers, like the [OTLP receiver](https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver), that forward data emitted by APM agents, or the [host metrics receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/hostmetricsreceiver).

1. The receivers, like the [OTLP receiver](https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver), that forward data emitted by OpenTelemetry SDKs, or the [host metrics receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/hostmetricsreceiver).

hegerchr · 2026-06-18T07:42:39Z


 1. The receivers, like the [OTLP receiver](https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver), that forward data emitted by APM agents, or the [host metrics receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/hostmetricsreceiver).
-2. Use the [Batch processor](https://github.com/open-telemetry/opentelemetry-collector/blob/main/processor/batchprocessor/README.md) and the [memory limiter processor](https://github.com/open-telemetry/opentelemetry-collector/blob/main/processor/memorylimiterprocessor/README.md). For more information, see [recommended processors](https://github.com/open-telemetry/opentelemetry-collector/blob/main/processor/README.md#recommended-processors).
+2. Use the [Batch processor](https://github.com/open-telemetry/opentelemetry-collector/blob/main/processor/batchprocessor/README.md) and the [memory limiter processor](https://github.com/open-telemetry/opentelemetry-collector/blob/main/processor/memorylimiterprocessor/README.md). For more information, refer to [recommended processors](https://github.com/open-telemetry/opentelemetry-collector/blob/main/processor/README.md#recommended-processors).


Should we mention why the Batch processor and the memory limiter are useful?

hegerchr · 2026-06-18T07:48:32Z

-7. Environment-specific configuration parameters can be conveniently passed in as environment variables documented [here](https://opentelemetry.io/docs/collector/configuration/#environment-variables) (e.g. `ELASTIC_APM_SERVER_ENDPOINT` and `ELASTIC_APM_SECRET_TOKEN`).
-8. To send OpenTelemetry logs to {{stack}} version 8.0+, declare a `logs` pipeline. {applies_to}`product: preview`
+4. Elastic endpoint configuration. Elastic supports a ProtoBuf payload via both the OTLP protocol over gRPC transport [(OTLP/gRPC)](https://opentelemetry.io/docs/specs/otlp/#otlpgrpc) and the OTLP protocol over HTTP transport [(OTLP/HTTP)](https://opentelemetry.io/docs/specs/otlp/#otlphttp). To learn more about these exporters, refer to the OpenTelemetry Collector documentation: [OTLP/HTTP Exporter](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/otlphttpexporter) or [OTLP/gRPC exporter](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/otlpexporter). When adding an endpoint to an existing configuration an optional name component can be added, like `otlp/elastic`, to distinguish endpoints as described in the [OpenTelemetry Collector Configuration Basics](https://opentelemetry.io/docs/collector/configuration/#basics).
+5. Hostname and port of the Elastic endpoint. For self-managed deployments, use your {{apm-server}} address (for example, `apm-server:8200`). For {{ech}} (ECH), use the [Managed OTLP endpoint](opentelemetry://reference/motlp/index.md).


Why do we expect users to send data to the APM Server for self-managed deployments? Shouldn't we recommend to send the data to an Elastic Agent with an OTLP endpoint?

hegerchr · 2026-06-18T07:50:45Z

@@ -150,117 +150,121 @@ When using the OpenTelemetry Collector, send data through the [`OTLP` exporter](
 The following instructions show how to send data directly from a contrib OpenTelemetry SDK to Elastic, which is appropriate when getting started. However, sending data from an OpenTelemetry SDK to the OpenTelemetry Collector is preferred, as the Collector processes and exports data to Elastic. Read more about when and how to use a collector in the [OpenTelemetry documentation](https://opentelemetry.io/docs/collector/#when-to-use-a-collector).


Suggested change

The following instructions show how to send data directly from a contrib OpenTelemetry SDK to Elastic, which is appropriate when getting started. However, sending data from an OpenTelemetry SDK to the OpenTelemetry Collector is preferred, as the Collector processes and exports data to Elastic. Read more about when and how to use a collector in the [OpenTelemetry documentation](https://opentelemetry.io/docs/collector/#when-to-use-a-collector).

The following instructions show how to send data directly from an OpenTelemetry SDK to Elastic, which is appropriate when getting started. However, sending data from an OpenTelemetry SDK to the OpenTelemetry Collector is preferred, as the Collector processes and exports data to Elastic. Read more about when and how to use a collector in the [OpenTelemetry documentation](https://opentelemetry.io/docs/collector/#when-to-use-a-collector).

IIUC the example above for self-managed deployments does not show the use of the elasticsearch exporter.

hegerchr · 2026-06-18T07:55:56Z

 export OTEL_RESOURCE_ATTRIBUTES=service.name=checkoutService,service.version=1.1,deployment.environment=production
-export OTEL_EXPORTER_OTLP_ENDPOINT=https://apm_server_url:8200
-export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer an_apm_secret_token"
+export OTEL_EXPORTER_OTLP_ENDPOINT=https://elastic-endpoint:8200


8200 is the port number of the APM Server. OpenTelemetry collectors or the managed OTLP endpoint listens on 4317 (grpc) and 4318 (HTTP)

hegerchr · 2026-06-18T09:21:26Z


 `OTEL_EXPORTER_OTLP_ENDPOINT`
-:   APM Server URL. The host and port that APM Server listens for events on.
+:   Elastic endpoint URL. For self-managed deployments, use your {{apm-server}} address (for example, `https://elastic-endpoint:8200`). For {{ech}} (ECH), use the [Managed OTLP endpoint](opentelemetry://reference/motlp/index.md).


Having apm-server address here looks misaligned with the rest. It's either another OTel Collector or the managed OTLP endpoint that makes sense.

hegerchr · 2026-06-18T09:24:56Z

 export OTEL_RESOURCE_ATTRIBUTES=service.name=checkoutService,service.version=1.1,deployment.environment=production
-export OTEL_EXPORTER_OTLP_ENDPOINT=https://apm_server_url:8200
-export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey an_apm_api_key"
+export OTEL_EXPORTER_OTLP_ENDPOINT=https://your-motlp-endpoint


We should explicitly include the port (e.g., :4317 or :4318) here.

hegerchr · 2026-06-18T09:30:50Z

+You are now ready to collect traces and [metrics](/solutions/observability/apm/opentelemetry/collect-metrics.md), and then [verify](/solutions/observability/apm/opentelemetry/collect-metrics.md#apm-open-telemetry-verify-metrics) and [visualize](/solutions/observability/apm/opentelemetry/collect-metrics.md#apm-open-telemetry-visualize) them.

-## Proxy requests to APM Server [apm-open-telemetry-proxy-apm]
+## Proxy requests to {{apm-server}} [apm-open-telemetry-proxy-apm]


Do we need to update this section and describe how to do it with a collector?

hegerchr · 2026-06-18T09:32:21Z

-    # Elastic APM server https endpoint without the "https://" prefix
-    endpoint: "${env:ELASTIC_APM_SERVER_ENDPOINT}" <5> <7>
+    # Elastic endpoint without the "https://" prefix
+    endpoint: "${env:ELASTIC_OTLP_ENDPOINT}" <5> <7>


Should we explicitly include port numbers here?

alexandra5000 requested a review from a team as a code owner June 9, 2026 15:11

github-actions Bot deployed to docs-preview June 9, 2026 15:14 View deployment

alexandra5000 commented Jun 10, 2026

View reviewed changes

Additional updates and fixes

5ed7d86

github-actions Bot deployed to docs-preview June 16, 2026 12:32 View deployment

Merge branch 'main' into upstream-otel-apm-server-refs

66fe24a

alexandra5000 requested a review from hegerchr June 16, 2026 12:33

github-actions Bot deployed to docs-preview June 16, 2026 12:36 View deployment

Update note to remove ambiguity

01e9b33

github-actions Bot deployed to docs-preview June 17, 2026 15:53 View deployment

jmikell821 approved these changes Jun 17, 2026

View reviewed changes

hegerchr reviewed Jun 18, 2026

View reviewed changes

		@@ -75,13 +75,13 @@ service:
		```

		1. The receivers, like the [OTLP receiver](https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver), that forward data emitted by APM agents, or the [host metrics receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/hostmetricsreceiver).

		@@ -150,117 +150,121 @@ When using the OpenTelemetry Collector, send data through the [`OTLP` exporter](
		The following instructions show how to send data directly from a contrib OpenTelemetry SDK to Elastic, which is appropriate when getting started. However, sending data from an OpenTelemetry SDK to the OpenTelemetry Collector is preferred, as the Collector processes and exports data to Elastic. Read more about when and how to use a collector in the [OpenTelemetry documentation](https://opentelemetry.io/docs/collector/#when-to-use-a-collector).

Conversation

alexandra5000 commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Context

Summary

Uh oh!

github-actions Bot commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Elastic Docs AI PR menu

Uh oh!

github-actions Bot commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

github-actions Bot commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Elastic Docs Style Checker (Vale)

Uh oh!

alexandra5000 commented Jun 9, 2026

Uh oh!

alexandra5000 left a comment

Choose a reason for hiding this comment

Docs review summary

Focus areas

Nits

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jmikell821 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hegerchr left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

alexandra5000 commented Jun 9, 2026 •

edited

Loading

github-actions Bot commented Jun 9, 2026 •

edited

Loading

github-actions Bot commented Jun 9, 2026 •

edited

Loading

github-actions Bot commented Jun 9, 2026 •

edited

Loading