Implement declarative config ConfigProvider / ConfigProperties API by ocelotl · Pull Request #5486 · open-telemetry/opentelemetry-python

ocelotl · 2026-07-29T22:19:56Z

Description

Implements the declarative configuration Instrumentation Configuration API
(configuration/api.md),
which was previously not implemented in Python.

ConfigProperties — a typed, schemaless read view over a parsed
configuration mapping node: get_string, get_bool, get_int, get_float,
get_config (nested view), get_config_list, the scalar-sequence getters
get_string_list, get_bool_list, get_int_list and get_float_list,
keys(), and __contains__. Getters return None on a missing key or type
mismatch, matching the spec and Java's DeclarativeConfigProperties
semantics. The spec requires accessors for "sequences of scalars" without
naming them, and asks for type safety "based on what is idiomatic in the
language", so Python uses one typed getter per scalar type rather than
Java's getScalarList(name, Class<T>), which only takes a type token
because of type erasure.
ConfigProvider — holds the ConfigProperties for the .instrumentation
config node and exposes get_instrumentation_config().
A global default ConfigProvider with get_config_provider() /
set_config_provider(), so instrumentation libraries can access configuration
during initialization.
configure_sdk now builds a ConfigProvider from the .instrumentation
node and installs it as the global (empty when the node is absent).

All symbols are exported from opentelemetry.configuration.

Scope

This PR is intentionally scoped to the API surface (ConfigProvider /
ConfigProperties) and its wiring into configure_sdk. The related but separate
concern of making Create/configure_sdk return the top-level SDK components as
a pure builder is not included here and can be tracked separately.

Fixes #5485.

Type of change

New feature (non-breaking change which adds functionality)

ConfigProvider is Development stability in the spec; the package is already
marked experimental. ConfigProperties is Stable in the spec.

How Has This Been Tested?

New opentelemetry-configuration/tests/test_config_provider.py (40 tests)
covering scalar getters, type-mismatch/None behavior, bool/int
disambiguation, nested get_config/get_config_list, the typed scalar-list
getters, a key present with a null value versus an absent key,
dataclass-node normalization, and the global provider get/set.
Full opentelemetry-configuration suite passes locally (421 passed, 29
subtests) — no regressions from the configure_sdk wiring.

Does This PR Require a Contrib Repo Change?

No.

Checklist

Followed the style guidelines of this project
Unit tests have been added
Added a changelog entry (.changelog/5485.added; will rename to the PR
number if preferred)

ocelotl · 2026-07-29T23:33:11Z

Updated the global ConfigProvider to follow the same convention as set_tracer_provider/get_tracer_provider (and metrics/_logs):

