From ddbdd12b2eb63474534f97bbad3b45de5d0ed42d Mon Sep 17 00:00:00 2001 From: Mike Goldsmith Date: Fri, 15 May 2026 12:06:01 +0100 Subject: [PATCH 1/2] rename 'known/unknown' to 'built-in/plugin' in declarative config Update docstrings, comments, and test names to use clearer terminology for components that are built into the SDK vs loaded via entry points as plugins. Covers the already-merged sampler PR and shared infrastructure. The pending propagator, exporter, and resource detector PRs will need the same rename applied when they merge. Assisted-by: Claude Opus 4.6 --- .changelog/5195.changed | 1 + opentelemetry-sdk/codegen/README.md | 2 +- opentelemetry-sdk/codegen/dataclass.jinja2 | 2 +- .../src/opentelemetry/sdk/_configuration/_common.py | 6 +++--- .../opentelemetry/sdk/_configuration/_tracer_provider.py | 6 +++--- .../tests/_configuration/test_tracer_provider.py | 4 ++-- 6 files changed, 11 insertions(+), 10 deletions(-) create mode 100644 .changelog/5195.changed diff --git a/.changelog/5195.changed b/.changelog/5195.changed new file mode 100644 index 00000000000..2eb2c739bec --- /dev/null +++ b/.changelog/5195.changed @@ -0,0 +1 @@ +`opentelemetry-sdk`: rename "known/unknown" to "built-in/plugin" terminology in declarative config plugin loading code diff --git a/opentelemetry-sdk/codegen/README.md b/opentelemetry-sdk/codegen/README.md index d28e52b4cf5..293c9207a87 100644 --- a/opentelemetry-sdk/codegen/README.md +++ b/opentelemetry-sdk/codegen/README.md @@ -6,7 +6,7 @@ Custom [datamodel-code-generator](https://github.com/koxudaxi/datamodel-code-gen Extends the default dataclass template to support `additionalProperties` from the JSON Schema. Schema types that allow additional properties (e.g. `Sampler`, `SpanExporter`, `TextMapPropagator`) get: -- `@_additional_properties` decorator — captures unknown constructor kwargs +- `@_additional_properties` decorator — captures plugin/custom constructor kwargs - `additional_properties: ClassVar[dict[str, Any]]` annotation — satisfies type checkers without creating a dataclass field This enables plugin/custom component names to flow through typed dataclasses without a post-processing step. diff --git a/opentelemetry-sdk/codegen/dataclass.jinja2 b/opentelemetry-sdk/codegen/dataclass.jinja2 index f584357c8cb..91f2069d819 100644 --- a/opentelemetry-sdk/codegen/dataclass.jinja2 +++ b/opentelemetry-sdk/codegen/dataclass.jinja2 @@ -2,7 +2,7 @@ Extends the default datamodel-codegen dataclass template to support JSON Schema additionalProperties. When a schema type allows additional properties (e.g. Sampler, SpanExporter), this template adds: - - @_additional_properties decorator (captures unknown kwargs) + - @_additional_properties decorator (captures plugin/custom kwargs) - additional_properties: ClassVar[dict[str, Any]] annotation (for type checkers) The template checks two context variables set by datamodel-codegen: diff --git a/opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_common.py b/opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_common.py index f70358b1510..8b9c6abce3c 100644 --- a/opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_common.py +++ b/opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_common.py @@ -16,11 +16,11 @@ def _additional_properties(cls): """Decorator for dataclasses whose JSON Schema sets additionalProperties. - Wraps the dataclass-generated ``__init__`` so that unknown keyword + Wraps the dataclass-generated ``__init__`` so that extra keyword arguments are captured into an ``additional_properties`` instance - attribute instead of raising ``TypeError``. This lets plugin/custom + attribute instead of raising ``TypeError``. This lets plugin component names flow through the config pipeline without modifying - the codegen output for known fields. + the codegen output for built-in fields. Applied automatically by the custom template in ``opentelemetry-sdk/codegen/`` when ``additionalPropertiesType`` is present in the template context diff --git a/opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_tracer_provider.py b/opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_tracer_provider.py index af4200e4748..6b10d7136c2 100644 --- a/opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_tracer_provider.py +++ b/opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_tracer_provider.py @@ -177,8 +177,8 @@ def _create_span_processor( def _create_sampler(config: SamplerConfig) -> Sampler: """Create a sampler from config. - Known sampler types are checked via typed fields on the Sampler - dataclass. Unknown sampler names captured in additional_properties + Built-in sampler types are checked via typed fields on the Sampler + dataclass. Plugin sampler names captured in additional_properties by the @_additional_properties decorator are loaded via the ``opentelemetry_sampler`` entry point group. """ @@ -195,7 +195,7 @@ def _create_sampler(config: SamplerConfig) -> Sampler: name = next(iter(config.additional_properties)) return load_entry_point("opentelemetry_sampler", name)() raise ConfigurationError( - f"Unknown or unsupported sampler type in config: {config!r}. " + f"Unsupported sampler type in config: {config!r}. " "Supported types: always_on, always_off, trace_id_ratio_based, parent_based." ) diff --git a/opentelemetry-sdk/tests/_configuration/test_tracer_provider.py b/opentelemetry-sdk/tests/_configuration/test_tracer_provider.py index 80267df426f..345b7db5ee3 100644 --- a/opentelemetry-sdk/tests/_configuration/test_tracer_provider.py +++ b/opentelemetry-sdk/tests/_configuration/test_tracer_provider.py @@ -207,7 +207,7 @@ def test_parent_based_with_delegate_samplers(self): self.assertIs(sampler._local_parent_sampled, ALWAYS_ON) self.assertIs(sampler._local_parent_not_sampled, ALWAYS_OFF) - def test_unknown_sampler_raises_configuration_error(self): + def test_no_sampler_raises_configuration_error(self): with self.assertRaises(ConfigurationError): self._make_provider(SamplerConfig()) @@ -222,7 +222,7 @@ def test_plugin_sampler_loaded_via_entry_point(self): provider = self._make_provider(SamplerConfig(my_custom_sampler={})) self.assertIs(provider.sampler, mock_sampler) - def test_unknown_plugin_raises_configuration_error(self): + def test_plugin_sampler_not_found_raises_configuration_error(self): with patch( "opentelemetry.sdk._configuration._common.entry_points", return_value=[], From b03d9253f259160c4759e2b25b252eee1904dcfd Mon Sep 17 00:00:00 2001 From: Mike Goldsmith Date: Mon, 18 May 2026 15:25:01 +0100 Subject: [PATCH 2/2] rename changelog fragment to PR #5214 --- .changelog/{5195.changed => 5214.changed} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .changelog/{5195.changed => 5214.changed} (100%) diff --git a/.changelog/5195.changed b/.changelog/5214.changed similarity index 100% rename from .changelog/5195.changed rename to .changelog/5214.changed