diff --git a/CHANGELOG.md b/CHANGELOG.md index 462738e2bdb..06a9acd224e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -40,6 +40,9 @@ release. ### SDK Configuration +- Specify handling of invalid numeric environment variables + ([#2963](https://github.com/open-telemetry/opentelemetry-specification/pull/2963)) + ### Telemetry Schemas ### Common diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md index ef94a62fd83..76cb3bbd780 100644 --- a/specification/sdk-environment-variables.md +++ b/specification/sdk-environment-variables.md @@ -27,6 +27,26 @@ Renaming or changing the default value MUST NOT happen without a major version u If an SDK chooses to support an integer-valued environment variable, it SHOULD support nonnegative values between 0 and 2³¹ − 1 (inclusive). Individual SDKs MAY choose to support a larger range of values. +> The following paragraph was added after stabilization and the requirements are +thus qualified as "SHOULD" to allow SDKs to avoid breaking changes. +For new +implementations, these should be treated as MUST requirements. + +For variables accepting a numeric value, if the user provides a value the SDK cannot parse, +or which is outside the valid range for the configuration item, the SDK SHOULD +generate a warning and gracefully ignore the setting, i.e., treat them as not set. +In particular, SDKs +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. + ### Enum value For variables which accept a known value out of a set, i.e., an enum value, SDK implementations MAY support additional values not listed here.