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.

[github-actions]

This PR has been automatically marked as stale because it has not had any activity for 14 days. It will be closed if no further activity occurs within 14 days of this comment.
If you're still working on this, please add a comment or push new commits.

[ocelotl]

🔒 Internal (dash0) — reworked after upstream advanced. Rebased onto current upstream/main and trimmed: dropped the top-level log_level wiring (now upstream via open-telemetry#5351). Kept the still-missing pieces: ${env:VAR} prefix substitution (L5), applying the :-default when a var is set-but-empty (L6; upstream open-telemetry#5408 only covers unset), and wiring top-level attribute_limits into span limits (L7-attr). Scope: opentelemetry-configuration + changelog; 388 tests pass. Now a single commit on top of upstream/main.