Skip to content

Remove misleading implementation guidance for context propagation via environment variables#5003

Merged
jack-berg merged 7 commits intoopen-telemetry:mainfrom
pellared:env-var-one-approach
Apr 13, 2026
Merged

Remove misleading implementation guidance for context propagation via environment variables#5003
jack-berg merged 7 commits intoopen-telemetry:mainfrom
pellared:env-var-one-approach

Conversation

@pellared
Copy link
Copy Markdown
Member

@pellared pellared commented Apr 1, 2026 •
edited
Loading

Per #4961 (comment) and other similar feedback

Changes

This PR removes the non-normative guidance that presented a dedicated EnvironmentContextPropagator as a first-class alternative for environment variable context propagation.

The supplementary guidance now describes the carrier-based pattern directly:

The previous (removed) “Approach 1” guidance suggested that a dedicated environment-variable-specific propagator was a viable recommendation. Based on the discussion in #4961, that approach is seen as misleading/buggy:

  • the environment variable carrier should remain format-agnostic
  • propagator-specific behavior belongs in the propagator, not in the carrier
  • the Swift example did not reflect the direction we want to recommend here

This change keeps the document aligned with the carrier-based model used by the referenced implementations.

Side note

I think we can look into stabilization of this document after this PR is merged. I plan to create a stabilization issue and update the compliance matrix.

@pellared pellared changed the title Remove misleading alternative guidance for env var context propagation Remove misleading implementation guidance for context propagation via environment variables Apr 1, 2026
@pellared
Copy link
Copy Markdown
Member Author

pellared commented Apr 1, 2026

CC @open-telemetry/semconv-cicd-approvers
and @dashpole @marcalff @reyang @jack-berg @MrAlias who reviewed the previous PRs

