Skip to content

Make environment variable propagation operational guidance non-normative#5165

Merged
pellared merged 13 commits into
open-telemetry:mainfrom
pellared:env-car-operational-doc
Jun 23, 2026
Merged

Make environment variable propagation operational guidance non-normative#5165
pellared merged 13 commits into
open-telemetry:mainfrom
pellared:env-car-operational-doc

Conversation

@pellared

@pellared pellared commented Jun 18, 2026

Copy link
Copy Markdown
Member

Motivation

The Environment Variables as Context Propagation Carriers specification used normative wording in the "Operational Guidance" section for application-level usage advice, such as when applications read environment variables or how they prepare child process environments.

That made the section read like it was adding specification requirements for application behavior, even though the intent is guidance for how environment variable carriers are typically used.

This came up in discussion with @dashpole and also I mentioned this in open-telemetry/opentelemetry-go-contrib#9112 (comment)

Here is a simple example how the languages can be document some operational guidance: open-telemetry/opentelemetry-go-contrib@5b1606f

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Pull request overview

This PR updates the Environment Variables as Context Propagation Carriers specification to ensure the “Operational Guidance” section reads as non-normative application guidance rather than introducing new normative requirements.

Changes:

  • Reword “Operational Guidance” recommendations to avoid normative RFC 2119 keywords for application behavior.
  • Clarify process-startup immutability and child-process environment handling guidance.
  • Add a changelog entry documenting the clarification.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File Description
specification/context/env-carriers.md Rewords the Operational Guidance section to be non-normative guidance and adjusts phrasing around immutability, process spawning, and security.
CHANGELOG.md Adds an Unreleased changelog entry noting the operational guidance is non-normative and should be documented by language implementations.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread specification/context/env-carriers.md Outdated
Comment thread specification/context/env-carriers.md Outdated
Comment thread specification/context/env-carriers.md Outdated
pellared and others added 2 commits June 18, 2026 15:46
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
@pellared
pellared marked this pull request as ready for review June 18, 2026 13:47
@pellared
pellared requested a review from a team as a code owner June 18, 2026 13:47
Comment thread specification/context/env-carriers.md Outdated
@pellared
pellared requested a review from MrAlias June 18, 2026 19:09

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

Comment thread specification/context/env-carriers.md
Comment thread specification/context/env-carriers.md Outdated
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Comment thread specification/context/env-carriers.md
@pellared

Copy link
Copy Markdown
Member Author

@open-telemetry/semconv-cicd-approvers, @maryliag, @jack-berg, @marcalff, @xrmx, @pichlermarc, PTAL

@MrAlias MrAlias left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Thanks for continuing to tighten this. I think two issues remain: the lower-case should wording still makes the guidance read like RFC 2119 terms were only de-capitalized, and the rewrite drops the normative boundary around language implementations spawning processes. I left targeted suggestions on the specific changed ranges.

Comment thread specification/context/env-carriers.md
Comment thread specification/context/env-carriers.md Outdated
Comment thread specification/context/env-carriers.md Outdated
Comment thread specification/context/env-carriers.md Outdated
Comment thread specification/context/env-carriers.md Outdated
Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com>
@pellared
pellared requested a review from MrAlias June 22, 2026 19:58
@pellared
pellared added this pull request to the merge queue Jun 23, 2026
Merged via the queue into open-telemetry:main with commit 1342728 Jun 23, 2026
8 of 9 checks passed
@pellared
pellared deleted the env-car-operational-doc branch June 23, 2026 11:06
pellared added a commit to pellared/opentelemetry-specification that referenced this pull request Jun 23, 2026
…on carriers (open-telemetry#5166)

Address
open-telemetry#5165 (comment)

This PR cleans up the non-normative implementation guidance for
environment variable propagation carriers.

It keeps the guidance aligned with open-telemetry#5144 by removing
implementation-shape bullets whose `Getter` guidance was no longer
accurate after the specification was updated to require environment
variable carriers to read and return only normalized environment
variable names.

### Motivation

open-telemetry#5144 changed the expected behavior for environment variable carrier
lookup: `Get` normalizes the key requested by the propagator and reads
that normalized environment variable name directly, while `Keys` returns
only names that are already normalized.

After that change, review feedback in open-telemetry#5165 called out that the previous
supplementary guidance could be misleading. In particular, the `Getter`
bullet suggested creating an in-memory copy of all current environment
variables before reading context from it. That pattern can imply full
environment enumeration, which is exactly what open-telemetry#5144 was intended to
avoid for extraction. It also made the guidance sound more prescriptive
than it needed to be, even though different language implementations
expose environment-variable propagation through different carrier,
getter, setter, or helper shapes.

### Changes

- Rename "Supplementary Guidelines" to "Implementation Guidelines" so
the section title better matches its purpose.
- Update the implementation-shape bullets to follow open-telemetry#5144 and remove
whose remaining content repeated the surrounding text.
- Reword "Examples" to "Example implementations".
- Add the OpenTelemetry JavaScript implementation to the example list.

### Notes

This does not add new normative requirements. It only updates
explanatory guidance so it does not contradict or over-specify the
behavior introduced by open-telemetry#5144.
@carlosalberto carlosalberto mentioned this pull request Jul 8, 2026
pull Bot pushed a commit to CodeWeaver13/opentelemetry-specification that referenced this pull request Jul 10, 2026
### Context

- Clarify that environment variable propagation operational guidance is
  non-normative and should be documented by language implementations.

([open-telemetry#5165](open-telemetry#5165))
- Clean up implementation guidelines for environment variable
propagation
  carriers.

([open-telemetry#5166](open-telemetry#5166))
- Remove caching behavior suggestions for environment variable
propagation
  carrier implementations.

([open-telemetry#5179](open-telemetry#5179))
- Mark "Environment Variables as Context Propagation Carriers" as
Release
  Candidate.

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

### Traces

- Amend the description of Composite/Composable samplers.

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

### Logs

- Add ETW (Event Tracing for Windows) example mapping to the logs data
  model appendix, including the ETW level to `SeverityNumber` mapping.

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

### Profiles

- Add Profiles data model (data-model.md).

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

### Supplementary Guidelines

- Add non-normative supplementary guidelines for SDK self-observability.

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

### OTEPs

- Add OTEP proposing a central OpenTelemetry benchmarks repository.

([open-telemetry#5118](open-telemetry#5118))
- Introduce Policies into the specification.

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

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

8 participants