feat(config): support OTEL_CONFIG_FILE in the SDK configurator by MikeGoldsmith · Pull Request #5271 · open-telemetry/opentelemetry-python

MikeGoldsmith · 2026-06-03T12:50:36Z

Description

Wires the SDK entry point to honor the OTEL_CONFIG_FILE environment variable. When set, _OTelSDKConfigurator._configure loads the referenced YAML/JSON file via load_config_file() and applies it via configure_sdk() — bypassing the existing env-var-based _initialize_components() path entirely.

Per spec v1.0.0: when a config file is given, it is the sole source of truth; other OTEL_* variables are ignored except as ${env:VAR} substitutions inside the file.

OTEL_CONFIG_FILE=/path/to/otel-config.yaml python my_app.py

Behavior

Env var unset → existing _initialize_components(**kwargs) path. No change.
Env var set → configure_sdk(load_config_file(path)). Other env vars ignored.
Env var set + kwargs passed → warning logged listing the ignored kwargs (matters for distros that subclass _OTelSDKConfigurator and inject kwargs via super()._configure(**kwargs)). The file is authoritative.
Env var set, file missing/invalid → ConfigurationError propagates. Loud failure per spec.

Implementation notes

OTEL_CONFIG_FILE constant added to opentelemetry.sdk.environment_variables.
File-loader imports (pyyaml, jsonschema) stay lazy inside the if config_file: branch so the SDK does not require [file-configuration] extras unless a config file is actually used.

Refs #3631

Type of change

New feature (non-breaking change which adds functionality)

How Has This Been Tested?

5 new tests in tests/_configuration/test_configurator_file_routing.py:

Env var unset → _initialize_components called with passed kwargs (existing behavior preserved)
Env var set → configure_sdk(load_config_file(path)) called; _initialize_components NOT called
Env var set, missing file → ConfigurationError propagates
Env var set + kwargs → warning logged, kwargs not forwarded
Distro override pattern (subclass mutating kwargs then calling super()._configure) still works when env var is unset

Manually smoke-tested end-to-end: with a minimal YAML file, the SDK TracerProvider is constructed with the configured processor.

Does This PR Require a Contrib Repo Change?

Yes.
No.

Checklist:

Followed the style guidelines of this project
Changelogs have been updated
Unit tests have been added
Documentation has been updated

Adds `_dict_to_dataclass` in `_conversion.py` which walks each field's type annotation and converts: - nested dicts → typed dataclass instances - lists of dicts → lists of typed dataclasses - string/value → Enum members (e.g. log_level: info) - unknown keys → routed to the @_additional_properties decorator The loader's `_dict_to_model` now produces a fully-typed OpenTelemetryConfiguration tree end-to-end. Factory functions can rely on typed attribute access (config.tracer_provider.processors[0].batch .exporter.otlp_http.endpoint) instead of failing on raw dicts. This closes the gap between load_config_file() and the factory functions — YAML/JSON config → SDK objects now works end-to-end. Closes open-telemetry#5127 Assisted-by: Claude Opus 4.6

- Use TypeVar for _dict_to_dataclass return — callers now get the correct type instead of Any - Use collections.abc.Mapping for input (more permissive than dict) - Add explicit is_dataclass check at entry — raises TypeError with a descriptive message instead of failing later in dataclasses.fields Assisted-by: Claude Opus 4.6

Astroid 3.x (used by pylint 3.x) follows typing.get_type_hints into Python 3.14's annotationlib, which contains t-string literals it can't parse and crashes with AttributeError on 'visit_templatestr'. Wrapping the call in a helper that returns dict[str, Any] stops the inference at the declared return type. Assisted-by: Claude Opus 4.7

Same effect as the prior helper — declaring the local as ``dict[str, Any]`` stops astroid's inference at the annotation rather than tracing into the typing internals. Assisted-by: Claude Opus 4.7

