feat(config): Add TracerProvider support for declarative config by MikeGoldsmith · Pull Request #4985 · open-telemetry/opentelemetry-python

MikeGoldsmith · 2026-03-16T14:58:40Z

Description

Implements create_tracer_provider() and configure_tracer_provider() for the declarative configuration pipeline, as part of the ongoing work tracked in the following PR:

Add declarative configuration prototype #3631.

Note

This PR is based on #4979 (Resource & Propagator creation) which must be merged first. The extra commits at the base of this branch will be dropped once that PR lands.

What's included

_tracer_provider.py: creates an SDK TracerProvider from declarative config
Supports all sampler types: always_on, always_off, trace_id_ratio_based, parent_based (with all 4 delegate samplers)
Supports BatchSpanProcessor and SimpleSpanProcessor
Supports OTLP HTTP, OTLP gRPC, and Console span exporters
Lazy imports for optional OTLP packages with a ConfigurationError if not installed
SpanLimits and sampler use OTel spec defaults for absent fields — no env-var leakage
configure_tracer_provider(None) is a no-op per spec/Java/JS behavior
32 new tests covering all paths including env-var suppression

Env-var suppression

Python's TracerProvider reads OTEL_TRACES_SAMPLER when sampler=None, and SpanLimits reads OTEL_SPAN_*_LIMIT when fields are None. To match the spec's "what you see is what you get" semantics (and Java SDK behavior), we always pass explicit values — defaulting to spec defaults (e.g. ParentBased(root=ALWAYS_ON), 128 for count limits) rather than falling through to env vars.

Type of change

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
This change requires a documentation update

How Has This Been Tested?

32 unit tests in tests/_configuration/test_tracer_provider.py
Includes explicit tests that env vars (OTEL_TRACES_SAMPLER, OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT) are not read when config is used

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

Assisted-by: Claude Sonnet 4.6

Implements create_resource() and create_propagator()/configure_propagator() for the declarative file configuration. Resource creation does not read OTEL_RESOURCE_ATTRIBUTES or run any detectors (matches Java/JS SDK behavior). Propagator configuration always calls set_global_textmap to override Python's default tracecontext+baggage, setting a noop CompositePropagator when no propagator is configured. Assisted-by: Claude Sonnet 4.6

Assisted-by: Claude Sonnet 4.6

- _resource.py: refactor _coerce_attribute_value to dispatch table to avoid too-many-return-statements; fix short variable names k/v -> attr_key/attr_val; fix return type of _sdk_default_attributes to dict[str, str] to satisfy pyright - _propagator.py: rename short variable names e -> exc, p -> propagator - test_resource.py: move imports to top level; split TestCreateResource (25 methods) into three focused classes to satisfy too-many-public-methods - test_propagator.py: add pylint disable for protected-access Assisted-by: Claude Sonnet 4.6

- replace _sdk_default_attributes() with _DEFAULT_RESOURCE from resources module - move _coerce_bool into dispatch tables for both scalar and array bool types, fixing a bug where bool_array with string values like "false" would coerce incorrectly via plain bool() (non-empty string -> True) - add test for bool_array with string values to cover the bug Assisted-by: Claude Sonnet 4.6

… into mike/config-resource-propagator

Assisted-by: Claude Sonnet 4.6

…erge - collapse _SCALAR_COERCIONS and _ARRAY_COERCIONS into a single _COERCIONS dict using an _array() factory, reducing _coerce_attribute_value to two lines - process attributes_list before attributes so explicit attributes naturally overwrite list entries without needing an explicit guard Assisted-by: Claude Sonnet 4.6

opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_resource.py

JWinermaSplunk · 2026-03-17T21:01:20Z

opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_propagator.py

+    return CompositePropagator(propagators)
+
+
+def configure_propagator(config: Optional[PropagatorConfig]) -> None:


Correct me if I'm wrong, but did we want to silently disable trace context, baggage propagation for an empty propagator section in the config file?

The intention here is "what you see is what you get" (WYSIWYG) semantics as defined in the declarative config contributing guide:

implementations should minimize the amount of magic that occurs as a result of the absence of an optional property

So if propagators is absent or empty in the config file, the intent is that no propagators are configured — not that we fall back to the SDK defaults of tracecontext+baggage. WYSIWYG: there are no propagators in the config, you get no propagators.

This is intentional and consistent with how e.g. an absent meter_provider results in a noop meter provider rather than a default one with a periodic reader and OTLP exporter.

Assisted-by: Claude Sonnet 4.6

…e-propagator

Adds _run_detectors() stub and _filter_attributes() to create_resource(), providing the shared scaffolding for detector PRs to build on. Detectors are opt-in: nothing runs unless explicitly listed under detection_development.detectors in the config. The include/exclude attribute filter mirrors other SDK behaviour. Assisted-by: Claude Sonnet 4.6

Merges service.name=unknown_service into base before running detectors, so detectors (e.g. service) can override it. Previously it was added to config_attrs and merged last, which would have silently overridden any detector-provided service.name. Assisted-by: Claude Sonnet 4.6

Assisted-by: Claude Sonnet 4.6

