feat(config): extract declarative configuration into opentelemetry-configuration package by MikeGoldsmith · Pull Request #5356 · open-telemetry/opentelemetry-python

MikeGoldsmith · 2026-06-25T18:07:58Z

Description

Per the Python SIG on 2026-06-25, declarative configuration moves out of opentelemetry-sdk into a new opentelemetry-configuration package. The SDK stays slim and stable; declarative config lives in its own package with public types, an experimental marker, and an independent release cadence.

Core changes

New opentelemetry-configuration package owns the schema, models, loader, env substitution, configure_sdk, per-signal factories, and exceptions. Public namespace is opentelemetry.configuration (the old opentelemetry.sdk._configuration private namespace is dropped, no shim). pyyaml and jsonschema are required runtime dependencies.
opentelemetry-sdk keeps OTEL_CONFIG_FILE and the _OTelSDKConfigurator activation hook. When the env var is set, it lazy-imports the new package and calls configure_sdk(load_config_file(path)); otherwise no import happens, so users who don't opt in pay zero cost.
If OTEL_CONFIG_FILE is set but opentelemetry-configuration is not installed, the SDK raises a RuntimeError with a pip-install hint instead of a bare ImportError.
pyproject.toml codegen, tox.ini envs, and CI workflows are updated accordingly.

Closes #5355
Refs #3631

Type of change

New feature (non-breaking change which adds functionality)
Breaking change (only for callers reaching into private opentelemetry.sdk._configuration paths)

How Has This Been Tested?