Single entry point that takes a parsed OpenTelemetryConfiguration, builds the resource, and applies the tracer/meter/logger providers and propagator globally. Honors the top-level disabled flag — when true, no globals are touched. The orchestrator is a thin composition of the existing per-signal configure_* factories; the deeper unification with the env-var path (see open-telemetry#5126) is left for follow-up. Refs open-telemetry#3631 Refs open-telemetry#5126 Assisted-by: Claude Opus 4.7

Assisted-by: Claude Opus 4.7

When the environment variable is set, route the SDK through the declarative config path — load the file via load_config_file() and apply it via configure_sdk() — in place of the env-var-based _initialize_components(). Other OTEL_* vars are ignored (per spec v1.0.0: when a config file is given, it is the sole source of truth). Kwargs passed to _OTelSDKConfigurator._configure are ignored with a warning when the file path is set, so distros that inject kwargs via super() see a clear signal rather than silent drops. The file-loader imports (pyyaml, jsonschema) stay lazy so installs without the file-configuration extras are not affected. Refs open-telemetry#3631 Assisted-by: Claude Opus 4.7

Assisted-by: Claude Opus 4.7

… codespell Replace the bespoke _Level enum (which violated pylint's invalid-name on lowercase members) with the real ExemplarFilter enum from models.py — the generated models use lowercase values verbatim from the JSON schema, so using one of them avoids fighting the linter and exercises the same code path with real data shapes. Add 'astroid' to codespell's ignore-words-list; the prior commit's explanatory comment mentions the library by name and codespell flagged it as a misspelling of 'asteroid'. Assisted-by: Claude Opus 4.7

…-orchestrator

…ting

Move ``SdkTracerProvider`` import to module top (ruff PLC0415 / pylint C0415) and add explicit ``# pylint: disable=no-self-use`` on the three mock-only tests that intentionally do not touch ``self``. Assisted-by: Claude Opus 4.7

…ting

The configure_sdk / load_config_file imports inside ``_configure`` are deliberately deferred so that the SDK does not pull in the optional file-configuration extras (pyyaml, jsonschema) unless ``OTEL_CONFIG_FILE`` is actually set. Annotate with the corresponding pylint and ruff suppressions; the existing comment already explains why. Assisted-by: Claude Opus 4.7

Assisted-by: Claude Opus 4.7

…ting

Assisted-by: Claude Opus 4.7

The conversion module has unit tests that exercise _dict_to_dataclass in isolation, but nothing verified the full pipeline: load a real YAML file, get back fully-typed nested dataclasses, and feed the result into a downstream factory function. Adds two checks built on a representative nested fixture (tracer provider with a parent-based / trace-id-ratio sampler and a batch processor with console exporter): - nested fields (sampler, processors[*].batch) come back as the expected typed dataclasses, not raw dicts - the typed result is accepted by ``create_tracer_provider`` and produces an SDK ``TracerProvider`` This is the integration coverage requested in PR review feedback; the inline example in the PR description is now an actual regression test. Assisted-by: Claude Opus 4.7

…-orchestrator

…ting

Resolve conflicts from merged config orchestrator and conversion work by keeping main's versions of shared modules and tests.

Use a walrus operator in _configure, simplify singleton reset to tearDown only, and hoist no-self-use pylint disable to file scope.

xrmx

LGTM, what do you think of adding a test in a followup PR (in docker-tests?) to check that the plumbing is working e2e?

aabmass · 2026-06-17T15:44:35Z

@MikeGoldsmith do we need to do anything in docs or opentelemetry.io? Also wondering if we can communicate to users that this feature is experimental/under development at this point.

herin049 · 2026-06-18T01:57:03Z

+
+The :envvar:`OTEL_CONFIG_FILE` environment variable points the SDK at a
+declarative configuration file (YAML or JSON). When set, the file is the
+sole source of SDK configuration; other ``OTEL_*`` environment variables


Small comment here, are we certain that this is truly the case? For example the OTEL_PYTHON_* environment variables.

Yeah, I think you're right and the docstring is too broad. I'll update to something like: "the declarative configuration file is the sole source for SDK construction. Spec-defined OTEL_* vars with schema equivalents are ignored. Env vars may still be read indirectly by components the file enables (e.g. resource detectors) and via ${env:VAR} substitution inside the file."

aabmass

🥇 looking forward to using this!

MikeGoldsmith added 9 commits June 3, 2026 10:55

rename changelog fragment to PR open-telemetry#5269

582c37f

inline the typing.get_type_hints wrap

131378c

Same effect as the prior helper — declaring the local as ``dict[str, Any]`` stops astroid's inference at the annotation rather than tracing into the typing internals. Assisted-by: Claude Opus 4.7

rename changelog fragment to PR open-telemetry#5270

fd6c20a

Assisted-by: Claude Opus 4.7

rename changelog fragment to PR open-telemetry#5271

da80d63

Assisted-by: Claude Opus 4.7

MikeGoldsmith mentioned this pull request Jun 3, 2026

Add declarative configuration prototype #3631

Open

30 tasks

MikeGoldsmith added 9 commits June 3, 2026 14:03

Merge branch 'mike/config-recursive-dict-conversion' into mike/config…

83e17bd

…-orchestrator

Merge branch 'mike/config-orchestrator' into mike/config-file-env-rou…

52365e2

…ting

Merge branch 'mike/config-orchestrator' into mike/config-file-env-rou…

119bc83

…ting

remove extra blank line after imports (ruff I001)

41667ca

Assisted-by: Claude Opus 4.7

Merge branch 'mike/config-orchestrator' into mike/config-file-env-rou…

297da35

…ting

collapse multi-line @patch decorators (ruff format)

2b2d47b

Assisted-by: Claude Opus 4.7

MikeGoldsmith added the Approve Public API check This label shows that the public symbols added or changed in a PR are strictly necessary label Jun 3, 2026

MikeGoldsmith added this to Python PR digest Jun 3, 2026

MikeGoldsmith moved this to Ready for review in Python PR digest Jun 3, 2026

MikeGoldsmith mentioned this pull request Jun 5, 2026

feat(config): add public opentelemetry.sdk.configuration namespace #5276

Draft

11 tasks

MikeGoldsmith added 4 commits June 5, 2026 14:38

Merge branch 'mike/config-recursive-dict-conversion' into mike/config…

828c54b

…-orchestrator

Merge branch 'mike/config-orchestrator' into mike/config-file-env-rou…

62cdfa4

…ting

Merge branch 'main' into mike/config-file-env-routing

111fc4a

DylanRussell approved these changes Jun 9, 2026

View reviewed changes

Comment thread opentelemetry-sdk/tests/_configuration/test_configurator_file_routing.py

Comment thread opentelemetry-sdk/tests/_configuration/test_configurator_file_routing.py Outdated

Comment thread opentelemetry-sdk/src/opentelemetry/sdk/_configuration/__init__.py Outdated

MikeGoldsmith changed the title ~~feat(config): honor OTEL_CONFIG_FILE in the SDK configurator~~ feat(config): support OTEL_CONFIG_FILE in the SDK configurator Jun 10, 2026

Merge branch 'main' into mike/config-file-env-routing

e111ebf

Resolve conflicts from merged config orchestrator and conversion work by keeping main's versions of shared modules and tests.

address review feedback on OTEL_CONFIG_FILE routing

73982d9

Use a walrus operator in _configure, simplify singleton reset to tearDown only, and hoist no-self-use pylint disable to file scope.

MikeGoldsmith marked this pull request as ready for review June 16, 2026 10:35

MikeGoldsmith requested a review from a team as a code owner June 16, 2026 10:35

MikeGoldsmith moved this from Ready for review to Approved PRs in Python PR digest Jun 16, 2026

This was referenced Jun 16, 2026

Document declarative (file-based) configuration #5308

Open

docs: add declarative configuration guide and example #5309

Draft

Merge branch 'main' into mike/config-file-env-routing

df88a20

xrmx approved these changes Jun 17, 2026

View reviewed changes

xrmx moved this from Approved PRs to Ready for merge in Python PR digest Jun 17, 2026

MikeGoldsmith mentioned this pull request Jun 17, 2026

feat(config): add docker-tests e2e for OTEL_CONFIG_FILE plumbing #5318

Open

Merge branch 'main' into mike/config-file-env-routing

4a41603

herin049 approved these changes Jun 18, 2026

View reviewed changes

aabmass approved these changes Jun 18, 2026

View reviewed changes

Comment thread .changelog/5271.added

MikeGoldsmith mentioned this pull request Jun 18, 2026

[python] Document declarative (file-based) configuration open-telemetry/opentelemetry.io#10475

Open

xrmx moved this from Ready for merge to Approved PRs that need fixes in Python PR digest Jun 18, 2026

herin049 approved these changes Jun 18, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(config): support OTEL_CONFIG_FILE in the SDK configurator#5271

feat(config): support OTEL_CONFIG_FILE in the SDK configurator#5271
MikeGoldsmith wants to merge 26 commits into
open-telemetry:mainfrom
MikeGoldsmith:mike/config-file-env-routing

MikeGoldsmith commented Jun 3, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

xrmx left a comment

Uh oh!

aabmass commented Jun 17, 2026

Uh oh!

herin049 Jun 18, 2026

Uh oh!

MikeGoldsmith Jun 18, 2026

Uh oh!

aabmass left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

MikeGoldsmith commented Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Behavior

Implementation notes

Type of change

How Has This Been Tested?

Does This PR Require a Contrib Repo Change?

Checklist:

Uh oh!

Uh oh!

Uh oh!

Uh oh!

xrmx left a comment

Choose a reason for hiding this comment

Uh oh!

aabmass commented Jun 17, 2026

Uh oh!

herin049 Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

MikeGoldsmith Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

aabmass left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

MikeGoldsmith commented Jun 3, 2026 •

edited

Loading