Skip to content
Merged
Show file tree
Hide file tree
Changes from 3 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

### Metrics
Expand All @@ -26,6 +30,10 @@ release.

### Baggage

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

### Resource

### Profiles
Expand Down
49 changes: 49 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 end-user for receiving the set context from the SDK and
passing it to it's own process spawning mechanism. The SDK SHOULD NOT handle
spawning processes for the end-user.

#### Security

Expand All @@ -149,3 +158,43 @@ 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 SDKs 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 [Swift SDK][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`

SDKs 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 end-user for them to use when spawning processes.

### Common Behaviors

Both approaches achieve the same outcome while offering different developer
experiences. SDK implementers 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
users can pass to their process spawning libraries

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