Background

Per the Python SIG discussion on 2026-06-25, the declarative configuration code currently lives under `opentelemetry-sdk/src/opentelemetry/sdk/_configuration/` (underscore-prefixed, intentionally private). Promoting it to a public namespace inside the SDK was rejected because:

• The SDK is stable; declarative config still has rough edges and changes shape regularly. Pinning the stable SDK to follow declarative-config churn is the wrong trade-off.
• Other languages (JS, Java) ship configuration as a separate package, which gives a clear "experimental" signal and lets it version independently.
• Distros / system packages benefit from the configuration being a separate dependency they can opt into.

SIG attendees agreed: extract into a new package, public types, marked experimental, versioned independently of `opentelemetry-sdk`.

Proposed package

New: `opentelemetry-sdk-configuration`

• Import path: `opentelemetry.sdk.configuration` (no underscore prefix; types are public).
• Houses: `schema.json`, `models.py`, `_loader.py`, `_sdk.py` (`configure_sdk`), `_conversion.py`, all per-signal factories, `_exceptions.py`.
• Hard runtime dependency on `opentelemetry-sdk` (factories construct SDK objects).
• Initial version `0.1.0` or similar; clearly marked experimental in README and `pyproject.toml` classifiers.

Existing: `opentelemetry-sdk` (slimmed)

• Keep: `OTEL_CONFIG_FILE` env var constant in `opentelemetry.sdk.environment_variables`.
• Keep: `_OTelSDKConfigurator._configure` env-var detection. When `OTEL_CONFIG_FILE` is set, lazy-import `opentelemetry.sdk.configuration` and call `configure_sdk(load_config_file(path))`.
• No runtime dependency on the new package. Lambda users who don't set `OTEL_CONFIG_FILE` pay zero import cost.
• Drop `opentelemetry/sdk/_configuration/` entirely (no deprecation shim; the package was intentionally private).

Migration steps

1. Scaffold `opentelemetry-sdk-configuration/` package: directory layout, `pyproject.toml`, README, dev-requirements, tox env entries, CI matrix.
2. Move every file under `opentelemetry-sdk/src/opentelemetry/sdk/_configuration/` to `opentelemetry-sdk-configuration/src/opentelemetry/sdk/configuration/`. Vendor `schema.json` into the new package. Move tests to `opentelemetry-sdk-configuration/tests/`.
3. Rewire `_OTelSDKConfigurator._configure` in `opentelemetry-sdk` to lazy-import `opentelemetry.sdk.configuration` only when `OTEL_CONFIG_FILE` is set.
4. Remove the now-empty `opentelemetry/sdk/_configuration/` directory from the SDK.
5. Update changelog fragments in both packages describing the move.

In-flight PRs and their migration

• feat(config): add public opentelemetry.sdk.configuration namespace #5276 (promote `_configuration` to public namespace): close, superseded by this work.
• docs(config): link to shared declarative config spec conformance matrix #5347 (link Python README to shared matrix): retarget the README change into the new package's README. Keep open.
• opentelemetry-sdk: add support for file exporter with declarative config #5311 (file exporter), fix(config): align additional_properties typing #5286 (typing fix), feat(sdk): add MissingDependencyError for declarative configuration #5265 (MissingDependencyError), feat(config): wire top-level log_level field in declarative configuration #5351 (`log_level`), docs(config): document OTEL_PYTHON_* bypass when OTEL_CONFIG_FILE is set #5353 (OTEL_PYTHON_* doc): continue landing in `opentelemetry-sdk._configuration` as today. The extraction carries them across in a single file move.

Follow-ups (separate issues, not gating)

• Experimental language-override mechanism (per Riccardo / Michele in the SIG).
• Move API-level configuration types to `opentelemetry-api` (per Liudmila). Scope TBD.
• Lambda cold-start measurement once the extraction lands (per Lukas).

Related

• Add declarative configuration prototype #3631 declarative configuration tracking issue
• feat(config): add public opentelemetry.sdk.configuration namespace #5276 (will be closed by this work)
• SIG notes 2026-06-25