elastic / elastic/docs-content

Add a unified "Switch to OpenTelemetry" migration how-to guide (SDK + Collector/Agent)

Open
#7,321 1 comment 0 reactions 1 assignee Claimed by @alexandra5000 View on GitHub
Team:SKI
Dominant language
No language data
Stars
47
Forks
261
Avg merge
3d 12h
Merged PRs (30d)
116

Description

Where: Observability -› Get started -› OpenTelemetry (TBD)

There is no cross-cutting guide for existing Elastic users moving to OTel. App-instrumentation migration exists
only as per-language SDK pages (and RUM has none, .NET also covers upstream-OTel while java/node/python don't), and the collection-side path (Elastic Agent/Beats to EDOT Collector) is preview-level (`elastic-agent//hybrid-agent-beats-receivers.md`). Existing users can't find a single place that tells them what changes, what to keep, and where to start.

Create a prescriptive how-to page, `get-started/opentelemetry/switch-to-otel.md`, with two clearly separated sub-pages that link out to the detailed pages:

**Sub-page 1: Migrate app instrumentation (classic APM agents → EDOT SDKs)**:
- Per-language: link to `elastic-otel-{dotnet,java,node,python}//reference/edot-*/migration.md`.
- Call out the gaps explicitly: **RUM has no migration path yet**; only .NET documents upstream-OTel→EDOT.
- Shared caveats: don't run both agents at once; config/attribute changes; span compression & central config
limitations; EDOT-native vs ECS data streams and partial query compatibility (`opentelemetry//reference/compatibility/data-streams.md`).

**Sub-page 2: Migrate collection (Beats / Elastic Agent → EDOT Collector)**:
- Frame the key fact: **Elastic Agent already runs the EDOT Collector under the hood** for many users this is a
configuration/transform issue, not a full replace. Link Fleet pages: `docs-content//reference/fleet/{elastic-agent-as-otel-collector,otel-agent,otel-agent-transform,add-otel-collector}.md`.
- Beats users: link the (currently preview, out-of-nav) `elastic-agent//hybrid-agent-beats-receivers.md` (beat receivers / `elastic-agent otel` mode) and note preview status + delivery-guarantee caveats.
- Component migration for existing EDOT Collector configs: `elastic-agent//reference/edot-collector/components/migrate-components.md`.
- When to keep classic collection (integrations/dashboards, ingest pipelines) -> `.../compatibility/limitations.md`.

**Draft outline:**
1. Who this is for + choose your case (decision tree: instrumenting apps vs collecting infra/logs).
2. What changes after you switch: data model (OTel-native vs ECS), UI/app implications, what you gain/lose.
3. Verify + troubleshooting.

**Source pages to link (but not duplicate):**
- SDK migration: `elastic-otel-{dotnet,java,node,python}//reference/edot-*/migration.md`
- Data model comparison: `opentelemetry//reference/compatibility/data-streams.md`, `opentelemetry//reference/data-streams.md`
- Limitations / when to keep classic: `opentelemetry//reference/compatibility/limitations.md`
- Agent-as-EDOT-Collector: `docs-content//reference/fleet/elastic-agent-as-otel-collector.md` (+ otel-agent, transform)
- Beats/Agent → OTel: `elastic-agent//hybrid-agent-beats-receivers.md`
- Component migration: `elastic-agent//reference/edot-collector/components/migrate-components.md`

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.