Skip to content

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

Open
MikeGoldsmith wants to merge 22 commits into
open-telemetry:mainfrom
MikeGoldsmith:mike/extract-sdk-configuration
Open

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

Conversation

@MikeGoldsmith

@MikeGoldsmith MikeGoldsmith commented Jun 25, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

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

@MikeGoldsmith
extract declarative configuration into opentelemetry-sdk-configuratio…
949fd69 
…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
@MikeGoldsmith
rename changelog fragment to PR open-telemetry#5356
d7ba5da
@MikeGoldsmith MikeGoldsmith marked this pull request as ready for review June 25, 2026 18:10
@MikeGoldsmith MikeGoldsmith requested a review from a team as a code owner June 25, 2026 18:10
@MikeGoldsmith MikeGoldsmith moved this to Ready for merge in Python PR digest Jun 25, 2026
@MikeGoldsmith 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
herin049
herin049 reviewed Jun 25, 2026
View reviewed changes
Comment thread .changelog/5356.changed Outdated
@herin049

herin049 commented Jun 25, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

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?

@xrmx xrmx moved this from Ready for merge to Ready for review in Python PR digest Jun 26, 2026
@MikeGoldsmith 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
emdneto
emdneto reviewed Jun 26, 2026
View reviewed changes
Comment thread pyproject.toml
@MikeGoldsmith

MikeGoldsmith commented Jun 26, 2026

Copy link
Copy Markdown
Member Author

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.

  1. 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.
  2. 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.

@MikeGoldsmith
silence pylint no-name-in-module on conditional opentelemetry.configu…
5877b3e 
…ration import (not installed in sdk lint env)
@herin049

herin049 commented Jun 27, 2026

Copy link
Copy Markdown
Contributor

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.

  1. 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.
  2. 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
herin049 approved these changes Jun 27, 2026
View reviewed changes
Comment thread opentelemetry-configuration/pyproject.toml
carlosalberto
carlosalberto approved these changes Jul 2, 2026
View reviewed changes
Comment thread opentelemetry-configuration/pyproject.toml
Comment thread opentelemetry-configuration/pyproject.toml
@carlosalberto

carlosalberto commented Jul 2, 2026

Copy link
Copy Markdown
Contributor

Symbolic approval as this is aligning matters with what other SIGs do ;)

@MikeGoldsmith MikeGoldsmith mentioned this pull request Jul 6, 2026
Open
@MikeGoldsmith
Merge branch 'main' into mike/extract-sdk-configuration
2f19ee6
@MikeGoldsmith
Merge remote-tracking branch 'upstream/main' into mike/extract-sdk-co…
074705c 
…nfiguration

# Conflicts:
#	opentelemetry-sdk/src/opentelemetry/sdk/_configuration/README.md
@MikeGoldsmith
Merge remote-tracking branch 'upstream/main' into mike/extract-sdk-co…
92fffcf 
…nfiguration

# Conflicts:
#	opentelemetry-configuration/src/opentelemetry/configuration/_tracer_provider.py
#	opentelemetry-configuration/tests/test_tracer_provider.py
@MikeGoldsmith
Merge remote-tracking branch 'origin/mike/extract-sdk-configuration' …
6ca3e0d 
…into mike/extract-sdk-configuration
@MikeGoldsmith
Merge branch 'main' into mike/extract-sdk-configuration
7901696
lzchen
lzchen reviewed Jul 7, 2026
View reviewed changes
Comment thread opentelemetry-configuration/pyproject.toml
"Typing :: Typed",
]
dependencies = [
"opentelemetry-api == 1.44.0.dev",

@lzchen lzchen Jul 7, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we use ~= in the future once a prod version of api and sdk are released?

@MikeGoldsmith MikeGoldsmith Jul 8, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated the tracking issue for config package deps to review this before 1.0:

@lzchen

lzchen commented Jul 7, 2026

Copy link
Copy Markdown
Contributor

Probably should merge the smaller: #5372, #5396 and #5265 first and rebase this after.

@MikeGoldsmith

MikeGoldsmith commented Jul 8, 2026

Copy link
Copy Markdown
Member Author

Probably should merge the smaller: #5372, #5396 and #5265 first and rebase this after.

I agree, let's land those before this PR or it will introduce a fair amount of friction.

@emdneto emdneto mentioned this pull request Jul 8, 2026
Open
4 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@emdneto emdneto emdneto left review comments
@herin049 herin049 herin049 approved these changes
@carlosalberto carlosalberto carlosalberto approved these changes
@lzchen lzchen lzchen approved these changes
+1 more reviewer
@ocelotl ocelotl ocelotl approved these changes
Reviewers whose approvals may not affect merge requirements

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

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

Projects

Python PR digest
Status: Ready for review

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

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

7 participants

@MikeGoldsmith @herin049 @carlosalberto @lzchen @ocelotl @emdneto @xrmx