From ddbdd12b2eb63474534f97bbad3b45de5d0ed42d Mon Sep 17 00:00:00 2001 From: Mike Goldsmith Date: Fri, 15 May 2026 12:06:01 +0100 Subject: [PATCH 1/3] 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/3] 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 From 61cc7782d006ca6de0117c23164b53536306494a Mon Sep 17 00:00:00 2001 From: Mike Goldsmith Date: Wed, 27 May 2026 12:37:59 +0100 Subject: [PATCH 3/3] use 'user-defined' instead of 'plugin' per review feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rename 'plugin' to 'user-defined' throughout — pairs better with 'built-in' and is less ambiguous. Assisted-by: Claude Opus 4.6 --- .changelog/5214.changed | 2 +- opentelemetry-sdk/codegen/README.md | 2 +- opentelemetry-sdk/codegen/dataclass.jinja2 | 2 +- .../src/opentelemetry/sdk/_configuration/_common.py | 2 +- .../src/opentelemetry/sdk/_configuration/_tracer_provider.py | 2 +- .../tests/_configuration/test_tracer_provider.py | 4 ++-- 6 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.changelog/5214.changed b/.changelog/5214.changed index 2eb2c739bec..f8926edd6b8 100644 --- a/.changelog/5214.changed +++ b/.changelog/5214.changed @@ -1 +1 @@ -`opentelemetry-sdk`: rename "known/unknown" to "built-in/plugin" terminology in declarative config plugin loading code +`opentelemetry-sdk`: rename "known/unknown" to "built-in/user-defined" terminology in declarative config component loading code diff --git a/opentelemetry-sdk/codegen/README.md b/opentelemetry-sdk/codegen/README.md index 293c9207a87..b79210a576e 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 plugin/custom constructor kwargs +- `@_additional_properties` decorator — captures user-defined 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 91f2069d819..17b8aecdb50 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 plugin/custom kwargs) + - @_additional_properties decorator (captures user-defined 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 0fac88abc53..02d17138019 100644 --- a/opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_common.py +++ b/opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_common.py @@ -18,7 +18,7 @@ def _additional_properties(cls): 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 + attribute instead of raising ``TypeError``. This lets user-defined component names flow through the config pipeline without modifying the codegen output for built-in fields. diff --git a/opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_tracer_provider.py b/opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_tracer_provider.py index 20e0ff64ac3..b609d16be8a 100644 --- a/opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_tracer_provider.py +++ b/opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_tracer_provider.py @@ -189,7 +189,7 @@ def _create_sampler(config: SamplerConfig) -> Sampler: """Create a sampler from config. Built-in sampler types are checked via typed fields on the Sampler - dataclass. Plugin sampler names captured in additional_properties + dataclass. User-defined sampler names captured in additional_properties by the @_additional_properties decorator are loaded via the ``opentelemetry_sampler`` entry point group. """ diff --git a/opentelemetry-sdk/tests/_configuration/test_tracer_provider.py b/opentelemetry-sdk/tests/_configuration/test_tracer_provider.py index 0e960b6fbd4..2c73ee3649f 100644 --- a/opentelemetry-sdk/tests/_configuration/test_tracer_provider.py +++ b/opentelemetry-sdk/tests/_configuration/test_tracer_provider.py @@ -211,7 +211,7 @@ def test_no_sampler_raises_configuration_error(self): with self.assertRaises(ConfigurationError): self._make_provider(SamplerConfig()) - def test_plugin_sampler_loaded_via_entry_point(self): + def test_user_defined_sampler_loaded_via_entry_point(self): mock_sampler = MagicMock(spec=Sampler) mock_class = MagicMock(return_value=mock_sampler) with patch( @@ -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_plugin_sampler_not_found_raises_configuration_error(self): + def test_user_defined_sampler_not_found_raises_configuration_error(self): with patch( "opentelemetry.sdk._configuration._common.entry_points", return_value=[],