OpenTelemetry code mutualization: strategy for centralization and protocol support
- Dominant language
- C++
- Stars
- 28.9k
- Forks
- 5.6k
- Avg merge
- 1d 22h
- Merged PRs (30d)
- 430
Description
## Background
Envoy's OpenTelemetry support is expanding, but code is currently spread across several domain-specific extensions:
- **Tracing**: `extensions/tracers/opentelemetry/`, `extensions/tracers/zipkin/`, etc.
- **Propagators**: `extensions/propagators/{w3c,b3,xray,skywalking}/`
- **Metrics/Logging**: (planned/future work)
Recent work—see [issue #41009](https://github.com/envoyproxy/envoy/issues/41009) and open PRs such as [#40989](https://github.com/envoyproxy/envoy/pull/40989)—is focused on refactoring propagators into dedicated modules with unified constants and APIs. However, OpenTelemetry logic (constants, helpers, resource attributes, protocol parsing) remains duplicated or fragmented across the codebase.
## Intention
This issue proposes to:
- **Centralize OpenTelemetry code** in a shared directory (e.g., `source/common/opentelemetry/`) for reusable constants, helpers, and adapters.
- **Refactor domain-specific extensions** (tracing, propagators, metrics, logging) to use this shared code, improving maintainability and extensibility.
- **Align with OpenTelemetry conventions** for propagator configuration (e.g., support for `OTEL_PROPAGATORS` env var), resource attributes, and exporter endpoints where practical.
- **Document the relationship** between standardized OTEL protocols (W3C, B3, X-Ray) and nonstandard protocols (e.g., SkyWalking), especially for composite support.
- **Explicitly reference open works**: [#41009](https://github.com/envoyproxy/envoy/issues/41009) and PRs such as [#40989](https://github.com/envoyproxy/envoy/pull/40989) as the starting point for propagator mutualization. These are not merged yet, so details may evolve.
## SkyWalking Support
- **SkyWalking Propagator:**
At this time, Envoy will not pursue a custom implementation of the SkyWalking propagator.
Instead, we will wait for official support for SkyWalking from the OpenTelemetry project before integrating it into Envoy.
- This ensures protocol alignment, reduces maintenance burden, and avoids fragmentation.
- If/when OpenTelemetry supports SkyWalking natively, Envoy will revisit integration and update documentation accordingly.
## Proposed Strategy
1. **Centralized Organization**
- Create `source/common/opentelemetry/` for reusable constants, helpers, and adapters.
- Move protocol constants (header names, limits) and utility functions from propagators/tracers into this directory after open PRs are merged.
2. **Domain Extension Refactoring**
- Update all existing and future extensions (tracers, propagators, metrics, logging) to consume shared OpenTelemetry code.
- Minimize duplication and ensure clear cross-referencing in docs and code comments.
3. **OpenTelemetry Environment Variable Support**
- Evaluate supporting `OTEL_PROPAGATORS`, `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_EXPORTER_OTLP_ENDPOINT`, etc., as configuration fallbacks.
- Document precedence and mapping between Envoy config and OTEL_* env vars.
4. **Nonstandard Protocols and Composite Support**
- For protocols not standardized by OpenTelemetry (e.g., SkyWalking), document their status in Envoy as "pending official OpenTelemetry support."
- In composite propagators, clearly document which protocols are supported and any configuration differences from OpenTelemetry SDKs.
5. **Design Documentation**
- Update README files and developer docs to clarify the new structure, mutualization goals, and links to key implementation issues and PRs ([#41009](https://github.com/envoyproxy/envoy/issues/41009), [#40989](https://github.com/envoyproxy/envoy/pull/40989)).
## Questions for Review
- Is `source/common/opentelemetry/` the right location/naming for shared code?
- Which OTEL_* env vars should be supported, and by which extensions?
- How should future metrics/logging features consume this shared code?
- Are there other opportunities for mutualization or interoperability?
- How should Envoy track and integrate future OpenTelemetry protocol support (e.g., for SkyWalking)?
## Relevant Links
- [Refactor trace propagator infrastructure for unified header management and composable injection (#41009)](https://github.com/envoyproxy/envoy/issues/41009)
- [Open PR: Move propagator constants infrastructure to separate extension (#40989)](https://github.com/envoyproxy/envoy/pull/40989)
- [OpenTelemetry SDK configuration](https://opentelemetry.io/docs/languages/sdk-configuration/general/)
- [Current Envoy propagator modules](https://github.com/envoyproxy/envoy/tree/main/source/extensions/propagators)
- [OpenTelemetry C++ SDK](https://github.com/open-telemetry/opentelemetry-cpp)
---
**Maintainers and contributors are invited to discuss the intention and strategy outlined above before detailed implementation proceeds.**
Contributor guide
Assessment
This issue has not been assessed yet.