Skip to content

Commit

Permalink
Update sdk-environment-variables.md
Browse files Browse the repository at this point in the history
  • Loading branch information
pellared authored Oct 26, 2023
1 parent 4b94fd6 commit de74bd4
Showing 1 changed file with 12 additions and 12 deletions.
24 changes: 12 additions & 12 deletions specification/configuration/sdk-environment-variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,25 +36,25 @@ The SDK MUST interpret an empty value of an environment variable the same way as
### Boolean value

Any value that represents a Boolean MUST be set to true only by the case-insensitive string `"true"`, meaning `"True"` or `"TRUE"` are also accepted, as true.
An SDK MUST NOT extend this definition and define additional values that are interpreted as true.
An implementation MUST NOT extend this definition and define additional values that are interpreted as true.
Any value not explicitly defined here as a true value, including unset and empty values, MUST be interpreted as false.
If any value other than a true value, case-insensitive string `"false"`, 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.

### Numeric value

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.
If an implementation 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.
thus qualified as "SHOULD" to allow implementations 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
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, SDKs
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.
Expand All @@ -68,15 +68,15 @@ because it might reset a value set from other configuration sources with the def

### 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.
For variables accepting an enum value, if the user provides a value the SDK does not recognize, the SDK MUST generate a warning and gracefully ignore the setting.
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.

If a null object (empty, no-op) value is acceptable, then the enum value representing it MUST be `"none"`.

### Duration

Any value that represents a duration, for example a timeout, MUST be an integer representing a number of
milliseconds. The value is non-negative - if a negative value is provided, the SDK MUST generate a warning,
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.
Expand All @@ -93,7 +93,7 @@ For example, the value `12000` indicates 12000 milliseconds, i.e., 12 seconds.
| OTEL_LOG_LEVEL | Log level used by the SDK logger | "info" | |
| OTEL_PROPAGATORS | Propagators to be used as a comma-separated list | "tracecontext,baggage" | Values MUST be deduplicated in order to register a `Propagator` only once. |
| OTEL_TRACES_SAMPLER | Sampler to be used for traces | "parentbased_always_on" | See [Sampling](../trace/sdk.md#sampling) |
| OTEL_TRACES_SAMPLER_ARG | String value to be used as the sampler argument | | The specified value will only be used if OTEL_TRACES_SAMPLER is set. Each Sampler type defines its own expected input, if any. Invalid or unrecognized input MUST be logged and MUST be otherwise ignored, i.e. the SDK MUST behave as if OTEL_TRACES_SAMPLER_ARG is not set. |
| OTEL_TRACES_SAMPLER_ARG | String value to be used as the sampler argument | | The specified value will only be used if OTEL_TRACES_SAMPLER is set. Each Sampler type defines its own expected input, if any. Invalid or unrecognized input MUST be logged and MUST be otherwise ignored, i.e. the implementation MUST behave as if OTEL_TRACES_SAMPLER_ARG is not set. |

Known values for `OTEL_PROPAGATORS` are:

Expand Down Expand Up @@ -151,7 +151,7 @@ Depending on the value of `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` may b

## Attribute Limits

SDKs SHOULD only offer environment variables for the types of attributes, for
Implementations SHOULD only offer environment variables for the types of attributes, for
which that SDK implements truncation mechanism.

See the SDK [Attribute Limits](../common/README.md#attribute-limits) section for the definition of the limits.
Expand Down Expand Up @@ -230,7 +230,7 @@ We define environment variables for setting one or more exporters per signal.
| OTEL_METRICS_EXPORTER | Metrics exporter to be used | "otlp" |
| OTEL_LOGS_EXPORTER | Logs exporter to be used | "otlp" |

The SDK MAY accept a comma-separated list to enable setting multiple exporters.
The implementation MAY accept a comma-separated list to enable setting multiple exporters.

Known values for `OTEL_TRACES_EXPORTER` are:

Expand Down

0 comments on commit de74bd4

Please sign in to comment.