Skip to content

Clarify environment carrier key normalization behavior#5102

Open
pellared wants to merge 4 commits into
open-telemetry:mainfrom
pellared:clarify-env-car
Open

Clarify environment carrier key normalization behavior#5102
pellared wants to merge 4 commits into
open-telemetry:mainfrom
pellared:clarify-env-car

Conversation

@pellared
Copy link
Copy Markdown
Member

@pellared pellared commented May 18, 2026

Towards #5040

Changes

Clarifies the environment variable propagation carrier key normalization requirements:

  • Set writes values using normalized key names.
  • Get normalizes both the requested propagator key and carrier keys before matching.
  • Keys returns normalized key names.

Motivation

The existing text defined how key names are normalized, but it did not explicitly say where that normalization applies. This PR clarifies that normalization is part of the carrier behavior for writing, reading, and listing keys.

This follows the robustness principle: carriers write the normalized representation, while getters can still accept a non-normalized environment variable key if it normalizes to the requested propagation key. For example, a non-normalized traceparent environment variable can still be used by the propagation getter when matching TRACEPARENT.

This retrospects #4944 (comment) now that implementations are in place.

Implementation references

Related Java discussion: open-telemetry/opentelemetry-java#8233 (comment)

@pellared
Copy link
Copy Markdown
Member Author

pellared commented May 18, 2026

CC @open-telemetry/semconv-cicd-approvers @jack-berg @marcalff @Joibel

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

spec:context Related to the specification/context directory

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants