Skip to content

Align environment variable propagation names with POSIX and define normalization rules#4944

Merged
reyang merged 9 commits intoopen-telemetry:mainfrom
pellared:env-car-normalization
Mar 18, 2026
Merged

Align environment variable propagation names with POSIX and define normalization rules#4944
reyang merged 9 commits intoopen-telemetry:mainfrom
pellared:env-car-normalization

Conversation

@pellared
Copy link
Copy Markdown
Member

@pellared pellared commented Mar 13, 2026 •
edited
Loading

This PR aligns environment variable context propagation naming with POSIX.1-2024 and defines normalization rules for propagation keys.

Fixes #4914

Prototype open-telemetry/opentelemetry-go-contrib#8678

Note that the changes are in a document which has status "Alpha".

Motivation

The current text refers to platform-specific restrictions but does not define how invalid propagation keys should be handled. In particular, it does not clearly address cases such as:

Changes

Propagation keys MUST be normalized to valid environment variable names by:

  • converting ASCII letters to uppercase
  • replacing disallowed characters with _
  • prefixing _ when the name would otherwise begin with a digit

Benefits

  • Defines deterministic behavior across SDKs
  • Improves interoperability between propagators (e.g., W3C and B3)
  • Reduces implementation ambiguity
  • Aligns with POSIX.1-2024

@pellared pellared changed the title Align environment variable context propagation name restrictions with POSIX.1-2024 Align environment variable propagation names with POSIX and define normalization rules Mar 13, 2026
@pellared
Copy link
Copy Markdown
Member Author

pellared commented Mar 13, 2026

CC @open-telemetry/semconv-cicd-approvers

@pellared pellared marked this pull request as ready for review March 13, 2026 20:15
@pellared pellared requested review from a team as code owners March 13, 2026 20:15
MrAlias
MrAlias approved these changes Mar 13, 2026
View reviewed changes
Comment thread specification/context/env-carriers.md Outdated
@pellared @MrAlias
Update specification/context/env-carriers.md
757c39d 
Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com>
@pellared pellared added enhancement New feature or request spec:context Related to the specification/context directory labels Mar 13, 2026
marcalff
marcalff approved these changes Mar 14, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@marcalff marcalff left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

kamphaus
kamphaus reviewed Mar 17, 2026
View reviewed changes
Comment thread specification/context/env-carriers.md
marcalff
marcalff approved these changes Mar 17, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@marcalff marcalff left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

reyang
reyang reviewed Mar 18, 2026
View reviewed changes
Comment thread specification/context/env-carriers.md
reyang
reyang approved these changes Mar 18, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@reyang reyang left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM with a non-blocking clarification question.

@reyang reyang enabled auto-merge March 18, 2026 16:47
@reyang reyang added this pull request to the merge queue Mar 18, 2026
Merged via the queue into open-telemetry:main with commit 704bee6 Mar 18, 2026
7 of 8 checks passed
@pellared pellared deleted the env-car-normalization branch March 18, 2026 16:55
@pellared pellared mentioned this pull request Mar 18, 2026
Merged
This was referenced Mar 30, 2026
Open
Merged
github-merge-queue Bot pushed a commit that referenced this pull request Apr 1, 2026
@pellared @reyang
Decouple the responsibilities of the environment variable propagation…
e482a39 
… carrier (#4961)

Follows
#4944

Per
#4944 (comment)

Per
#4961 (comment)

## Changes

Decouple the responsibilities of the environment variable propagation
carrier from concerns that are:
1. specific to individual propagators used with it, 
2. already handled by the underlying environment variable APIs (error
handling and limits when setting values).

---------

Co-authored-by: Reiley Yang <reyang@microsoft.com>
@carlosalberto carlosalberto mentioned this pull request Apr 20, 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>
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@kamphaus kamphaus kamphaus approved these changes

@reyang reyang reyang approved these changes

@jsuereth jsuereth jsuereth approved these changes

@MrAlias MrAlias MrAlias approved these changes

@marcalff marcalff marcalff approved these changes

+1 more reviewer

@Kielek Kielek Kielek approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

@jsuereth jsuereth

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.

Refine key normalization for Environment Variables Context Propagation Carrier

7 participants

@pellared @jsuereth @MrAlias @Kielek @kamphaus @marcalff @reyang