open-telemetry / open-telemetry/opentelemetry-python-contrib

Add config_dataclass to BaseInstrumentor for declarative configuration schema support

Open
#4,765 1 comment 0 reactions 1 assignee View on GitHub

@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

  1. Add config_dataclass: type | None = None to BaseInstrumentor in opentelemetry-instrumentation
  2. Add config_dataclass implementations to instrumentation packages, starting with opentelemetry-instrumentation-urllib3 as the reference implementation

The SDK side (loading and applying config_dataclass) is handled in open-telemetry/opentelemetry-python#5372.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.