open-telemetry / open-telemetry/opentelemetry-python-contrib
Add config_dataclass to BaseInstrumentor for declarative configuration schema support
@ocelotl is already working on this.
Since Jul 6, 2026.
- Dominant language
- Python
- Stars
- 1.1k
- Forks
- 1.1k
- Avg merge
- 4d 15h
- Merged PRs (30d)
- 16
Description
Background
open-telemetry/opentelemetry-python#5372 adds support for activating instrumentors from a declarative configuration file (OTEL_EXPERIMENTAL_CONFIG_FILE) via the instrumentation/development.python section. When the SDK reads this section it calls instrument(**options) on each listed instrumentor with the raw options from YAML.
Problem
The SDK has no way to know which options each instrumentor accepts or what types they expect. Options are passed through as raw YAML values (strings, lists, dicts) with no validation or type coercion, making it easy to silently misconfigure an instrumentor.
Proposed solution
Add an opt-in config_dataclass class attribute to BaseInstrumentor. When set to a dataclass type, the SDK declarative config pipeline runs the raw YAML options through _dict_to_dataclass — the same type-coercion pipeline already used for SDK component configuration (tracer providers, exporters, etc.) — before forwarding them to instrument().
@dataclass
class URLLib3InstrumentorConfig:
excluded_urls: str | None = None
captured_request_headers: list[str] | None = None
captured_response_headers: list[str] | None = None
sensitive_headers: list[str] | None = None
class URLLib3Instrumentor(BaseInstrumentor):
config_dataclass = URLLib3InstrumentorConfig
...
The default value of config_dataclass is None, so all existing instrumentors are unaffected.
Scope of this issue
- Add
config_dataclass: type | None = NonetoBaseInstrumentorinopentelemetry-instrumentation - Add
config_dataclassimplementations to instrumentation packages, starting withopentelemetry-instrumentation-urllib3as the reference implementation
The SDK side (loading and applying config_dataclass) is handled in open-telemetry/opentelemetry-python#5372.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.