OpenTelemetry Environment Variable Specification

Status: Mixed

The goal of this specification is to unify the environment variable names between different OpenTelemetry SDK implementations. SDKs 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.

Parsing empty value

Status: Stable

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

Special configuration types

Status: Stable

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

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.

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

Status: Stable

NameDescriptionDefaultNotes
OTEL_SDK_DISABLEDDisable the SDK for all signalsfalseBoolean value. If “true”, a no-op SDK implementation will be used for all telemetry signals. Any other value or absence of the variable will have no effect and the SDK will remain enabled. This setting has no effect on propagators configured through the OTEL_PROPAGATORS variable.
OTEL_RESOURCE_ATTRIBUTESKey-value pairs to be used as resource attributesSee Resource semantic conventions for details.See Resource SDK for more details.
OTEL_SERVICE_NAMESets the value of the service.name resource attributeIf service.name is also provided in OTEL_RESOURCE_ATTRIBUTES, then OTEL_SERVICE_NAME takes precedence.
OTEL_LOG_LEVELLog level used by the SDK logger“info”
OTEL_PROPAGATORSPropagators to be used as a comma-separated list“tracecontext,baggage”Values MUST be deduplicated in order to register a Propagator only once.
OTEL_TRACES_SAMPLERSampler to be used for traces“parentbased_always_on”See Sampling
OTEL_TRACES_SAMPLER_ARGString value to be used as the sampler argumentThe 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.

Known values for OTEL_PROPAGATORS are:

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

Status: Stable

NameDescriptionDefaultNotes
OTEL_BSP_SCHEDULE_DELAYDelay interval (in milliseconds) between two consecutive exports5000
OTEL_BSP_EXPORT_TIMEOUTMaximum allowed time (in milliseconds) to export data30000
OTEL_BSP_MAX_QUEUE_SIZEMaximum queue size2048
OTEL_BSP_MAX_EXPORT_BATCH_SIZEMaximum batch size512Must be less than or equal to OTEL_BSP_MAX_QUEUE_SIZE

Batch LogRecord Processor

Status: Experimental

NameDescriptionDefaultNotes
OTEL_BLRP_SCHEDULE_DELAYDelay interval (in milliseconds) between two consecutive exports5000
OTEL_BLRP_EXPORT_TIMEOUTMaximum allowed time (in milliseconds) to export data30000
OTEL_BLRP_MAX_QUEUE_SIZEMaximum queue size2048
OTEL_BLRP_MAX_EXPORT_BATCH_SIZEMaximum batch size512Must be less than or equal to OTEL_BLRP_MAX_QUEUE_SIZE

Attribute Limits

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

NameDescriptionDefaultNotes
OTEL_ATTRIBUTE_VALUE_LENGTH_LIMITMaximum allowed attribute value sizeEmpty value is treated as infinity. Non-integer and negative values are invalid.
OTEL_ATTRIBUTE_COUNT_LIMITMaximum allowed span attribute count128

Span Limits

Status: Stable

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

NameDescriptionDefaultNotes
OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMITMaximum allowed attribute value sizeEmpty value is treated as infinity. Non-integer and negative values are invalid.
OTEL_SPAN_ATTRIBUTE_COUNT_LIMITMaximum allowed span attribute count128
OTEL_SPAN_EVENT_COUNT_LIMITMaximum allowed span event count128
OTEL_SPAN_LINK_COUNT_LIMITMaximum allowed span link count128
OTEL_EVENT_ATTRIBUTE_COUNT_LIMITMaximum allowed attribute per span event count128
OTEL_LINK_ATTRIBUTE_COUNT_LIMITMaximum allowed attribute per span link count128

OTLP Exporter

See OpenTelemetry Protocol Exporter Configuration Options.

Jaeger Exporter

Status: Stable

The OTEL_EXPORTER_JAEGER_PROTOCOL environment variable MAY by used to specify the transport protocol. The value MUST be one of:

The default transport protocol SHOULD be http/thrift.binary unless SDKs have good reasons to choose other as the default (e.g. for backward compatibility reasons).