@pellared pellared marked this pull request as ready for review April 1, 2026 16:18
@pellared pellared requested review from a team as code owners April 1, 2026 16:18
@pellared pellared added enhancement New feature or request spec:context Related to the specification/context directory labels Apr 1, 2026
@pellared pellared mentioned this pull request Apr 1, 2026
Open
@jack-berg jack-berg added this pull request to the merge queue Apr 13, 2026
Merged via the queue into open-telemetry:main with commit dc33969 Apr 13, 2026
8 of 9 checks passed
@pellared pellared deleted the env-var-one-approach branch April 13, 2026 14:27
@carlosalberto carlosalberto mentioned this pull request Apr 15, 2026
Merged
pull Bot pushed a commit to MC-MAGA/opentelemetry-specification that referenced this pull request Apr 20, 2026
@carlosalberto @jack-berg
Release 1.56 (open-telemetry#5029)
50149c2 
### Context

- Align environment variable context propagation name restrictions with
POSIX.1-2024
  and define normalization behavior.

([open-telemetry#4944](open-telemetry#4944))
- Decouple the responsibilities of the environment variable propagation
carrier.

([open-telemetry#4961](open-telemetry#4961))
- Remove misleading implementation approach the environment variable
propagation.

([open-telemetry#5003](open-telemetry#5003))
- Change Environment Variables as Context Propagation Carriers document
status to Beta.

([open-telemetry#5020](open-telemetry#5020))

### Traces

- Stabilize Tracer `enabled` operation

([open-telemetry#4941](open-telemetry#4941))
- Stabilize `AlwaysRecord` sampler.

([open-telemetry#4934](open-telemetry#4934))

### Metrics

- Add development `maxExportBatchSize` parameter to Periodic exporting
MetricReader.

([open-telemetry#4895](open-telemetry#4895))

### Logs

- Add event to span event bridge.

([open-telemetry#5006](open-telemetry#5006))

### Resource

- Clarify that a Resource describes the observed entity, not the
component
  that technically emits telemetry.

([open-telemetry#4905](open-telemetry#4905))

### Compatibility

- Deprecate OpenTracing compatibility requirements in the specification.

([open-telemetry#4938](open-telemetry#4938))
- Stabilize sections of Prometheus and OpenMetrics Compatibility.
- Stabilize Prometheus Classic Histogram to OTLP Explicit Histogram
transformation.

([open-telemetry#4874](open-telemetry#4874))
  - Stabilize Prometheus Timestamp and Start timestamp transformation.

([open-telemetry#4953](open-telemetry#4953))
- Clarify Prometheus Native Histogram to OTLP Exponential Histogram
conversion,
add conversion rules for Native Histograms with Custom Buckets (NHCB) to
OTLP
    Histogram.

([open-telemetry#4898](open-telemetry#4898))
  - Stabilize Prometheus Dropped Types transformation.

([open-telemetry#4952](open-telemetry#4952))
- Stabilize OpenTelemetry Attributes to Prometheus labels
transformation.

([open-telemetry#4963](open-telemetry#4963))
- Stabilize Prometheus Exemplar to OpenTelemetry Exemplar
transformation.

([open-telemetry#4962](open-telemetry#4962))
  - Stabilize Prometheus Metadata transformation.

([open-telemetry#4954](open-telemetry#4954))
- Stabilize OpenTelemetry Metric Metadata to Prometheus metric metadata.

([open-telemetry#4966](open-telemetry#4966))
- Stabilize OpenTelemetry Exemplar to Prometheus Exemplar
transformation.

([open-telemetry#4964](open-telemetry#4964))
- Stabilize sections of Prometheus Metrics Exporter.
  - Stabilize host configuration.

([open-telemetry#5025](open-telemetry#5025))

### SDK Configuration

- Declarative configuration: add in-development guidance for exposing
the
  effective `Resource` returned by `Create`.

([open-telemetry#4949](open-telemetry#4949))
- Require spec changes to consider declarative config schema

([open-telemetry#4916](open-telemetry#4916))
- Add strict YAML parsing guidance to configuration supplementary
guidelines.

([open-telemetry#4878](open-telemetry#4878))

### OTEPs

- Process Context: Sharing Resource Attributes with External Readers.

([open-telemetry#4719](open-telemetry#4719))
- Support multiple Resources within an SDK.

([open-telemetry#4665](open-telemetry#4665))

---------

Co-authored-by: Jack Berg <34418638+jack-berg@users.noreply.github.com>
@pellared pellared mentioned this pull request Apr 21, 2026
Merged
hilmarf pushed a commit to apeirora/opentelemetry-specification that referenced this pull request Apr 22, 2026
@carlosalberto @jack-berg @hilmarf
Release 1.56 (open-telemetry#5029)
68fba8a 
### Context

- Align environment variable context propagation name restrictions with
POSIX.1-2024
  and define normalization behavior.

([open-telemetry#4944](open-telemetry#4944))
- Decouple the responsibilities of the environment variable propagation
carrier.

([open-telemetry#4961](open-telemetry#4961))
- Remove misleading implementation approach the environment variable
propagation.

([open-telemetry#5003](open-telemetry#5003))
- Change Environment Variables as Context Propagation Carriers document
status to Beta.

([open-telemetry#5020](open-telemetry#5020))

### Traces

- Stabilize Tracer `enabled` operation

([open-telemetry#4941](open-telemetry#4941))
- Stabilize `AlwaysRecord` sampler.

([open-telemetry#4934](open-telemetry#4934))

### Metrics

- Add development `maxExportBatchSize` parameter to Periodic exporting
MetricReader.

([open-telemetry#4895](open-telemetry#4895))

### Logs

- Add event to span event bridge.

([open-telemetry#5006](open-telemetry#5006))

### Resource

- Clarify that a Resource describes the observed entity, not the
component
  that technically emits telemetry.

([open-telemetry#4905](open-telemetry#4905))

### Compatibility

- Deprecate OpenTracing compatibility requirements in the specification.

([open-telemetry#4938](open-telemetry#4938))
- Stabilize sections of Prometheus and OpenMetrics Compatibility.
- Stabilize Prometheus Classic Histogram to OTLP Explicit Histogram
transformation.

([open-telemetry#4874](open-telemetry#4874))
  - Stabilize Prometheus Timestamp and Start timestamp transformation.

([open-telemetry#4953](open-telemetry#4953))
- Clarify Prometheus Native Histogram to OTLP Exponential Histogram
conversion,
add conversion rules for Native Histograms with Custom Buckets (NHCB) to
OTLP
    Histogram.

([open-telemetry#4898](open-telemetry#4898))
  - Stabilize Prometheus Dropped Types transformation.

([open-telemetry#4952](open-telemetry#4952))
- Stabilize OpenTelemetry Attributes to Prometheus labels
transformation.

([open-telemetry#4963](open-telemetry#4963))
- Stabilize Prometheus Exemplar to OpenTelemetry Exemplar
transformation.

([open-telemetry#4962](open-telemetry#4962))
  - Stabilize Prometheus Metadata transformation.

([open-telemetry#4954](open-telemetry#4954))
- Stabilize OpenTelemetry Metric Metadata to Prometheus metric metadata.

([open-telemetry#4966](open-telemetry#4966))
- Stabilize OpenTelemetry Exemplar to Prometheus Exemplar
transformation.

([open-telemetry#4964](open-telemetry#4964))
- Stabilize sections of Prometheus Metrics Exporter.
  - Stabilize host configuration.

([open-telemetry#5025](open-telemetry#5025))

### SDK Configuration

- Declarative configuration: add in-development guidance for exposing
the
  effective `Resource` returned by `Create`.

([open-telemetry#4949](open-telemetry#4949))
- Require spec changes to consider declarative config schema

([open-telemetry#4916](open-telemetry#4916))
- Add strict YAML parsing guidance to configuration supplementary
guidelines.

([open-telemetry#4878](open-telemetry#4878))

### OTEPs

- Process Context: Sharing Resource Attributes with External Readers.

([open-telemetry#4719](open-telemetry#4719))
- Support multiple Resources within an SDK.

([open-telemetry#4665](open-telemetry#4665))

---------

Co-authored-by: Jack Berg <34418638+jack-berg@users.noreply.github.com>
cijothomas pushed a commit to cijothomas/opentelemetry-specification that referenced this pull request Apr 22, 2026
@pellared
remove propagation wrapper wording (open-telemetry#5041)
7e8720b 
This removes "(or propagator wrapper)".

Leftover after
open-telemetry#5003
(we agreed that a wrapper/decorator implementation is invalid).
hilmarf pushed a commit to apeirora/opentelemetry-specification that referenced this pull request Apr 23, 2026
@pellared @hilmarf
remove propagation wrapper wording (open-telemetry#5041)
92417db 
This removes "(or propagator wrapper)".

Leftover after
open-telemetry#5003
(we agreed that a wrapper/decorator implementation is invalid).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@tsloughter tsloughter tsloughter approved these changes

@codeboten codeboten codeboten approved these changes

@carlosalberto carlosalberto carlosalberto approved these changes

@dashpole dashpole dashpole approved these changes

@kamphaus kamphaus kamphaus approved these changes

@jack-berg jack-berg jack-berg approved these changes

+1 more reviewer

@adrielp adrielp adrielp approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

enhancement New feature or request spec:context Related to the specification/context directory

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

8 participants

@pellared @tsloughter @codeboten @carlosalberto @dashpole @kamphaus @adrielp @jack-berg