From d3afcb4717ce5e51ddba052c68063b14f07930fe Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Fri, 21 Mar 2025 10:05:43 -0400 Subject: [PATCH 01/12] [chore] more adjustments --- specification/context/env-carriers.md | 217 ++++++++++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 specification/context/env-carriers.md diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md new file mode 100644 index 00000000000..84fc3a14af4 --- /dev/null +++ b/specification/context/env-carriers.md @@ -0,0 +1,217 @@ +# Environment Variables as Context Propagation Carriers + +**Status**: [Experimental](../document-status.md) + +
+Table of Contents + + + +- [Overview](#overview) +- [Environment Variable Propagator](#environment-variable-propagator) + * [Standard Environment Variable Names](#standard-environment-variable-names) + * [Environment Variable Format Restrictions](#environment-variable-format-restrictions) + + [Key Format Restrictions](#key-format-restrictions) + + [Value Format Restrictions](#value-format-restrictions) + + [Size Limitations](#size-limitations) + * [Implementation Details](#implementation-details) + + [EnvVarTextMapPropagator](#envvartextmappropagator) + + [EnvVarGetter](#envvargetter) + - [Get](#get) + - [Keys](#keys) + - [GetAll](#getall) + + [EnvVarSetter](#envvarsetter) + - [Set](#set) + * [Operational Guidance](#operational-guidance) + + [Environment Variable Immutability](#environment-variable-immutability) + + [Process Spawning](#process-spawning) + + [Security Considerations](#security-considerations) +- [Cross-Platform Considerations](#cross-platform-considerations) + * [Case Sensitivity](#case-sensitivity) + * [UNIX-Specific Considerations](#unix-specific-considerations) + * [Windows-Specific Considerations](#windows-specific-considerations) + + + +
+ +## Overview + +In systems where processes communicate without using network protocols, context +propagation can be achieved using environment variables as carriers. This +specification extends the [API Propagators](../context/api-propagators.md) to +define how the +[TextMapPropagator](../context/api-propagators.md#textmap-propagator) can be +used with environment variables. + +Common scenarios where this is useful include: + +- ETL pipelines +- Batch processing systems +- CI/CD environments +- Command-line tools + +## Environment Variable Propagator + +### Standard Environment Variable Names + +The OpenTelemetry supported specifications for context propagation SHOULD be +mapped to environment variables. It is RECOMMENDED to use the [W3C Trace Context](https://www.w3.org/TR/trace-context/) +and [W3C Baggage](https://www.w3.org/TR/baggage/) specifications mapped to +environment variables names. + +When using the W3C Trace Context and Baggage propagators with environment +variables, the following standard environment variable names MUST be used: + +| Context Information | Environment Variable | W3C Header Equivalent | +|---------------------|----------------------|------------------------| +| Trace Context | `TRACEPARENT` | `traceparent` | +| Trace State | `TRACESTATE` | `tracestate` | +| Baggage | `BAGGAGE` | `baggage` | + +Implementations MAY support additional propagation formats and SHOULD provide +configuration options to override the default environment variable names to +support legacy systems. + +### Environment Variable Format Restrictions + +#### Key Format Restrictions + +Environment variable names used for context propagation: + +- SHOULD use uppercase letters, digits, and underscores for maximum + cross-platform compatibility +- MUST NOT include characters forbidden in environment variables per + platform-specific restrictions +- SHOULD follow naming conventions that align with the propagation format + specification they're implementing (e.g., `TRACEPARENT` for W3C trace context) + +#### Value Format Restrictions + +Environment variable values used for context propagation: + +- MUST only use characters that are valid in HTTP header fields per [RFC + 9110](https://tools.ietf.org/html/rfc9110) +- MUST follow the format requirements of the specific propagation protocol + (e.g., W3C Trace Context specification for `TRACEPARENT` values) +- SHOULD NOT contain sensitive information + +#### Size Limitations + +Implementations SHOULD follow platform-specific environment variable size +limitations: + +- Windows: Maximum 32,767 characters for name=value pairs according to + [Microsoft Documentation](https://docs.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-setenvironmentvariable) +- UNIX: System-dependent limits exist and are typically lower than Windows. + +Implementations SHOULD handle truncation gracefully when size limits are +exceeded. + +### Implementation Details + +#### EnvVarTextMapPropagator + +The `EnvPropagator` implements the `TextMapPropagator` interface to enable +context propagation through environment variables. It uses specialized `EnvGetter` and +`EnvSetter` implementations that work with environment variables. + +#### EnvGetter + +The `EnvGetter` implements the TextMapPropagator's Getter interface for +environment variables. + +##### Get + +The `Get` function MUST return the value of the specified environment variable +or return null if the variable doesn't exist. + +Required arguments: +- The carrier of propagation fields (typically the environment variable store) +- The key of the field + +The `Get` function MUST handle case-sensitivity appropriately across platforms. +On Windows, where environment variables are case-insensitive, the getter SHOULD +perform case-insensitive lookups. + +##### Keys + +The `Keys` function MUST return the list of all environment variable names in +the carrier. + +Required arguments: +- The carrier of the propagation fields (typically the environment variable + store) + +##### GetAll + +The `GetAll` function MUST return all values of the given propagation key, if +supported. It SHOULD return them in the same order as they appear in the +carrier. If the key doesn't exist, it SHOULD return an empty collection. + +Required arguments: +- The carrier of propagation fields (typically the environment variable store) +- The key of the field + +#### EnvSetter + +The `EnvSetter` implements the TextMapPropagator's Setter interface for environment variables. + +##### Set + +The `Set` function MUST set or replace an environment variable with the given value. + +Required arguments: +- The carrier of propagation fields (typically the environment variable store) +- The key of the field +- The value to set + +The `Set` function SHOULD convert environment variable names to uppercase for consistency across platforms. + +### Operational Guidance + +#### Environment Variable Immutability + +Once set for a process, environment variables SHOULD be treated as immutable within that process: + +- Environment variables SHOULD only be modified before spawning child processes +- Applications SHOULD NOT modify context-related environment variables during execution, as this can lead to inconsistent trace contexts +- If modification is required, applications SHOULD create a new environment variables dictionary with the updated values for the child process + +#### Process Spawning + +When spawning child processes: + +- Parent processes SHOULD inject context into environment variables before spawning child processes +- Child processes SHOULD extract context from environment variables at startup +- When spawning multiple child processes with different contexts, each child SHOULD receive its own copy of the environment variables with appropriate context information + +#### Security Considerations + +Environment variables are generally accessible to all code running within a process: + +- Implementations SHOULD NOT store sensitive information in context propagation via environment variables +- Applications running in multi-tenant environments SHOULD be aware that environment variables may be visible to other processes or users with appropriate permissions +- When using environment variables for context propagation, consider the security implications of propagating trace context across trust boundaries + +## Cross-Platform Considerations + +### Case Sensitivity + +- Environment variable names are case-sensitive on UNIX but case-insensitive on Windows +- For maximum compatibility, implementations SHOULD: + - Use uppercase names consistently (`TRACEPARENT` not `TraceParent`) + - Handle case-insensitivity correctly when reading environment variables on Windows + - Always use the canonical case when setting environment variables + +### UNIX-Specific Considerations + +- UNIX systems generally use uppercase for environment variables by convention +- Environment variables in UNIX are typically inherited by child processes unless explicitly cleared +- The maximum size of environment variables varies by system and should be considered when implementing + +### Windows-Specific Considerations + +- Windows environment variables are case-insensitive but case-preserving +- Windows has a larger maximum environment variable size limit (32,767 characters) +- Some Windows APIs may have different behavior regarding environment variable inheritance in child processes From 92f73c11742ea9e4d7d24deed3c2e87d4c40544e Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Fri, 21 Mar 2025 23:02:53 -0400 Subject: [PATCH 02/12] [chore] slight adjustments to the wording of the specification --- specification/context/env-carriers.md | 44 +++++++++++++++++---------- 1 file changed, 28 insertions(+), 16 deletions(-) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index 84fc3a14af4..e2302ae8bdb 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -37,31 +37,36 @@ ## Overview -In systems where processes communicate without using network protocols, context -propagation can be achieved using environment variables as carriers. This -specification extends the [API Propagators](../context/api-propagators.md) to -define how the -[TextMapPropagator](../context/api-propagators.md#textmap-propagator) can be -used with environment variables. +Environment variables provide a mechanism to propagate context and baggage +information across process boundaries when network protocols are not +applicable. This specification extends the [API Propagators](../context/api-propagators.md) +to define how the [TextMapPropagator](../context/api-propagators.md#textmap-propagator) +can be used with environment variables. -Common scenarios where this is useful include: +Common systems where context propagation via environment variables is useful +include: -- ETL pipelines - Batch processing systems - CI/CD environments - Command-line tools -## Environment Variable Propagator +## Propagator Mechanisms + +Propagating context via environment variables involves reading and writing to +environment variables. A `TextMapPropagator` SHOULD be used alongside its +normal `Get`, `Set`, and `Inject` functionality as described in the [API +Propagators](../context/api-propagators.md) specification. ### Standard Environment Variable Names -The OpenTelemetry supported specifications for context propagation SHOULD be -mapped to environment variables. It is RECOMMENDED to use the [W3C Trace Context](https://www.w3.org/TR/trace-context/) -and [W3C Baggage](https://www.w3.org/TR/baggage/) specifications mapped to -environment variables names. +It is RECOMMENDED to use the [W3C Trace +Context](https://www.w3.org/TR/trace-context/) and [W3C +Baggage](https://www.w3.org/TR/baggage/) specifications mapped to environment +variables names for consistent context propagation. When using the W3C Trace Context and Baggage propagators with environment -variables, the following standard environment variable names MUST be used: +variables, the following translated standard environment variable names SHOULD +be used: | Context Information | Environment Variable | W3C Header Equivalent | |---------------------|----------------------|------------------------| @@ -70,8 +75,7 @@ variables, the following standard environment variable names MUST be used: | Baggage | `BAGGAGE` | `baggage` | Implementations MAY support additional propagation formats and SHOULD provide -configuration options to override the default environment variable names to -support legacy systems. +configuration options to override the default environment variable. ### Environment Variable Format Restrictions @@ -215,3 +219,11 @@ Environment variables are generally accessible to all code running within a proc - Windows environment variables are case-insensitive but case-preserving - Windows has a larger maximum environment variable size limit (32,767 characters) - Some Windows APIs may have different behavior regarding environment variable inheritance in child processes + + +## Implementation Guidelines + +- SDKs SHOULD automatically detect and extract context from environment variables when initializing +- When spawning child processes, SDKs SHOULD automatically inject current context into the child's environment +- Implementations MUST provide mechanisms to disable automatic propagation when needed +- The presence of these variables SHOULD NOT override explicitly configured context From 46def4dc42c37eaca0d36f8b2223dace34b03d81 Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Sat, 22 Mar 2025 09:42:48 -0400 Subject: [PATCH 03/12] [chore] additional changes --- specification/context/env-carriers.md | 166 +++++++------------------- 1 file changed, 43 insertions(+), 123 deletions(-) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index e2302ae8bdb..c339f7ffa85 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -8,28 +8,17 @@ - [Overview](#overview) -- [Environment Variable Propagator](#environment-variable-propagator) - * [Standard Environment Variable Names](#standard-environment-variable-names) - * [Environment Variable Format Restrictions](#environment-variable-format-restrictions) - + [Key Format Restrictions](#key-format-restrictions) - + [Value Format Restrictions](#value-format-restrictions) +- [Propagator Mechanisms](#propagator-mechanisms) + * [Environment Variable Names](#environment-variable-names) + * [Format Restrictions](#format-restrictions) + + [Name Restrictions](#name-restrictions) + + [Value Restrictions](#value-restrictions) + [Size Limitations](#size-limitations) - * [Implementation Details](#implementation-details) - + [EnvVarTextMapPropagator](#envvartextmappropagator) - + [EnvVarGetter](#envvargetter) - - [Get](#get) - - [Keys](#keys) - - [GetAll](#getall) - + [EnvVarSetter](#envvarsetter) - - [Set](#set) * [Operational Guidance](#operational-guidance) + [Environment Variable Immutability](#environment-variable-immutability) + [Process Spawning](#process-spawning) - + [Security Considerations](#security-considerations) -- [Cross-Platform Considerations](#cross-platform-considerations) - * [Case Sensitivity](#case-sensitivity) - * [UNIX-Specific Considerations](#unix-specific-considerations) - * [Windows-Specific Considerations](#windows-specific-considerations) + + [Security](#security) + * [Case Sensitivity](#case-sensitivity) @@ -40,8 +29,9 @@ Environment variables provide a mechanism to propagate context and baggage information across process boundaries when network protocols are not applicable. This specification extends the [API Propagators](../context/api-propagators.md) -to define how the [TextMapPropagator](../context/api-propagators.md#textmap-propagator) -can be used with environment variables. +to define how the +[TextMapPropagator](../context/api-propagators.md#textmap-propagator) can be +used with environment variables. Common systems where context propagation via environment variables is useful include: @@ -54,10 +44,10 @@ include: Propagating context via environment variables involves reading and writing to environment variables. A `TextMapPropagator` SHOULD be used alongside its -normal `Get`, `Set`, and `Inject` functionality as described in the [API +normal `Get`, `Set`, `Extract`, and `Inject` functionality as described in the [API Propagators](../context/api-propagators.md) specification. -### Standard Environment Variable Names +### Environment Variable Names It is RECOMMENDED to use the [W3C Trace Context](https://www.w3.org/TR/trace-context/) and [W3C @@ -77,9 +67,9 @@ be used: Implementations MAY support additional propagation formats and SHOULD provide configuration options to override the default environment variable. -### Environment Variable Format Restrictions +### Format Restrictions -#### Key Format Restrictions +#### Name Restrictions Environment variable names used for context propagation: @@ -90,7 +80,7 @@ Environment variable names used for context propagation: - SHOULD follow naming conventions that align with the propagation format specification they're implementing (e.g., `TRACEPARENT` for W3C trace context) -#### Value Format Restrictions +#### Value Restrictions Environment variable values used for context propagation: @@ -112,118 +102,48 @@ limitations: Implementations SHOULD handle truncation gracefully when size limits are exceeded. -### Implementation Details - -#### EnvVarTextMapPropagator - -The `EnvPropagator` implements the `TextMapPropagator` interface to enable -context propagation through environment variables. It uses specialized `EnvGetter` and -`EnvSetter` implementations that work with environment variables. - -#### EnvGetter - -The `EnvGetter` implements the TextMapPropagator's Getter interface for -environment variables. - -##### Get - -The `Get` function MUST return the value of the specified environment variable -or return null if the variable doesn't exist. - -Required arguments: -- The carrier of propagation fields (typically the environment variable store) -- The key of the field - -The `Get` function MUST handle case-sensitivity appropriately across platforms. -On Windows, where environment variables are case-insensitive, the getter SHOULD -perform case-insensitive lookups. - -##### Keys - -The `Keys` function MUST return the list of all environment variable names in -the carrier. - -Required arguments: -- The carrier of the propagation fields (typically the environment variable - store) - -##### GetAll - -The `GetAll` function MUST return all values of the given propagation key, if -supported. It SHOULD return them in the same order as they appear in the -carrier. If the key doesn't exist, it SHOULD return an empty collection. - -Required arguments: -- The carrier of propagation fields (typically the environment variable store) -- The key of the field - -#### EnvSetter - -The `EnvSetter` implements the TextMapPropagator's Setter interface for environment variables. - -##### Set - -The `Set` function MUST set or replace an environment variable with the given value. - -Required arguments: -- The carrier of propagation fields (typically the environment variable store) -- The key of the field -- The value to set - -The `Set` function SHOULD convert environment variable names to uppercase for consistency across platforms. - ### Operational Guidance #### Environment Variable Immutability -Once set for a process, environment variables SHOULD be treated as immutable within that process: +Once set for a process, environment variables SHOULD be treated as immutable +within that process: -- Environment variables SHOULD only be modified before spawning child processes -- Applications SHOULD NOT modify context-related environment variables during execution, as this can lead to inconsistent trace contexts -- If modification is required, applications SHOULD create a new environment variables dictionary with the updated values for the child process +- Environment variables SHOULD only be modified before the creation of one or + more child processes occur. +- Applications SHOULD NOT modify context-related environment variables during + execution within the environment in which they were created, as this can lead + to inconsistent trace contexts. +- If modification is required, applications SHOULD create a new environment + variables dictionary with the updated values for the child process. #### Process Spawning When spawning child processes: -- Parent processes SHOULD inject context into environment variables before spawning child processes -- Child processes SHOULD extract context from environment variables at startup -- When spawning multiple child processes with different contexts, each child SHOULD receive its own copy of the environment variables with appropriate context information +- Parent processes SHOULD inject context into environment variables before + spawning child processes. +- Child processes SHOULD extract context from environment variables at startup. +- When spawning multiple child processes with different contexts or baggage, + each child SHOULD receive its own copy of the environment variables with + appropriate information. -#### Security Considerations +#### Security -Environment variables are generally accessible to all code running within a process: +Environment variables are generally accessible to all code running within a +process and with the correct permissions, can be accessed from other processes. -- Implementations SHOULD NOT store sensitive information in context propagation via environment variables -- Applications running in multi-tenant environments SHOULD be aware that environment variables may be visible to other processes or users with appropriate permissions -- When using environment variables for context propagation, consider the security implications of propagating trace context across trust boundaries +- Implementations SHOULD NOT store sensitive information in environment + variables. +- Applications running in multi-tenant environments SHOULD be aware that + environment variables may be visible to other processes or users with + appropriate permissions. -## Cross-Platform Considerations +#### Case Sensitivity -### Case Sensitivity +Environment variable names are case-sensitive on UNIX and case-insensitive on +Windows. -- Environment variable names are case-sensitive on UNIX but case-insensitive on Windows - For maximum compatibility, implementations SHOULD: - - Use uppercase names consistently (`TRACEPARENT` not `TraceParent`) - - Handle case-insensitivity correctly when reading environment variables on Windows - - Always use the canonical case when setting environment variables - -### UNIX-Specific Considerations - -- UNIX systems generally use uppercase for environment variables by convention -- Environment variables in UNIX are typically inherited by child processes unless explicitly cleared -- The maximum size of environment variables varies by system and should be considered when implementing - -### Windows-Specific Considerations - -- Windows environment variables are case-insensitive but case-preserving -- Windows has a larger maximum environment variable size limit (32,767 characters) -- Some Windows APIs may have different behavior regarding environment variable inheritance in child processes - - -## Implementation Guidelines - -- SDKs SHOULD automatically detect and extract context from environment variables when initializing -- When spawning child processes, SDKs SHOULD automatically inject current context into the child's environment -- Implementations MUST provide mechanisms to disable automatic propagation when needed -- The presence of these variables SHOULD NOT override explicitly configured context + - Use uppercase names consistently (`TRACEPARENT` not `TraceParent`). + - Use the canonical case when setting environment variables. From 88f9d2eab44523b661d3e89a3566528e58e32fdb Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Sat, 22 Mar 2025 09:53:14 -0400 Subject: [PATCH 04/12] [chore] update changelog --- CHANGELOG.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index d5aa8bbab53..c7ad518dd62 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,9 @@ release. ### Context +- Add context propagation through Environment Variables specification. + ([#4454](https://github.com/open-telemetry/opentelemetry-specification/pull/4454)) + ### Traces - Clarify STDOUT exporter format is unspecified. @@ -26,6 +29,9 @@ release. ### Baggage +- Add context (baggage) propagation through Environment Variables specification. + ([#4454](https://github.com/open-telemetry/opentelemetry-specification/pull/4454)) + ### Resource ### Profiles From 1fbea35d05b4daf480f4101d68856f14d97b4999 Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Sat, 22 Mar 2025 09:55:29 -0400 Subject: [PATCH 05/12] [chore] update toc --- specification/context/env-carriers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index c339f7ffa85..55c4afce952 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -18,7 +18,7 @@ + [Environment Variable Immutability](#environment-variable-immutability) + [Process Spawning](#process-spawning) + [Security](#security) - * [Case Sensitivity](#case-sensitivity) + + [Case Sensitivity](#case-sensitivity) From 6a30e75c62b09a9723e4909b3c4c077235296e9f Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Sat, 22 Mar 2025 23:15:59 -0400 Subject: [PATCH 06/12] Update specification/context/env-carriers.md Co-authored-by: Christophe Kamphaus --- specification/context/env-carriers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index 55c4afce952..13a465cdb81 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -52,7 +52,7 @@ Propagators](../context/api-propagators.md) specification. It is RECOMMENDED to use the [W3C Trace Context](https://www.w3.org/TR/trace-context/) and [W3C Baggage](https://www.w3.org/TR/baggage/) specifications mapped to environment -variables names for consistent context propagation. +variable names for consistent context propagation. When using the W3C Trace Context and Baggage propagators with environment variables, the following translated standard environment variable names SHOULD From 713d1bf816659f7ff8e4e4bf37d94329b7ac336d Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Tue, 25 Mar 2025 10:44:19 -0400 Subject: [PATCH 07/12] [chore] minor updates to wording --- specification/context/env-carriers.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index 13a465cdb81..53852433cd6 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -109,11 +109,10 @@ exceeded. Once set for a process, environment variables SHOULD be treated as immutable within that process: -- Environment variables SHOULD only be modified before the creation of one or - more child processes occur. -- Applications SHOULD NOT modify context-related environment variables during - execution within the environment in which they were created, as this can lead - to inconsistent trace contexts. +- Applications SHOULD read context-related environment variables during + initialization. +- Applications SHOULD NOT modify environment variables on initialization of + environment in which the parent process exists. - If modification is required, applications SHOULD create a new environment variables dictionary with the updated values for the child process. From 8571b891a31d939af560eb5d00228ed6e37d4f38 Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Tue, 25 Mar 2025 15:13:01 -0400 Subject: [PATCH 08/12] Apply suggestions from code review Co-authored-by: Reiley Yang Co-authored-by: Christophe Kamphaus --- specification/context/env-carriers.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index 53852433cd6..5427aaade82 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -59,10 +59,10 @@ variables, the following translated standard environment variable names SHOULD be used: | Context Information | Environment Variable | W3C Header Equivalent | -|---------------------|----------------------|------------------------| -| Trace Context | `TRACEPARENT` | `traceparent` | -| Trace State | `TRACESTATE` | `tracestate` | -| Baggage | `BAGGAGE` | `baggage` | +|---------------------|----------------------|-----------------------| +| Trace Context | `TRACEPARENT` | `traceparent` | +| Trace State | `TRACESTATE` | `tracestate` | +| Baggage | `BAGGAGE` | `baggage` | Implementations MAY support additional propagation formats and SHOULD provide configuration options to override the default environment variable. @@ -96,7 +96,7 @@ Implementations SHOULD follow platform-specific environment variable size limitations: - Windows: Maximum 32,767 characters for name=value pairs according to - [Microsoft Documentation](https://docs.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-setenvironmentvariable) + [Microsoft Documentation](https://docs.microsoft.com/windows/win32/api/winbase/nf-winbase-setenvironmentvariable) - UNIX: System-dependent limits exist and are typically lower than Windows. Implementations SHOULD handle truncation gracefully when size limits are @@ -111,7 +111,7 @@ within that process: - Applications SHOULD read context-related environment variables during initialization. -- Applications SHOULD NOT modify environment variables on initialization of +- Applications SHOULD NOT modify context-related environment variables of the environment in which the parent process exists. - If modification is required, applications SHOULD create a new environment variables dictionary with the updated values for the child process. From 6cac3773dd39c831a37986a586f3870d771492ee Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Tue, 25 Mar 2025 17:06:58 -0400 Subject: [PATCH 09/12] [chore] minor changes to wording based on feedback --- specification/context/env-carriers.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index 5427aaade82..9d06a98a407 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -113,15 +113,13 @@ within that process: initialization. - Applications SHOULD NOT modify context-related environment variables of the environment in which the parent process exists. -- If modification is required, applications SHOULD create a new environment - variables dictionary with the updated values for the child process. #### Process Spawning When spawning child processes: -- Parent processes SHOULD inject context into environment variables before - spawning child processes. +- Parent processes SHOULD copy the current environment variables (if + applicable), modify, and inject context when spawning child processes. - Child processes SHOULD extract context from environment variables at startup. - When spawning multiple child processes with different contexts or baggage, each child SHOULD receive its own copy of the environment variables with @@ -143,6 +141,6 @@ process and with the correct permissions, can be accessed from other processes. Environment variable names are case-sensitive on UNIX and case-insensitive on Windows. -- For maximum compatibility, implementations SHOULD: +- For maximum compatibility, implementations MUST: - Use uppercase names consistently (`TRACEPARENT` not `TraceParent`). - Use the canonical case when setting environment variables. From cad65746ae6d0695337520f9420d640d6babcd32 Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Wed, 26 Mar 2025 17:34:19 -0400 Subject: [PATCH 10/12] [chore] minor updates to reference env carriers from other locations --- specification/README.md | 1 + specification/baggage/api.md | 4 ++++ 2 files changed, 5 insertions(+) diff --git a/specification/README.md b/specification/README.md index 32a653e04d6..5d587fdf99f 100644 --- a/specification/README.md +++ b/specification/README.md @@ -28,6 +28,7 @@ path_base_for_github_subdir: - API Specification - [Context](context/README.md) - [Propagators](context/api-propagators.md) + - [Environment Variable Carriers](context/env-carriers.md) - [Baggage](baggage/api.md) - [Tracing](trace/api.md) - [Metrics](metrics/api.md) diff --git a/specification/baggage/api.md b/specification/baggage/api.md index fef72cd153c..b035144a97c 100644 --- a/specification/baggage/api.md +++ b/specification/baggage/api.md @@ -183,6 +183,10 @@ The API layer or an extension package MUST include the following `Propagator`s: See [Propagators Distribution](../context/api-propagators.md#propagators-distribution) for how propagators are to be distributed. +See [Environment Variable Carriers](env-carriers.md) for how propagation should +be handled when using environment variables as a carrier mechanism between +processes. + Note: The W3C baggage specification does not currently assign semantic meaning to the optional metadata. From ddbc7f2d264c725faf215bc29a7584908e97d897 Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Wed, 26 Mar 2025 17:46:08 -0400 Subject: [PATCH 11/12] [chore] update truncation guidance --- specification/context/env-carriers.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/specification/context/env-carriers.md b/specification/context/env-carriers.md index 9d06a98a407..188c2881b87 100644 --- a/specification/context/env-carriers.md +++ b/specification/context/env-carriers.md @@ -99,8 +99,13 @@ limitations: [Microsoft Documentation](https://docs.microsoft.com/windows/win32/api/winbase/nf-winbase-setenvironmentvariable) - UNIX: System-dependent limits exist and are typically lower than Windows. -Implementations SHOULD handle truncation gracefully when size limits are -exceeded. +When truncation is required due to size limitations, implementations MUST +truncate whole entries. Truncation SHOULD start at the end of the entry list. +Implementers MUST document how graceful truncation is handled and SHOULD +provide the link to the corresponding specification (e.g., [W3C tracestate +Truncation guidance][w3c-truncation]). + +[w3c-truncation]: https://www.w3.org/TR/trace-context/#tracestate-limits ### Operational Guidance From a745c390e6405f1daaf4a74d5331733a8407a6f5 Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Wed, 26 Mar 2025 17:48:59 -0400 Subject: [PATCH 12/12] [chore] fix link --- specification/baggage/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/baggage/api.md b/specification/baggage/api.md index b035144a97c..67d4aa74afb 100644 --- a/specification/baggage/api.md +++ b/specification/baggage/api.md @@ -183,7 +183,7 @@ The API layer or an extension package MUST include the following `Propagator`s: See [Propagators Distribution](../context/api-propagators.md#propagators-distribution) for how propagators are to be distributed. -See [Environment Variable Carriers](env-carriers.md) for how propagation should +See [Environment Variable Carriers](../context/env-carriers.md) for how propagation should be handled when using environment variables as a carrier mechanism between processes.