From 2e2811e3598d1502bbb11e8ceb0a49ac6e5f6cd6 Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Wed, 5 Nov 2025 14:04:49 +0100 Subject: [PATCH 1/8] [configuration] Clarify that the boolean value environment variable guidance is not applicable to other configuration interfaces --- CHANGELOG.md | 3 +++ specification/configuration/sdk-environment-variables.md | 4 +++- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bc7e1c7853e..0058b28645a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -29,6 +29,9 @@ release. ### SDK Configuration +- Clarifies that guidance related to boolean environment variables is not applicable + to other configuration interfaces. ([#4723](https://github.com/open-telemetry/opentelemetry-specification/pull/4723)) + ### Common ### Supplementary Guidelines diff --git a/specification/configuration/sdk-environment-variables.md b/specification/configuration/sdk-environment-variables.md index f271bc9ea29..a10299a2530 100644 --- a/specification/configuration/sdk-environment-variables.md +++ b/specification/configuration/sdk-environment-variables.md @@ -75,7 +75,9 @@ empty, or unset is used, a warning SHOULD be logged to inform users about the fallback to false being applied. All Boolean environment variables SHOULD be named and defined such that false is the expected safe default behavior. Renaming or changing the default value MUST NOT happen without a major version -upgrade. +upgrade. The guidance on this paragraph is only applicable to environment +variables and not to other configuration interfaces such as the declarative +configuration interface. ### Numeric From 3b1aad7a19f7e867f8b3a7795c46dc16930f1e29 Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Fri, 14 Nov 2025 13:11:10 +0100 Subject: [PATCH 2/8] An attempt at splitting the guidance --- specification/configuration/common.md | 126 ++++++++++++++++++ .../sdk-environment-variables.md | 109 ++------------- specification/metrics/sdk_exporters/otlp.md | 2 +- specification/protocol/exporter.md | 6 +- 4 files changed, 143 insertions(+), 100 deletions(-) create mode 100644 specification/configuration/common.md diff --git a/specification/configuration/common.md b/specification/configuration/common.md new file mode 100644 index 00000000000..7b77982e0d2 --- /dev/null +++ b/specification/configuration/common.md @@ -0,0 +1,126 @@ + + +# OpenTelemetry Common Configuration Specification + +**Status**: [Stable](../document-status.md) except where otherwise specified + +
+Table of Contents + + + +- [Type-specific guidance](#type-specific-guidance) + * [Numeric](#numeric) + + [Integer](#integer) + + [Duration](#duration) + + [Timeout](#timeout) + * [String](#string) + + [Enum](#enum) + + + +
+ +The goal of this specification is to describe common guidance that is applicable +to all OpenTelemetry SDK configuration sources. + +Implementations MAY choose to allow configuration via any source in this specification, but are not required to. +If they do, they SHOULD follow the guidance listed in this document. + +## Type-specific guidance + +### Numeric + +Configuration sources accepting numeric values are sub-classified into: + +* [Integer](#integer) +* [Duration](#duration) +* [Timeout](#timeout) + +The following guidance applies to all numeric types. + +> The following paragraph was added after stabilization and the requirements are +> thus qualified as "SHOULD" to allow implementations to avoid breaking changes. +> For new +> implementations, these should be treated as MUST requirements. + +For sources accepting a numeric value, if the user provides a value the +implementation cannot parse, or which is outside the valid range for the +configuration item, the implementation SHOULD generate a warning and gracefully +ignore the setting, i.e., treat them as not set. In particular, implementations +SHOULD NOT assign a custom interpretation e.g. to negative values if a negative +value does not naturally apply to a configuration and does not have an +explicitly specified meaning, but treat it like any other invalid value. + +For example, a value specifying a buffer size must naturally be non-negative. +Treating a negative value as "buffer everything" would be an example of such a +discouraged custom interpretation. Instead the default buffer size should be +used. + +Note that this could make a difference even if the custom interpretation is +identical with the default value, because it might reset a value set from other +configuration sources with the default. + +#### Integer + +If an implementation chooses to support an integer-valued configuratin source, +it SHOULD support non-negative values between 0 and 2³¹ − 1 (inclusive). +Individual SDKs MAY choose to support a larger range of values. + +#### Duration + +Any value that represents a duration MUST be an integer representing a number of +milliseconds. The value is non-negative - if a negative value is provided, the +implementation MUST generate a warning, gracefully ignore the setting and use +the default value if it is defined. + +For example, the value `12000` indicates 12000 milliseconds, i.e., 12 seconds. + +#### Timeout + +Timeout values are similar to [duration](#duration) values, but are treated as a +separate type because of differences in how they interpret timeout zero values ( +see below). + +Any value that represents a timeout MUST be an integer representing a number of +milliseconds. The value is non-negative - if a negative value is provided, the +implementation MUST generate a warning, gracefully ignore the setting and use +the default value if it is defined. + +For example, the value `12000` indicates 12000 milliseconds, i.e., 12 seconds. + +Implementations SHOULD interpret timeout zero values (i.e. `0` indicating 0 +milliseconds) as no limit (i.e. infinite). In practice, implementations MAY +treat no limit as "a very long time" and substitute a very large duration ( +e.g. the maximum milliseconds representable by a 32-bit integer). + +### String + +String values are sub-classified into: + +* [Enum][]. + +Normally, string values include notes describing how they are interpreted by +implementations. + +#### Enum + +Enum values SHOULD be interpreted in a case-insensitive manner. + +For configuration sources which accept a known value out of a set, i.e., an enum +value, implementations MAY support additional values not listed here. + +For sources accepting an enum value, if the user provides a value +the implementation does not recognize, the implementation MUST generate +a warning and gracefully ignore the setting. +When reporting configuration errors, implementations SHOULD display the original +user-provided value to aid debugging. + +If a null object (empty, no-op) value is acceptable, then the enum value +representing it MUST be `"none"`. diff --git a/specification/configuration/sdk-environment-variables.md b/specification/configuration/sdk-environment-variables.md index a10299a2530..af1a2287a7d 100644 --- a/specification/configuration/sdk-environment-variables.md +++ b/specification/configuration/sdk-environment-variables.md @@ -17,14 +17,9 @@ aliases: - [Implementation guidelines](#implementation-guidelines) - [Parsing empty value](#parsing-empty-value) -- [Configuration types](#configuration-types) +- [Type-specific guidance](#type-specific-guidance) * [Boolean](#boolean) * [Numeric](#numeric) - + [Integer](#integer) - + [Duration](#duration) - + [Timeout](#timeout) - * [String](#string) - + [Enum](#enum) - [General SDK Configuration](#general-sdk-configuration) - [Batch Span Processor](#batch-span-processor) - [Batch LogRecord Processor](#batch-logrecord-processor) @@ -46,10 +41,11 @@ aliases: -The goal of this specification is to unify the environment variable names between different OpenTelemetry implementations. +The goal of this specification is to unify the environment variable names and value parsing between different OpenTelemetry implementations. Implementations MAY choose to allow configuration via the environment variables in this specification, but are not required to. -If they do, they SHOULD use the names listed in this document. +If they do, they SHOULD use the names and value parsing behavior specified in this document. +They SHOULD also follow the [common configuration specification](common.md). ## Implementation guidelines @@ -61,7 +57,7 @@ The environment-based configuration MUST have a direct code configuration equiva The SDK MUST interpret an empty value of an environment variable the same way as when the variable is unset. -## Configuration types +## Type-specific guidance ### Boolean @@ -75,18 +71,10 @@ empty, or unset is used, a warning SHOULD be logged to inform users about the fallback to false being applied. All Boolean environment variables SHOULD be named and defined such that false is the expected safe default behavior. Renaming or changing the default value MUST NOT happen without a major version -upgrade. The guidance on this paragraph is only applicable to environment -variables and not to other configuration interfaces such as the declarative -configuration interface. +upgrade. ### Numeric -Variables accepting numeric values are sub-classified into: - -* [Integer](#integer) -* [Duration](#duration) -* [Timeout](#timeout) - The following guidance applies to all numeric types. > The following paragraph was added after stabilization and the requirements are @@ -95,79 +83,8 @@ The following guidance applies to all numeric types. > implementations, these should be treated as MUST requirements. For variables accepting a numeric value, if the user provides a value the -implementation cannot parse, or which is outside the valid range for the -configuration item, the implementation SHOULD generate a warning and gracefully -ignore the setting, i.e., treat them as not set. In particular, implementations -SHOULD NOT assign a custom interpretation e.g. to negative values if a negative -value does not naturally apply to a configuration and does not have an -explicitly specified meaning, but treat it like any other invalid value. - -For example, a value specifying a buffer size must naturally be non-negative. -Treating a negative value as "buffer everything" would be an example of such a -discouraged custom interpretation. Instead the default buffer size should be -used. - -Note that this could make a difference even if the custom interpretation is -identical with the default value, because it might reset a value set from other -configuration sources with the default. - -#### Integer - -If an implementation chooses to support an integer-valued environment variable, -it SHOULD support non-negative values between 0 and 2³¹ − 1 (inclusive). -Individual SDKs MAY choose to support a larger range of values. - -#### Duration - -Any value that represents a duration MUST be an integer representing a number of -milliseconds. The value is non-negative - if a negative value is provided, the -implementation MUST generate a warning, gracefully ignore the setting and use -the default value if it is defined. - -For example, the value `12000` indicates 12000 milliseconds, i.e., 12 seconds. - -#### Timeout - -Timeout values are similar to [duration](#duration) values, but are treated as a -separate type because of differences in how they interpret timeout zero values ( -see below). - -Any value that represents a timeout MUST be an integer representing a number of -milliseconds. The value is non-negative - if a negative value is provided, the -implementation MUST generate a warning, gracefully ignore the setting and use -the default value if it is defined. - -For example, the value `12000` indicates 12000 milliseconds, i.e., 12 seconds. - -Implementations SHOULD interpret timeout zero values (i.e. `0` indicating 0 -milliseconds) as no limit (i.e. infinite). In practice, implementations MAY -treat no limit as "a very long time" and substitute a very large duration ( -e.g. the maximum milliseconds representable by a 32-bit integer). - -### String - -String values are sub-classified into: - -* [Enum][]. - -Normally, string values include notes describing how they are interpreted by -implementations. - -#### Enum - -Enum values SHOULD be interpreted in a case-insensitive manner. - -For variables which accept a known value out of a set, i.e., an enum value, -implementations MAY support additional values not listed here. - -For variables accepting an enum value, if the user provides a value -the implementation does not recognize, the implementation MUST generate -a warning and gracefully ignore the setting. -When reporting configuration errors, implementations SHOULD display the original -user-provided value to aid debugging. - -If a null object (empty, no-op) value is acceptable, then the enum value -representing it MUST be `"none"`. +implementation cannot parse, the implementation SHOULD generate a warning and gracefully +ignore the setting, i.e., treat them as not set. ## General SDK Configuration @@ -426,8 +343,8 @@ OTEL_{LANGUAGE}_{FEATURE} [Boolean]: #boolean [Float]: #float -[Integer]: #integer -[Duration]: #duration -[Timeout]: #timeout -[String]: #string -[Enum]: #enum +[Integer]: common.md#integer +[Duration]: common.md#duration +[Timeout]: common.md#timeout +[String]: common.md#string +[Enum]: common.md#enum diff --git a/specification/metrics/sdk_exporters/otlp.md b/specification/metrics/sdk_exporters/otlp.md index 31c52110975..5c6788ae7bb 100644 --- a/specification/metrics/sdk_exporters/otlp.md +++ b/specification/metrics/sdk_exporters/otlp.md @@ -72,4 +72,4 @@ The recognized (case-insensitive) values for `OTEL_EXPORTER_OTLP_METRICS_DEFAULT - [OTEP0131 OTLP Exporters Configurable Export Behavior](../../../oteps/metrics/0131-otlp-export-behavior.md) -[Enum]: ../../configuration/sdk-environment-variables.md#enum +[Enum]: ../../configuration/common.md#enum diff --git a/specification/protocol/exporter.md b/specification/protocol/exporter.md index 4025d180477..c400cf2b551 100644 --- a/specification/protocol/exporter.md +++ b/specification/protocol/exporter.md @@ -217,9 +217,9 @@ MyDistribution/x.y.z OTel-OTLP-Exporter-Python/1.2.3 ``` [Boolean]: ../configuration/sdk-environment-variables.md#boolean -[Timeout]: ../configuration/sdk-environment-variables.md#timeout -[String]: ../configuration/sdk-environment-variables.md#string -[Enum]: ../configuration/sdk-environment-variables.md#enum +[Timeout]: ../configuration/common.md#timeout +[String]: ../configuration/common.md#string +[Enum]: ../configuration/common.md#enum [resource-semconv]: https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#telemetry-sdk [otlphttp-req]: https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md#otlphttp-request From 9c90894e7d652c3e392106dcebaef3215275c56e Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Fri, 14 Nov 2025 13:16:44 +0100 Subject: [PATCH 3/8] Fix spelling mistake --- specification/configuration/common.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/configuration/common.md b/specification/configuration/common.md index 7b77982e0d2..dc18db88e7c 100644 --- a/specification/configuration/common.md +++ b/specification/configuration/common.md @@ -69,7 +69,7 @@ configuration sources with the default. #### Integer -If an implementation chooses to support an integer-valued configuratin source, +If an implementation chooses to support an integer-valued configuration source, it SHOULD support non-negative values between 0 and 2³¹ − 1 (inclusive). Individual SDKs MAY choose to support a larger range of values. From d91d3e7eb90e7d745d66be7ac19e3cbd026b1f70 Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Tue, 25 Nov 2025 11:26:27 +0100 Subject: [PATCH 4/8] Remove 'failure to parse' from common spec --- specification/configuration/common.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/specification/configuration/common.md b/specification/configuration/common.md index dc18db88e7c..01ae47a93b1 100644 --- a/specification/configuration/common.md +++ b/specification/configuration/common.md @@ -50,13 +50,13 @@ The following guidance applies to all numeric types. > For new > implementations, these should be treated as MUST requirements. -For sources accepting a numeric value, if the user provides a value the -implementation cannot parse, or which is outside the valid range for the -configuration item, the implementation SHOULD generate a warning and gracefully -ignore the setting, i.e., treat them as not set. In particular, implementations -SHOULD NOT assign a custom interpretation e.g. to negative values if a negative -value does not naturally apply to a configuration and does not have an -explicitly specified meaning, but treat it like any other invalid value. +For sources accepting a numeric value, if the user provides a value which is +outside the valid range for the configuration item, the implementation SHOULD +generate a warning and gracefully ignore the setting, i.e., treat them as not +set. In particular, implementations SHOULD NOT assign a custom interpretation +e.g. to negative values if a negative value does not naturally apply to a +configuration and does not have an explicitly specified meaning, but treat it +like any other invalid value. For example, a value specifying a buffer size must naturally be non-negative. Treating a negative value as "buffer everything" would be an example of such a From 7a80e060daadef0f06a67fdc91c1dffe7dbc7fd3 Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Mon, 1 Dec 2025 16:38:06 +0100 Subject: [PATCH 5/8] Make it clear that it is a configuration source --- specification/configuration/common.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/configuration/common.md b/specification/configuration/common.md index 01ae47a93b1..762c45f2f96 100644 --- a/specification/configuration/common.md +++ b/specification/configuration/common.md @@ -30,7 +30,8 @@ aliases: The goal of this specification is to describe common guidance that is applicable to all OpenTelemetry SDK configuration sources. -Implementations MAY choose to allow configuration via any source in this specification, but are not required to. +Implementations MAY choose to allow configuration via any configuration source +in this specification, but are not required to. If they do, they SHOULD follow the guidance listed in this document. ## Type-specific guidance From 4ae26bc9c098c6a825b882718618fb9a5644a35e Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Mon, 1 Dec 2025 16:40:09 +0100 Subject: [PATCH 6/8] Add link to common section --- specification/configuration/sdk-environment-variables.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/configuration/sdk-environment-variables.md b/specification/configuration/sdk-environment-variables.md index 67394787fa4..0eb18c00a05 100644 --- a/specification/configuration/sdk-environment-variables.md +++ b/specification/configuration/sdk-environment-variables.md @@ -75,7 +75,8 @@ upgrade. ### Numeric -The following guidance applies to all numeric types. +The following guidance applies to all numeric types and extends the [common +configuration specification 'Numeric' guidance](common.md#numeric). > The following paragraph was added after stabilization and the requirements are > thus qualified as "SHOULD" to allow implementations to avoid breaking changes. From 7faac929511f813a11c7bccb951b78c4de43e841 Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Mon, 1 Dec 2025 16:45:59 +0100 Subject: [PATCH 7/8] Move some enum guidance back to the env var doc --- .../configuration/sdk-environment-variables.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/specification/configuration/sdk-environment-variables.md b/specification/configuration/sdk-environment-variables.md index 0eb18c00a05..9a56288370b 100644 --- a/specification/configuration/sdk-environment-variables.md +++ b/specification/configuration/sdk-environment-variables.md @@ -87,6 +87,23 @@ For variables accepting a numeric value, if the user provides a value the implementation cannot parse, the implementation SHOULD generate a warning and gracefully ignore the setting, i.e., treat them as not set. +### String + +String values are sub-classified into: + +* [Enum][]. + +#### Enum + +The following guidance extends the [common configuration specification 'Enum' +guidance](common.md#enum). + +Enum values SHOULD be interpreted in a case-insensitive manner. + +For sources accepting an enum value, if the user provides a value +the implementation does not recognize, the implementation MUST generate +a warning and gracefully ignore the setting. + ## General SDK Configuration | Name | Description | Default | Type | Notes | From c4c00c7b398edb09838542efc37fcd9ec4ad958d Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Mon, 1 Dec 2025 16:50:20 +0100 Subject: [PATCH 8/8] Remove duplicated lines from common --- specification/configuration/common.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/specification/configuration/common.md b/specification/configuration/common.md index 762c45f2f96..60243116cf3 100644 --- a/specification/configuration/common.md +++ b/specification/configuration/common.md @@ -112,14 +112,9 @@ implementations. #### Enum -Enum values SHOULD be interpreted in a case-insensitive manner. - For configuration sources which accept a known value out of a set, i.e., an enum value, implementations MAY support additional values not listed here. -For sources accepting an enum value, if the user provides a value -the implementation does not recognize, the implementation MUST generate -a warning and gracefully ignore the setting. When reporting configuration errors, implementations SHOULD display the original user-provided value to aid debugging.