Implements create_tracer_provider() and configure_tracer_provider() for the declarative configuration pipeline (tracking issue open-telemetry#3631 step 5). Key behaviors: - Never reads OTEL_TRACES_SAMPLER or OTEL_SPAN_*_LIMIT env vars; absent config fields use OTel spec defaults (matching Java SDK behavior) - Default sampler is ParentBased(root=ALWAYS_ON) per the OTel spec - SpanLimits absent fields use hardcoded defaults (128) not env vars - configure_tracer_provider(None) is a no-op per spec/Java/JS behavior - OTLP exporter fields pass None through so the exporter reads its own env vars for unspecified values - Lazy imports for optional OTLP packages with ConfigurationError on missing - Supports all 4 ParentBased delegate samplers Assisted-by: Claude Sonnet 4.6

Assisted-by: Claude Sonnet 4.6

@staticmethod

- add # noqa: PLC0415 to lazy OTLP imports (ruff also enforces this) - move SDK imports to top-level (BatchSpanProcessor, etc.) - convert test helper methods to @staticmethod to satisfy no-self-use - add pylint: disable=protected-access for private member access in tests - fix return type annotation on _create_span_processor Assisted-by: Claude Sonnet 4.6

Assisted-by: Claude Sonnet 4.6

herin049 · 2026-03-21T03:31:35Z

opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_tracer_provider.py

+    """
+    if headers is None and headers_list is None:
+        return None
+    result: Dict[str, str] = {}


nit:

Suggested change

result: Dict[str, str] = {}

result: dict[str, str] = {}

herin049 · 2026-03-21T03:34:12Z

opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_tracer_provider.py

+    if headers is None and headers_list is None:
+        return None
+    result: Dict[str, str] = {}
+    if headers_list:


This function is nearly identical to _parse_attributes_list, can we create a more general shared function that can ideally be used in both places?

MikeGoldsmith added 6 commits March 13, 2026 13:04

update changelog with PR number

8232012

Assisted-by: Claude Sonnet 4.6

fix linter

8232d48

Merge branch 'main' of github.com:open-telemetry/opentelemetry-python…

6ed3425

… into mike/config-resource-propagator

MikeGoldsmith added a commit to MikeGoldsmith/opentelemetry-python that referenced this pull request Mar 16, 2026

add changelog entry for PR open-telemetry#4985

fa2a435

Assisted-by: Claude Sonnet 4.6

JWinermaSplunk reviewed Mar 17, 2026

View reviewed changes

MikeGoldsmith changed the title ~~feat(config): TracerProvider creation from declarative config~~ feat(config): Add TracerProvider support for declarative config Mar 18, 2026

xrmx mentioned this pull request Mar 20, 2026

Add declarative configuration prototype #3631

Open

8 tasks

MikeGoldsmith added 4 commits March 20, 2026 14:18

use Callable type annotation on _array helper

8ba91d8

Assisted-by: Claude Sonnet 4.6

Merge remote-tracking branch 'upstream/main' into mike/config-resourc…

516aecc

…e-propagator

MikeGoldsmith added a commit to MikeGoldsmith/opentelemetry-python that referenced this pull request Mar 20, 2026

add changelog entry for PR open-telemetry#4985

a7edb8f

Assisted-by: Claude Sonnet 4.6

MikeGoldsmith force-pushed the mike/config-tracer-provider branch from a54d5b1 to 9653d67 Compare March 20, 2026 14:30

MikeGoldsmith added 6 commits March 20, 2026 18:22

remove unused logging import from _propagator.py

7f51034

Assisted-by: Claude Sonnet 4.6

add changelog entry for PR open-telemetry#4985

90bc125

Assisted-by: Claude Sonnet 4.6

fix pylint no-self-use on TestCreateSampler._make_provider

732ed92

Assisted-by: Claude Sonnet 4.6

use allowlist for bool coercion in declarative config resource

232b06f

Assisted-by: Claude Sonnet 4.6

MikeGoldsmith force-pushed the mike/config-tracer-provider branch from 9653d67 to 232b06f Compare March 20, 2026 18:35

herin049 reviewed Mar 21, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(config): Add TracerProvider support for declarative config#4985

feat(config): Add TracerProvider support for declarative config#4985
MikeGoldsmith wants to merge 17 commits intoopen-telemetry:mainfrom
MikeGoldsmith:mike/config-tracer-provider

MikeGoldsmith commented Mar 16, 2026 •

edited

Loading

Uh oh!

Uh oh!

JWinermaSplunk Mar 17, 2026

Uh oh!

MikeGoldsmith Mar 18, 2026

Uh oh!

herin049 Mar 21, 2026

Uh oh!

herin049 Mar 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		return CompositePropagator(propagators)


		def configure_propagator(config: Optional[PropagatorConfig]) -> None:

Conversation

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

Uh oh!

Description

What's included

Env-var suppression

Type of change

How Has This Been Tested?

Does This PR Require a Contrib Repo Change?

Checklist:

Uh oh!

Uh oh!

JWinermaSplunk Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

MikeGoldsmith Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

herin049 Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

herin049 Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

MikeGoldsmith commented Mar 16, 2026 •

edited

Loading