Skip to content

Support declarative configuration via OTEL_CONFIG_FILE - #9

Draft
mmanciop wants to merge 1 commit into
mainfrom
declarative-config-support
Draft

Support declarative configuration via OTEL_CONFIG_FILE#9
mmanciop wants to merge 1 commit into
mainfrom
declarative-config-support

Conversation

@mmanciop

@mmanciop mmanciop commented Jul 21, 2026

Copy link
Copy Markdown
Member

What

Makes the distribution work with OpenTelemetry declarative (file-based) configuration:

  • declarative-config extra: pip install dash0-opentelemetry-distro[declarative-config] installs the loader dependencies (opentelemetry-sdk[file-configuration], i.e. pyyaml + jsonschema). It stays an extra rather than a hard dependency because jsonschema drags in rpds-py (native wheels), which would break the distro's "no native dependencies, safe to inject" design goal.

  • Preflight in Dash0Configurator: when OTEL_CONFIG_FILE is set but the loader can't be imported, log one actionable error and skip SDK configuration:

    OTEL_CONFIG_FILE is set but the declarative-configuration dependencies are not installed:
    File configuration requires pyyaml. Install with: pip install opentelemetry-sdk[file-configuration].
    The SDK will not be configured and no telemetry will be sent.
    

    Previously this failed with a raw ModuleNotFoundError traceback at startup, and the process silently ran without any telemetry.

The preflight checks only where the pinned SDK (1.43.0, from #8) keeps the loader; its docstring and the extra's comment flag that the 1.44 bump moves the loader to the separate opentelemetry-configuration package, so the future version-bump change knows to revisit both.

Validation

Verified end-to-end with opentelemetry-instrument against a local OTLP sink:

  • With the extra: the SDK is built from the declarative YAML — spans (including the distro's DASH0_BOOTSTRAP_SPAN) export to the endpoint from the file, with the file's resource attributes; the vendored pyproto OTLP/HTTP exporter is picked up by the declarative otlp_http factory.
  • Without the extra: the single error message above replaces the traceback and the application keeps running.
  • New unit tests cover the skip-with-error path, normal delegation, that the import probe doesn't run without OTEL_CONFIG_FILE, and the preflight's message shape. Full suite: 32 passed via the CI command; ruff clean; uv.lock regenerated.

Known remaining gap (out of scope, tracked in #6): the distro's detected resource attributes are dropped under declarative configuration.

Fixes #5

🤖 Generated with Claude Code

@mmanciop
mmanciop force-pushed the declarative-config-support branch from 9d3a83a to c6481ea Compare July 21, 2026 15:00
The pinned SDK bundles the OTEL_CONFIG_FILE loader behind the
opentelemetry-sdk[file-configuration] extra (pyyaml, jsonschema), which
a plain install of the distribution does not pull in. Setting
OTEL_CONFIG_FILE then failed with a raw traceback at startup and the
process ran without any telemetry.

Add a declarative-config extra so the loader's dependencies install
with the distribution, and a preflight in Dash0Configurator that, when
OTEL_CONFIG_FILE is set but the loader cannot be imported, logs one
actionable error naming the package to install instead of half-failing
into silence.

Validated end-to-end: with the extra installed, the SDK is built from
the declarative YAML (exporter endpoint and resource from the file) and
the distro's bootstrap span exports through the file-configured
pipeline; without it, the single error message replaces the traceback
and the application keeps running.

Fixes #5

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mmanciop
mmanciop force-pushed the declarative-config-support branch from c6481ea to 6457acb Compare July 21, 2026 16:51
@mmanciop
mmanciop changed the base branch from tighten-dependency-pins to main July 21, 2026 16:51
@mmanciop
mmanciop marked this pull request as draft July 21, 2026 16:54
@mmanciop

Copy link
Copy Markdown
Member Author

Putting this on the backburner because we do not use declarative config in the Dash0 Operator right now, and it would bring the pyyaml and jsonschema dependencies, with the associated injection risks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Declarative configuration (OTEL_CONFIG_FILE) fails out of the box: declarative-config dependencies are not installed

1 participant