refactor(config): rename 'known/unknown' to 'built-in/user-defined' terminology (#5214)

* 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

* rename changelog fragment to PR #5214

* use 'user-defined' instead of 'plugin' per review feedback

Rename 'plugin' to 'user-defined' throughout — pairs better with
'built-in' and is less ambiguous.

Assisted-by: Claude Opus 4.6

Author: MikeGoldsmith

.changelog/5214.changed

@@ -0,0 +1 @@
+`opentelemetry-sdk`: rename "known/unknown" to "built-in/user-defined" terminology in declarative config component loading code

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 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.

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 user-defined kwargs)
    - additional_properties: ClassVar[dict[str, Any]] annotation (for type checkers)
 
    The template checks two context variables set by datamodel-codegen:

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 user-defined
     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

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

@@ -188,8 +188,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. User-defined sampler names captured in additional_properties
     by the @_additional_properties decorator are loaded via the
     ``opentelemetry_sampler`` entry point group.
     """
@@ -206,7 +206,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."
     )
 

opentelemetry-sdk/tests/_configuration/test_tracer_provider.py

@@ -207,11 +207,11 @@ 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())
 
-    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_unknown_plugin_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=[],