Skip to content

Commit

Permalink
Specify how to deal with invalid numeric envvars (open-telemetry#2963)
Browse files Browse the repository at this point in the history
  • Loading branch information
Oberon00 authored Nov 28, 2022
1 parent e27f118 commit a0d0d68
Show file tree
Hide file tree
Showing 2 changed files with 23 additions and 0 deletions.
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
20 changes: 20 additions & 0 deletions specification/sdk-environment-variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down

0 comments on commit a0d0d68

Please sign in to comment.