Every existing declarative-config test moves verbatim into the new package (333 tests, all passing, including the new #5311 tests for the file exporter). The SDK suite (804 tests) passes, with the routing test rewritten to patch the new module paths and cover the missing-package case. Ruff + format clean across both packages.

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

…n package Per the Python SIG on 2026-06-25 (tracked in open-telemetry#5355), declarative configuration moves out of opentelemetry-sdk into a new standalone package. The SDK stays slim and stable; declarative-config-specific code lives in opentelemetry-sdk-configuration which can iterate and version independently with an experimental marker. Layout: opentelemetry-sdk-configuration/ pyproject.toml new package manifest README.rst experimental marker, install hint src/opentelemetry/sdk/configuration/ the public namespace __init__.py public API: configure_sdk, load_config_file, OpenTelemetryConfiguration, ConfigurationError _exceptions.py, _common.py, _conversion.py, _sdk.py, _resource.py, _propagator.py, _tracer_provider.py, _meter_provider.py, _logger_provider.py, models.py, schema.json file/__init__.py, file/_loader.py, file/_env_substitution.py version/__init__.py 0.1.0.dev codegen/dataclass.jinja2 moved from opentelemetry-sdk/codegen tests/ all moved from opentelemetry-sdk/tests/_configuration test-requirements.txt opentelemetry-sdk keeps only what activates the declarative path: - OTEL_CONFIG_FILE env var constant in opentelemetry.sdk.environment_variables - _OTelSDKConfigurator._configure detects the env var and lazy-imports opentelemetry.sdk.configuration. The SDK has no runtime dep on the new package; lambda / no-config users pay zero import cost. - When OTEL_CONFIG_FILE is set but the new package isn't installed, raise a clear RuntimeError with a pip-install hint instead of a bare ImportError. Top-level updates: - pyproject.toml: codegen input/output paths and additional-imports point at the new package. ruff per-file-ignore for test_models.py updated. file-configuration extras moved off opentelemetry-sdk. - tox.ini: adds test-/lint- envs for opentelemetry-sdk-configuration; coverage env switches from opentelemetry-sdk[file-configuration] to the standalone configuration package. Tests: - 309 tests in opentelemetry-sdk-configuration/tests pass. - 789 tests in opentelemetry-sdk/tests pass (incl. rewritten test_configurator_file_routing.py which now patches the new module paths and covers the missing-package RuntimeError). Closes open-telemetry#5355

…nfiguration

…lint/typecheck on lazy import, fix link-check placeholder

…m schema README

…d deps

herin049 · 2026-06-25T23:02:27Z

@@ -0,0 +1 @@
+Declarative configuration moves from `opentelemetry.sdk._configuration` into the new public `opentelemetry-sdk-configuration` package (`opentelemetry.sdk.configuration` namespace), published experimentally and versioned independently of the SDK.


Can you prefix this with opentelemetry-sdk-configuration?

herin049 · 2026-06-25T23:05:51Z

I'm somewhat suprised this package structure is installable alongside the opentelemetry-sdk given that the SDK includes an __init__.pyi under opentelemetry/sdk/. Maybe we should just have this package be something like opentelemetry-configuration and have everything live under opentelemetry/configuration and/or remove the __init__.pyi file from the SDK for safety.

This should probably be fine at runtime, can we verify that type checking works properly for someone using both opentelemetry-sdk and opentelemetry-sdk-configuration?

…r namespace package; revert lint/typecheck workarounds

…(module path opentelemetry.configuration); restore sdk __init__.pyi

… fake module

…lint disable

emdneto · 2026-06-26T11:58:34Z

 members = [
  "opentelemetry-api",
  "opentelemetry-sdk",
+  "opentelemetry-configuration",


can you also add to the typecheck include list?

MikeGoldsmith · 2026-06-26T12:19:02Z

I'm somewhat suprised this package structure is installable alongside the opentelemetry-sdk given that the SDK includes an __init__.pyi under opentelemetry/sdk/. Maybe we should just have this package be something like opentelemetry-configuration and have everything live under opentelemetry/configuration and/or remove the __init__.pyi file from the SDK for safety.

This should probably be fine at runtime, can we verify that type checking works properly for someone using both opentelemetry-sdk and opentelemetry-sdk-configuration?

Thanks @herin049.

I've decided to rename to opentelemetry-configuration with module path opentelemetry.configuration.* as a peer to api, sdk, proto, semantic-conventions instead of extending the SDK namespace.

Two things pushed me that way.

Of our ~50 OTel Python packages, only one has -sdk- in its name (opentelemetry-sdk-extension-aws) and every other package is named after what it does.
The config package names in other SDKs are super inconsistent. Java keeps it under sdk.*, JS and Go use peer, so Python conventions and your namespace-extension make sense.

Since we no longer extend opentelemetry.sdk.*, I restored the SDK's __init__.pyi and dropped the type-ignore / pylint workarounds too.

Let me know what you think.

…ration import (not installed in sdk lint env)

herin049 · 2026-06-27T18:31:58Z

I'm somewhat suprised this package structure is installable alongside the opentelemetry-sdk given that the SDK includes an __init__.pyi under opentelemetry/sdk/. Maybe we should just have this package be something like opentelemetry-configuration and have everything live under opentelemetry/configuration and/or remove the __init__.pyi file from the SDK for safety.
This should probably be fine at runtime, can we verify that type checking works properly for someone using both opentelemetry-sdk and opentelemetry-sdk-configuration?

Thanks @herin049.

I've decided to rename to opentelemetry-configuration with module path opentelemetry.configuration.* as a peer to api, sdk, proto, semantic-conventions instead of extending the SDK namespace.

Two things pushed me that way.

Of our ~50 OTel Python packages, only one has -sdk- in its name (opentelemetry-sdk-extension-aws) and every other package is named after what it does.

The config package names in other SDKs are super inconsistent. Java keeps it under sdk.*, JS and Go use peer, so Python conventions and your namespace-extension make sense.

Since we no longer extend opentelemetry.sdk.*, I restored the SDK's __init__.pyi and dropped the type-ignore / pylint workarounds too.

Let me know what you think.

I think this is the right call, we can always keep a lightweight user-facing API in opentelemetry-sdk under opentelemetry.sdk.configuration.

herin049 · 2026-06-27T18:44:15Z

+  "Typing :: Typed",
+]
+dependencies = [
+  "opentelemetry-api == 1.44.0.dev",


I have a few questions/comments on the dependencies here.

Can we loosen the SDK/API compatibility by declaring opentelemetry-api ~= 1.44.0.dev (and likewise opentelemetry-sdk) so that this package can rely on newer versions of the API/SDK. This should be safe to do as long as we don't rely on anything internal to the API/SDK that could break across minor versions. Edit: Actually, we probably need to pin as you have here because we support developmental/unstable functionality from the SDK.

Is typing-extensions explicitly used in this package, and/or is it only used within a TYPE_CHECKING block? If not, we can probably remove this dependency.

Can we make pyyaml >= 6.0 an optional dependency, perhaps under the extra yaml? I'm not sure how common it is, but it's possible that some users may choose not to read directly from a YAML file (e.g. JSON instead). If you don't think this is that common, I'm fine with keeping it in the default dependencies.

On a similar note to 3. can we make the version ranges for the pyyaml and jsonschema dependencies a little looser, to give our user's a more flexible compatibility window?

MikeGoldsmith added 2 commits June 25, 2026 18:35

rename changelog fragment to PR open-telemetry#5356

d7ba5da

MikeGoldsmith marked this pull request as ready for review June 25, 2026 18:10

MikeGoldsmith requested a review from a team as a code owner June 25, 2026 18:10

otelbot-python Bot added this to Python PR digest Jun 25, 2026

MikeGoldsmith moved this to Ready for merge in Python PR digest Jun 25, 2026

MikeGoldsmith added 4 commits June 25, 2026 19:21

Merge remote-tracking branch 'upstream/main' into mike/extract-sdk-co…

a40d653

…nfiguration

register opentelemetry-sdk-configuration in uv workspace

3c90d9c

fix CI: regenerate workflows, mock new pkg in routing tests, silence …

4f62d78

…lint/typecheck on lazy import, fix link-check placeholder

fix CI: per-package pylintrc for sdk-configuration, drop bad link fro…

9eba9f6

…m schema README

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

MikeGoldsmith added 2 commits June 25, 2026 21:41

drop file-configuration extras: pyyaml and jsonschema are now require…

3cde032

…d deps

tighten 5356 changelog entry

1b4f949

ocelotl approved these changes Jun 25, 2026

View reviewed changes

herin049 reviewed Jun 25, 2026

View reviewed changes

xrmx moved this from Ready for merge to Ready for review in Python PR digest Jun 26, 2026

MikeGoldsmith added 3 commits June 26, 2026 11:14

merge upstream/main; prefix 5356 changelog entry with package name

bf27ea4

drop opentelemetry/sdk/__init__.pyi to make opentelemetry.sdk a prope…

7641371

…r namespace package; revert lint/typecheck workarounds

rename opentelemetry-sdk-configuration → opentelemetry-configuration …

ac255fe

…(module path opentelemetry.configuration); restore sdk __init__.pyi

MikeGoldsmith changed the title ~~feat(config): extract declarative configuration into opentelemetry-sdk-configuration package~~ feat(config): extract declarative configuration into opentelemetry-configuration package Jun 26, 2026

MikeGoldsmith added 2 commits June 26, 2026 12:36

post-rename CI fixes: ruff import sort + disable no-member on dynamic…

9b7795b

… fake module

use class-based fake module in routing tests to drop the no-member py…

e76b325

…lint disable

emdneto reviewed Jun 26, 2026

View reviewed changes

silence pylint no-name-in-module on conditional opentelemetry.configu…

5877b3e

…ration import (not installed in sdk lint env)

herin049 approved these changes Jun 27, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(config): extract declarative configuration into opentelemetry-configuration package#5356

feat(config): extract declarative configuration into opentelemetry-configuration package#5356
MikeGoldsmith wants to merge 14 commits into
open-telemetry:mainfrom
MikeGoldsmith:mike/extract-sdk-configuration

MikeGoldsmith commented Jun 25, 2026 •

edited

Loading

Uh oh!

herin049 Jun 25, 2026

Uh oh!

herin049 commented Jun 25, 2026 •

edited

Loading

Uh oh!

emdneto Jun 26, 2026

Uh oh!

MikeGoldsmith commented Jun 26, 2026

Uh oh!

herin049 commented Jun 27, 2026

Uh oh!

herin049 Jun 27, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

		@@ -0,0 +1 @@
		Declarative configuration moves from `opentelemetry.sdk._configuration` into the new public `opentelemetry-sdk-configuration` package (`opentelemetry.sdk.configuration` namespace), published experimentally and versioned independently of the SDK.

Uh oh!

Conversation

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

Uh oh!

Description

Core changes

Type of change

How Has This Been Tested?

Does This PR Require a Contrib Repo Change?

Checklist:

Uh oh!

herin049 Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Uh oh!

emdneto Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

MikeGoldsmith commented Jun 26, 2026

Uh oh!

herin049 commented Jun 27, 2026

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

MikeGoldsmith commented Jun 25, 2026 •

edited

Loading

herin049 commented Jun 25, 2026 •

edited

Loading

herin049 Jun 27, 2026 •

edited

Loading