envoyproxy / envoyproxy/envoy

OpenTelemetry code mutualization: strategy for centralization and protocol support

Open
#41,010 6 comments 0 reactions 0 assignees View on GitHub
area/opentelemetry design proposal no stalebot
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.