Specify how to deal with invalid numeric envvars (#2963)

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

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.