oss_26_declarative_config_env_substitution

[ocelotl]

Closes #32

Declarative config env substitution + top-level fields (Linear OSS-26, findings L5/L6/L7): support ${env:VAR}; apply :-default when the var is null/empty/undefined; wire top-level log_level and attribute_limits into configure_sdk (attribute_limits applied to spans; logs/metrics not programmatically supported → warns).

Validation: scope contained to opentelemetry-configuration + changelog; package suite 374 passed.

Linear issue: https://linear.app/dash0/issue/OSS-26/l5-l6-l7-declarative-config-env-substitution-top-level-attribute

[ocelotl]

🔒 Internal (dash0) — not for upstream.

• Linear: https://linear.app/dash0/issue/OSS-26/l5-l6-l7-declarative-config-env-substitution-top-level-attribute (findings L5/L6/L7)
• Closes: oss_26_declarative_config_env_substitution #32 · Branch: oss_26_declarative_config_env_substitution · Commit: 70bd8450c
• Validation: opentelemetry-configuration suite 374 passed; scope package + changelog. attribute_limits→logs/metrics limitation cross-links OSS-21 (L2).

[ocelotl]

📣 Public-facing draft — to be used for the upstream PR in open-telemetry/opentelemetry-python. No internal references; copy verbatim.

Title: Fix declarative config env substitution and top-level fields

What

• Support the prefixed environment-variable reference form ${env:VAR} (including ${env:VAR:-default}), previously passed through unsubstituted.
• Apply the ${VAR:-default} default when the referenced variable is set-but-empty, not only when unset. A bare ${VAR} with an empty value still substitutes empty; only a truly undefined variable with no default remains an error.
• Honor top-level log_level and attribute_limits in configure_sdk (previously parsed but never applied): log_level sets the opentelemetry internal logger level (SeverityNumber bucketed onto the five stdlib levels); attribute_limits is threaded into the tracer provider as the default span attribute count/length limit (precedence: provider limits > top-level attribute_limits > spec defaults).

Why

Spec-conformance gaps: ${env:VAR} is part of the reference grammar; the :- default operator applies when the variable is null, empty, or undefined (configuration/data-model.md); and top-level log_level/attribute_limits are defined fields that must take effect.

Spec

Reference grammar (optional env: prefix) and null/empty/undefined semantics for :-: configuration/data-model.md.

Tests

New env-substitution tests (prefixed form; prefixed + default; prefixed missing raises; default applied when empty; empty-no-default substitutes empty; prefixed empty + default) and configure_sdk tests (log_level maps/sets the internal logger; attribute_limits applied to SpanLimits). Full opentelemetry-configuration suite: 374 passed.

Limitation

The SDK LoggerProvider constructor does not accept attribute limits and there is no single global attribute-limits hook, so top-level attribute_limits are applied only to spans; configure_sdk warns that logs and metrics are not covered rather than silently dropping the setting.