set_config_provider is now set-once, guarded by a thread-safe Once. A second call logs "Overriding of current ConfigProvider is not allowed" and keeps the existing provider (previously it warned but overwrote, and wasn't thread-safe).
get_config_provider() now returns a NoOpConfigProvider (empty instrumentation config) when none is set instead of None, so callers can traverse the tree without None checks — mirroring ProxyTracerProvider and Java's ConfigProvider.noop(). Return type is non-optional.

NoOpConfigProvider is exported. Added a set-once test; full opentelemetry-configuration suite passes (407 passed, 29 subtests).

ocelotl · 2026-07-30T00:59:42Z

@jack-berg @trask @mmanciop

herin049 · 2026-07-31T01:54:43Z

+        _logger.warning("Overriding of current ConfigProvider is not allowed")
+
+
+def get_config_provider() -> ConfigProvider:


I'm not sure if making the ConfigProvider accessible before initialization in a similar manner to Tracers/Loggers/Meter is desirable in this case. Why not just forward it as an argument to the instrument function on instrumentor classes and provide a no-op config provider if not initialized? What exactly is the global state buying us here as opposed to threading it through regular function calls? I'd imagine that receiving a ProxyConfigProvider instance wouldn't be that useful since consumers will almost always read from the configuration immediately.

I don't disagree, I'm following this approach for consistency. Even if we follow the approach suggested in this PR we would do no harm, so we get something that is consistent with the rest of the providers and we get a harmless possible scenario.

Copilot

Pull request overview

Adds the OpenTelemetry declarative Instrumentation Configuration API surface to the opentelemetry-configuration package, and wires it into configure_sdk so instrumentation libraries can read the parsed .instrumentation node via a global provider.

Changes:

Introduces ConfigProperties (typed read view over a mapping node) and ConfigProvider (exposes instrumentation config), plus global get_config_provider/set_config_provider with proxy-default + set-once semantics.
Updates configure_sdk to build a ConfigProvider from the instrumentation config node and install it globally.
Adds a comprehensive unit test suite for scalar/structured accessors and global provider behavior.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
opentelemetry-configuration/src/opentelemetry/configuration/_config_provider.py	New `ConfigProvider`/`ConfigProperties` implementation and global provider registry.
opentelemetry-configuration/src/opentelemetry/configuration/_sdk.py	Wires `configure_sdk` to set the global `ConfigProvider` based on instrumentation config.
opentelemetry-configuration/src/opentelemetry/configuration/init.py	Exports the new public API symbols from `opentelemetry.configuration`.
opentelemetry-configuration/tests/test_config_provider.py	Adds unit tests for getters, type-mismatch behavior, node normalization, and global get/set semantics.
.changelog/5486.added	Documents the new configuration API surface and `configure_sdk` wiring.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+        result: list[ConfigProperties] = []
+        for item in value:
+            mapping = _node_to_mapping(item)
+            if not mapping and item is not None:
+                self._log_type_mismatch(name, value, "list of mappings")
+                return None
+            result.append(ConfigProperties(mapping))
+        return result


    sections. Sections absent from the config (``None``) leave the
    corresponding global untouched — matching the spec's "noop default"
-    behavior.
+    behavior. The global :class:`ConfigProvider` is always set, exposing the
+    ``instrumentation`` config node as a read view (empty when absent) for
+    instrumentation libraries to consume.


opentelemetry-pr-dashboard · 2026-08-14T16:58:53Z

Pull request dashboard status

Waiting on the author · refreshed 2026-08-24 14:39 UTC

Two things need attention:

Required checks are failing — investigate the failures.
4 review items — respond to each (e.g. link a commit, explain why not, ask a follow-up):
- Inline threads: 1, 2, 3
- Top-level threads: 4

Status above doesn't look right?

Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
Should this be with reviewers? Comment /dashboard route:reviewers to route it to them.
Anything wrong — including the routing? Report it with what you expected; it helps us improve the dashboard.

xrmx

This API is going to be called by instrumentations but this API sits in opentelemetry-configuration. So are instrumentations going to add a dependency on it?

xrmx · 2026-08-20T08:28:44Z

+"""Read view over declarative instrumentation configuration.
+
+Implements the spec's ``ConfigProvider`` / ``ConfigProperties`` API
+(``configuration/api.md``): a stateless, typed read view over the parsed


Should this be a full url instead?

lzchen · 2026-08-21T15:58:46Z

+    """
+    if node is None:
+        return {}
+    if is_dataclass(node) and not isinstance(node, type):


I think we lose the distinction between the key being absent and then key being None. Would this be an issue?

opentelemetry-pr-dashboard · 2026-08-21T17:22:55Z

Hi @ocelotl — just a friendly reminder that this pull request is waiting on you. The dashboard status comment has the open items and is kept current.

Replying is enough to hand it off — answer, explain why no change is needed, or ask a follow-up. The dashboard routes it onward once nothing on the list is waiting on you.
To hand it back for any other reason, including the dashboard getting this wrong, comment /dashboard route:reviewers.

Adds the Instrumentation Configuration API from the declarative configuration spec (configuration/api.md), which was previously unimplemented in Python: - ConfigProperties: a typed, schemaless read view over a parsed configuration mapping node, with get_string/get_bool/get_int/ get_float, get_config, get_config_list, get_scalar_list, and key introspection. Getters return None on a missing key or type mismatch, matching the spec and Java's DeclarativeConfigProperties semantics. - ConfigProvider: holds the ConfigProperties for the instrumentation config node and exposes get_instrumentation_config(). - A global default ConfigProvider with get_config_provider() / set_config_provider(), so instrumentation libraries can access it. - configure_sdk now builds a ConfigProvider from the .instrumentation node and sets it as the global. Fixes open-telemetry#5485.

Make the global ConfigProvider consistent with the other OpenTelemetry globals (tracer/meter/logger): - set_config_provider is now set-once, guarded by a thread-safe Once. A second call logs a warning and keeps the existing provider instead of overwriting it (the previous version warned but overwrote, and was not thread-safe). - get_config_provider returns a NoOpConfigProvider (empty instrumentation config) when none is set, rather than None, so callers can traverse the config tree without None checks — mirroring ProxyTracerProvider and Java's ConfigProvider.noop(). Its return type is now non-optional.

…list getters Address further consistency gaps with existing opentelemetry-python APIs: - get_config_provider now returns a forwarding ProxyConfigProvider (reads the global lazily) instead of a frozen no-op, so a provider obtained before set_config_provider still resolves to the one installed later — matching ProxyTracerProvider / ProxyLoggerProvider. NoOpConfigProvider is kept as an explicit no-op (mirroring NoOpTracerProvider). - ConfigProperties getters now log a warning when a key is present with an incompatible type, instead of silently returning None (matching the package's own logging habits and Java's DeclarativeConfigProperties). - Replaced get_scalar_list(name, type) with typed getters get_string_list, get_bool_list, get_int_list, get_float_list, consistent with the scalar getters and avoiding a runtime type argument. - keys() now returns a set (matching the spec's "set of property keys").

…f import order - Rename changelog fragment 5485.added -> 5486.added to match the PR number (the changelog check requires <PR_NUMBER>.<type>). - Make ConfigProperties._log_type_mismatch a staticmethod (it does not use self) to satisfy pylint R6301 (no-self-use). - Disable protected-access in the test setUp that resets the module globals (pylint W0212). - Sort imports in the test module (ruff I001).

ocelotl marked this pull request as ready for review July 30, 2026 00:59

ocelotl requested a review from a team as a code owner July 30, 2026 00:59

otelbot-python Bot added this to Python PR digest Jul 30, 2026

herin049 reviewed Jul 31, 2026

View reviewed changes

pmcollins requested a review from Copilot July 31, 2026 19:33

Copilot started reviewing on behalf of pmcollins July 31, 2026 19:33 View session

Copilot AI reviewed Jul 31, 2026

View reviewed changes

aabmass moved this to Ready for review in Python PR digest Aug 6, 2026

opentelemetry-pr-dashboard Bot mentioned this pull request Aug 14, 2026

Pull Request Dashboard #5550

Open

xrmx mentioned this pull request Aug 20, 2026

opentelemetry-instrumentation: add config_dataclass opt-in to BaseInstrumentor open-telemetry/opentelemetry-python-contrib#4766

Open

3 tasks

xrmx reviewed Aug 20, 2026

View reviewed changes

lzchen reviewed Aug 21, 2026

View reviewed changes

ocelotl added 4 commits August 24, 2026 08:48

ocelotl force-pushed the issue_5485_configprovider branch from 3d26221 to 00c93f6 Compare August 24, 2026 13:48

Navigation Menu

Uh oh!

Implement declarative config ConfigProvider / ConfigProperties API - #5486

Implement declarative config ConfigProvider / ConfigProperties API#5486
ocelotl wants to merge 4 commits into
open-telemetry:mainfrom
ocelotl:issue_5485_configprovider

ocelotl commented Jul 29, 2026 •

edited

Loading

Uh oh!

ocelotl commented Jul 29, 2026

Uh oh!

ocelotl commented Jul 30, 2026

Uh oh!

herin049 Jul 31, 2026

Uh oh!

ocelotl Aug 6, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

opentelemetry-pr-dashboard Bot commented Aug 14, 2026 •

edited

Loading

Uh oh!

xrmx left a comment

Uh oh!

xrmx Aug 20, 2026 •

edited

Loading

Uh oh!

lzchen Aug 21, 2026

Uh oh!

opentelemetry-pr-dashboard Bot commented Aug 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

		_logger.warning("Overriding of current ConfigProvider is not allowed")


		def get_config_provider() -> ConfigProvider:

Uh oh!

Conversation

ocelotl commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Scope

Type of change

How Has This Been Tested?

Does This PR Require a Contrib Repo Change?

Checklist

Uh oh!

ocelotl commented Jul 29, 2026

Uh oh!

ocelotl commented Jul 30, 2026

Uh oh!

herin049 Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

ocelotl Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

opentelemetry-pr-dashboard Bot commented Aug 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull request dashboard status

Uh oh!

xrmx left a comment

Choose a reason for hiding this comment

Uh oh!

xrmx Aug 20, 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!

lzchen Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

opentelemetry-pr-dashboard Bot commented Aug 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

ocelotl commented Jul 29, 2026 •

edited

Loading

opentelemetry-pr-dashboard Bot commented Aug 14, 2026 •

edited

Loading

xrmx Aug 20, 2026 •

edited

Loading