Declarative (file-based) Configuration [META] #7658

Overview

This is the tracking issue for the OpenTelemetry.Configuration.Declarative package, which adds file-based declarative configuration (YAML) support for the OpenTelemetry .NET SDK, following the OpenTelemetry Configuration specification.

The package parses a declarative YAML file into a typed internal model, which is the source of truth for the SDK. When a document is registered, OTEL_* settings come only from that document, as the spec requires: earlier IConfiguration sources and environment variables do not layer over it, and flat projection into IConfiguration remains only as a compatibility transport to the SDK's existing read sites. .NET-style layering is provided instead through an explicit model overlay. The package also exposes a spec-compliant API surface for component construction and a plugin provider abstraction for building and selecting SDK components from configuration.

Task breakdown

Phases group related units of work into manageable implementation units and PRs. The numbering is a stable label and does not suggest an implementation sequence. Incomplete dependencies are shown in short form against each entry.

• Phase 1: Typed model and three-state scalars ([Config] Declarative config (phase 1) initial design and scalar values #7413)
• Phase 2: Neutral value model and ConfigProperties ([Config] Declarative config phase 2: Add ConfigProperties typed property bag #7657)
• Phase 3: Document-rooted ConfigProperties and unknown-key retention ([Declarative config] Phase 3: Parse the full configuration document #7716)
• Phase 4: Parsed-document retention across DI ([Declarative config] Phase 4: Document retention #7690)
• Phase 5: Public document access ([Declarative config] Phase 5: Public document access #7781)
• Phase 6: Remove the public source-only API ([Declarative config] Phase 6: Remove source-only configuration API #7980)
• Phase 7: Resource attribute fidelity ([Declarative config] Phase 7: Resource attribute fidelity #7806)
• Phase 8: Strict exclusivity mode (8a [Declarative config] Phase 8a: Default to strict mode when a declarative config file is in use #7849 | 8b [Declarative config] Phase 8b: Add strict mode warnings #7873)
• Phase 9: Component provider abstraction ([Declarative config] Phase 9: Component provider abstraction and registry #7710)
• Phase 10: Sampler model and parser withdrawn
• Phase 11: Built-in sampler providers from the document (11a sampler | 11b resource alignment)
• Phase 12: Phase 12: Minimal tracer provider from the document ([Declarative config] Phase 12: Build a minimal tracer provider from the document #8080)
• Phase 13: Logger provider pipeline (requires Phase 26)
• Phase 14: Schema artifact and model generation (requires Phases 13, 23 and 24)
• Phase 15: Public Parse and Create (requires Phase 14)
• Phase 16: Host application builder API (optional)
• Phase 17: Schema-derived key recognition and applied-property reporting (17a [Declarative config] Phase 17a: Schema key recognition and validation #7904 | 17b [Declarative config] Phase 17b: Report defined by not applied settings #8009)
• Phase 18: Schema structural validation (requires Phase 17) deferred
• Phase 19: Phase 19: Model overlay (with or before Phase 15)
• Phase 20: Zero-code activation
• Phase 21: .NET document section (21a: self-diagnostics outputs)
• Phase 22: Schema update workflow (after first alpha)
• Phase 23: Meter provider pipeline (requires Phase 26)
• Phase 24: Propagators, attribute limits and log level (24a [Declarative Config] Phase 24a: Apply self-diagnostics log level #8101 | 24b propagators | 24c attribute limits; requires 24c also Initial POC for centralising span limits #8021 and [feature request] Add public options types for attribute, span and log record limits #7827)
• Phase 25: Pre-alpha clean-up: renumber diagnostic events, public surface and README review (requires every phase on the alpha bar)
• Phase 26: Tracer provider OTLP exporters and span limits (span limits require Initial POC for centralising span limits #8021 and [feature request] Add public options types for attribute, span and log record limits #7827)
• Phase 27: Tracer and meter configurators in core (core work)

Future tasks

These are intentionally not assigned to committed phases yet:

• ConfigProvider and instrumentation config API. The spec's ConfigProvider type (Development status) follows spec stabilisation. Its destination package (declarative, core, or API) is an open question.

Supersedes #6380