Skip to content
Merged
Show file tree
Hide file tree
Changes from 10 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,10 @@ release.

### Context

- Add Supplementary Guidance for environment variables as context carrier
specification.
([#4548](https://github.com/open-telemetry/opentelemetry-specification/pull/4548))

### Traces

- Define sampling threshold field in OpenTelemetry TraceState; define the behavior
Expand All @@ -32,6 +36,10 @@ release.

### Baggage

- Add Supplementary Guidance for environment variables as context carrier
specification.
([#4548](https://github.com/open-telemetry/opentelemetry-specification/pull/4548))

### Profiles

### Resource
Expand Down
50 changes: 50 additions & 0 deletions specification/context/env-carriers.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@
<details>
<summary>Table of Contents</summary>

<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->

<!-- toc -->

- [Overview](#overview)
Expand All @@ -19,6 +21,10 @@
+ [Process Spawning](#process-spawning)
+ [Security](#security)
+ [Case Sensitivity](#case-sensitivity)
- [Supplementary Guidelines](#supplementary-guidelines)
* [Approach 1: Providing a dedicated `EnvironmentContextPropagator`](#approach-1-providing-a-dedicated-environmentcontextpropagator)
* [Approach 2: Using the carriers directly through `Setters` and `Getters`](#approach-2-using-the-carriers-directly-through-setters-and-getters)
* [Common Behaviors](#common-behaviors)

<!-- tocstop -->

Expand Down Expand Up @@ -129,6 +135,9 @@ When spawning child processes:
- When spawning multiple child processes with different contexts or baggage,
each child SHOULD receive its own copy of the environment variables with
appropriate information.
- The onus is on the application owner for receiving the set context from the
SDK and passing it to its own process spawning mechanism. The language
implementations MUST NOT handle spawning processes.

#### Security

Expand All @@ -149,3 +158,44 @@ Windows.
- For maximum compatibility, implementations MUST:
- Use uppercase names consistently (`TRACEPARENT` not `TraceParent`).
- Use the canonical case when setting environment variables.

## Supplementary Guidelines

> **IMPORTANT**: This section is non-normative and provides implementation
> guidance only. It does not add requirements to the specification.

Language implementations of OpenTelemetry have flexibility in how they implement
environment variable context propagation. Two main approaches have been
identified as viable.

### Approach 1: Providing a dedicated `EnvironmentContextPropagator`

SDKs can create a dedicated propagator for environment variables. For example,
the [OTel Swift][swift] implements a custom `EnvironmentContextPropagator` that
handles the environment-specific logic internally, in essence decorating the
`TextMapPropagator`.

### Approach 2: Using the carriers directly through `Setters` and `Getters`

Language implementations can use the existing `TextMapPropagator` interface directly with
environment-specific carriers. Go and Python SDKs follow this pattern by
providing:

- `EnvironmentGetter` - creates an in-memory copy of the current environment
variables and reads context from that copy.
- `EnvironmentSetter` - writes context to a dictionary/map and provides the
dictionary/map to the application owner for them to use when spawning processes.

### Common Behaviors

Both approaches achieve the same outcome while offering different developer
experiences. Language implementations may choose either approach based on their
language's idioms and ecosystem conventions. The behaviors in both approaches
are the same in that they:

1. **Extract context**: Read from environment variables and delegate to the
configured `TextMapPropagator` (e.g., W3C, B3) for parsing
2. **Inject context**: Return a dictionary/map of environment variables that
application owners can pass to their process spawning libraries

[swift]: https://github.com/open-telemetry/opentelemetry-swift/blob/main/Sources/OpenTelemetrySdk/Trace/Propagation/EnvironmentContextPropagator.swift
Loading