Make environment variable propagation operational guidance non-normative#5165
Conversation
There was a problem hiding this comment.
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.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
|
@open-telemetry/semconv-cicd-approvers, @maryliag, @jack-berg, @marcalff, @xrmx, @pichlermarc, PTAL |
MrAlias
left a comment
There was a problem hiding this comment.
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.
Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com>
…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.
### 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>
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