Environment Variable Specification

Status: Stable except where otherwise specified

The goal of this specification is to unify the environment variable names 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.

Implementation guidelines

Environment variables MAY be handled (implemented) directly by a component, in the SDK, or in a separate component (e.g. environment-based autoconfiguration component).

The environment-based configuration MUST have a direct code configuration equivalent.

Parsing empty value

The SDK MUST interpret an empty value of an environment variable the same way as when the variable is unset.

Special configuration types

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 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 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 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 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.

Enum value

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 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.

General SDK Configuration

Known values for OTEL_PROPAGATORS are:

• "tracecontext": W3C Trace Context
• "baggage": W3C Baggage
• "b3": B3 Single
• "b3multi": B3 Multi
• "jaeger": Jaeger
• "xray": AWS X-Ray (third party)
• "ottrace": OT Trace (third party)
• "none": No automatically configured propagator.

Known values for OTEL_TRACES_SAMPLER are:

• "always_on": AlwaysOnSampler
• "always_off": AlwaysOffSampler
• "traceidratio": TraceIdRatioBased
• "parentbased_always_on": ParentBased(root=AlwaysOnSampler)
• "parentbased_always_off": ParentBased(root=AlwaysOffSampler)
• "parentbased_traceidratio": ParentBased(root=TraceIdRatioBased)
• "parentbased_jaeger_remote": ParentBased(root=JaegerRemoteSampler)
• "jaeger_remote": JaegerRemoteSampler
• "xray": AWS X-Ray Centralized Sampling (third party)

Depending on the value of OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG may be set as follows:

• For traceidratio and parentbased_traceidratio samplers: Sampling probability, a number in the [0..1] range, e.g. “0.25”. Default is 1.0 if unset.
• For jaeger_remote and parentbased_jaeger_remote: The value is a comma separated list:
  • endpoint: the endpoint in form of scheme://host:port of gRPC server that serves the sampling strategy for the service (sampling.proto).
  • pollingIntervalMs: in milliseconds indicating how often the sampler will poll the backend for updates to sampling strategy.
  • initialSamplingRate: in the [0..1] range, which is used as the sampling probability when the backend cannot be reached to retrieve a sampling strategy. This value stops having an effect once a sampling strategy is retrieved successfully, as the remote strategy will be used until a new update is retrieved.
  • Example: endpoint=http://localhost:14250,pollingIntervalMs=5000,initialSamplingRate=0.25

Batch Span Processor

Batch LogRecord Processor

Attribute Limits

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

See the SDK Attribute Limits section for the definition of the limits.

Span Limits

See the SDK Span Limits section for the definition of the limits.

LogRecord Limits

See the SDK LogRecord Limits section for the definition of the limits.

OTLP Exporter

See OpenTelemetry Protocol Exporter Configuration Options.

Zipkin Exporter

Additionally, the following environment variables are reserved for future usage in Zipkin Exporter configuration:

• OTEL_EXPORTER_ZIPKIN_PROTOCOL

This will be used to specify whether or not the exporter uses v1 or v2, json, thrift or protobuf. As of 1.0 of the specification, there is no specified default, or configuration via environment variables.

Prometheus Exporter

Status: Development

Exporter Selection

We define environment variables for setting one or more exporters per signal.

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

Known values for OTEL_TRACES_EXPORTER are:

• "otlp": OTLP
• "zipkin": Zipkin (Defaults to protobuf format)
• "console": Standard Output
• "logging": Standard Output. It is a deprecated value left for backwards compatibility. It SHOULD NOT be supported by new implementations.
• "none": No automatically configured exporter for traces.

Known values for OTEL_METRICS_EXPORTER are:

• "otlp": OTLP
• "prometheus": Prometheus
• "console": Standard Output
• "logging": Standard Output. It is a deprecated value left for backwards compatibility. It SHOULD NOT be supported by new implementations.
• "none": No automatically configured exporter for metrics.

Known values for OTEL_LOGS_EXPORTER are:

• "otlp": OTLP
• "console": Standard Output
• "logging": Standard Output. It is a deprecated value left for backwards compatibility. It SHOULD NOT be supported by new implementations.
• "none": No automatically configured exporter for logs.

Metrics SDK Configuration

Exemplar

Status: Development

Known values for OTEL_METRICS_EXEMPLAR_FILTER are:

• "always_on": AlwaysOn
• "always_off": AlwaysOff
• "trace_based": TraceBased

Periodic exporting MetricReader

Environment variables specific for the push metrics exporters (OTLP, stdout, in-memory) that use periodic exporting MetricReader.

File Configuration

Status: Development

Environment variables involved in file configuration.

If OTEL_EXPERIMENTAL_CONFIG_FILE is set, the file at the specified path is used to call Parse. The resulting configuration model is used to call Create to produce fully configured SDK components.

When OTEL_EXPERIMENTAL_CONFIG_FILE is set, all other environment variables besides those referenced in the configuration file for environment variable substitution MUST be ignored. Ignoring the environment variables is necessary because there is no intuitive way to merge the flat environment variable scheme with the structured file configuration scheme in all cases. Users that require merging multiple sources of configuration are encouraged to customize the configuration model returned by Parse before Create is called. For example, a user may call Parse on multiple files and define logic from merging the resulting configuration models, or overlay values from environment variables on top of a configuration model. Implementations MAY provide a mechanism to customize the configuration model parsed from OTEL_EXPERIMENTAL_CONFIG_FILE.

Users are encouraged to use the sdk-config.yaml (TODO: Add link when available) as a starting point for OTEL_EXPERIMENTAL_CONFIG_FILE. This file represents a common SDK configuration scenario, and includes environment variable substitution references to environment variables which are otherwise ignored.

TODO: deprecate env vars which are not compatible (#3967) TODO: provide solution for platforms to contribute to configure (#3966)

Language Specific Environment Variables

To ensure consistent naming across projects, this specification recommends that language specific environment variables are formed using the following convention:

OTEL_{LANGUAGE}_{FEATURE}