elastic / elastic/docs-content
Add a unified "Switch to OpenTelemetry" migration how-to guide (SDK + Collector/Agent)
- 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.