Environment variables specific for the http/thrift.binary transport protocol:

NameDescriptionDefault
OTEL_EXPORTER_JAEGER_ENDPOINTFull URL of the Jaeger HTTP endpointhttp://localhost:14268/api/traces
OTEL_EXPORTER_JAEGER_TIMEOUTMaximum time (in milliseconds) the Jaeger exporter will wait for each batch export10000
OTEL_EXPORTER_JAEGER_USERUsername to be used for HTTP basic authentication
OTEL_EXPORTER_JAEGER_PASSWORDPassword to be used for HTTP basic authentication

Environment variables specific for the grpc transport protocol:

NameDescriptionDefault
OTEL_EXPORTER_JAEGER_ENDPOINTURL of the Jaeger gRPC endpointhttp://localhost:14250
OTEL_EXPORTER_JAEGER_TIMEOUTMaximum time (in milliseconds) the Jaeger exporter will wait for each batch export10000
OTEL_EXPORTER_JAEGER_USERUsername to be used for HTTP basic authentication
OTEL_EXPORTER_JAEGER_PASSWORDPassword to be used for HTTP basic authentication

Environment variables specific for the udp/thrift.compact transport protocol:

NameDescriptionDefault
OTEL_EXPORTER_JAEGER_AGENT_HOSTHostname of the Jaeger agentlocalhost
OTEL_EXPORTER_JAEGER_AGENT_PORTudp/thrift.compact port of the Jaeger agent6831

Environment variables specific for the udp/thrift.binary transport protocol:

NameDescriptionDefault
OTEL_EXPORTER_JAEGER_AGENT_HOSTHostname of the Jaeger agentlocalhost
OTEL_EXPORTER_JAEGER_AGENT_PORTudp/thrift.binary port of the Jaeger agent6832

Zipkin Exporter

Status: Stable

NameDescriptionDefault
OTEL_EXPORTER_ZIPKIN_ENDPOINTEndpoint for Zipkin traceshttp://localhost:9411/api/v2/spans
OTEL_EXPORTER_ZIPKIN_TIMEOUTMaximum time (in milliseconds) the Zipkin exporter will wait for each batch export10000

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: Experimental

NameDescriptionDefault
OTEL_EXPORTER_PROMETHEUS_HOSTHost used by the Prometheus exporter“localhost”
OTEL_EXPORTER_PROMETHEUS_PORTPort used by the Prometheus exporter9464

Exporter Selection

Status: Stable

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

NameDescriptionDefault
OTEL_TRACES_EXPORTERTrace exporter to be used“otlp”
OTEL_METRICS_EXPORTERMetrics exporter to be used“otlp”
OTEL_LOGS_EXPORTERLogs exporter to be used“otlp”

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

Known values for OTEL_TRACES_EXPORTER are:

  • "otlp": OTLP
  • "jaeger": export in Jaeger data model
  • "zipkin": Zipkin (Defaults to protobuf format)
  • "none": No automatically configured exporter for traces.

Known values for OTEL_METRICS_EXPORTER are:

  • "otlp": OTLP
  • "prometheus": Prometheus
  • "none": No automatically configured exporter for metrics.

Known values for OTEL_LOGS_EXPORTER are:

  • "otlp": OTLP
  • "none": No automatically configured exporter for logs.

Metrics SDK Configuration

Status: Mixed

NameDescriptionDefaultNotes
OTEL_METRICS_EXEMPLAR_FILTERFilter for which measurements can become Exemplars."with_sampled_trace"

Known values for OTEL_METRICS_EXEMPLAR_FILTER are:

  • "none": No measurements are eligible for exemplar sampling.
  • "all": All measurements are eligible for exemplar sampling.
  • "with_sampled_trace": Only allow measurements with a sampled parent span in context.

Periodic exporting MetricReader

Status: Stable

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

NameDescriptionDefaultNotes
OTEL_METRIC_EXPORT_INTERVALThe time interval (in milliseconds) between the start of two export attempts.60000
OTEL_METRIC_EXPORT_TIMEOUTMaximum allowed time (in milliseconds) to export data.30000

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}