0013: Every setting has one name¶
Status: accepted · Reviewed: 2026-11-01 · Supersedes the warning named in 0012. Records before this one use the 1.x variable names.
Context¶
In 1.x the library read about forty environment variables under four conventions:
- bare names an app often sets for itself, such as
LOG_LEVEL,ENVIRONMENTandMETRICS_ENABLED; OBS_*;- names it made up inside OpenTelemetry's namespace, such as
OTEL_ENABLED,OTEL_LOGS_ENDPOINTandOTEL_TRACE_SAMPLING_RATIO; - the specification's own, such as
OTEL_EXPORTER_OTLP_ENDPOINT, though only for traces. Log and metric export ignoredOTEL_EXPORTER_OTLP_PROTOCOL.
The settings models also matched variables named like their fields. ENABLED=true turned on the runtime control plane and OTLP export, and the control plane's path was read from PATH.
Decision¶
- Every variable the library owns starts with
OBS_. A 1.x name becomesOBS_plus that name. - For OpenTelemetry it reads the specification's variables:
OTEL_SDK_DISABLED,OTEL_SERVICE_NAME,OTEL_RESOURCE_ATTRIBUTES,OTEL_TRACES_SAMPLER_ARG,OTEL_METRIC_EXPORT_INTERVAL, andOTEL_EXPORTER_OTLP_PROTOCOLwith its per-signal forms. It doesn't read endpoints: OpenTelemetry's exporters readOTEL_EXPORTER_OTLP_*ENDPOINTthemselves (0006). - A setting is read only from its documented name, never from its field name.
ObservabilitySettings, the one model built from field names in code, addsOBS_to them for the environment. - At startup,
observability.settings_retiredlists the 1.x variables still set, each with its replacement. Setting the replacement stops it, so an app that setsLOG_LEVELfor itself isn't warned forever.
Evidence¶
- Tests: in
test_config_settings.py,test_settings_ignore_variables_named_like_their_fieldsandtest_otel_service_name_names_the_service_everywhere. The per-signal protocol fallback andOTEL_SDK_DISABLEDare intest_otel_logs_from_env.pyandtest_otel_metrics_from_env.py, and the warning intest_retired_settings_are_reported_with_their_replacementsintest_sinks.py. - The leak: before this change,
_RuntimeControlEnvSettings().pathreturned the process'sPATH.
What it cost¶
- Every deployment renames its variables. The upgrade table lists each one, and the startup warning names any it missed.
OTEL_TRACES_SAMPLERisn't read. Sampling stays parent-based by trace ID, so the runtime control plane can change the ratio. OnlyOTEL_TRACES_SAMPLER_ARGis honoured.ObservabilitySettingsgains a few undocumented names from the prefix, such asOBS_SERVICEforservice, where a field's name differs from its variable's.