The OpenTelemetry declarative configuration specification has reached a major milestone: stable 1.0. After years of development spanning multiple working groups and extensive community feedback, the JSON schema, YAML representation, and SDK operations are now finalized, enabling consistent telemetry configuration across languages and implementations. This stability means teams can invest in declarative configuration with confidence that the foundation will not change.
What is Now Stable
The 1.0 release stabilizes the core configuration infrastructure that underpins how OpenTelemetry SDKs are initialized and configured. This includes:
- JSON schema for the data model in opentelemetry-configuration, providing validation and IDE autocomplete
- YAML file format representation and parsing, the human-friendly configuration interface
- In-memory configuration model for runtime SDK use and programmatic access
- PluginComponentProvider mechanism for custom extensions and vendor-specific plugins
- Parse and Create SDK operations for instantiating components from configuration
- OTEL_CONFIG_FILE environment variable for config path specification
Language Implementation Status
Five languages currently have working implementations, with more on the way:
- C++ for high-performance native applications
- Go (also powers Collector internal telemetry configuration)
- Java for enterprise JVM applications
- JavaScript for Node.js and browser environments
- PHP for web application instrumentation
Active development is underway for .NET and Python, with community contributions welcome. The specification compliance matrix tracks feature parity across languages, helping teams understand which capabilities are available in their chosen runtime.
Beyond Environment Variables
The declarative model addresses fundamental limitations of the current environment variable approach. Complex configurations—think multi-layer sampling rules, conditional processors, or custom attribute mappings—become readable YAML instead of dense, escaping-prone environment variable strings that are hard to validate and debug.
Example use cases that particularly benefit from declarative configuration:
- Head-based sampling with custom rate limits per service and operation
- Processor chains with conditional logic and attribute filtering
- Resource attribute enrichment from multiple sources like environment, metadata services, and files
- Exporter configuration with custom retry policies, batching, and queuing
- Multi-signal pipelines (traces, metrics, logs) with shared resources
The YAML format enables comments, structure, and validation that environment variables cannot provide. Configuration files can be version-controlled, reviewed in pull requests, and tested before deployment.
What is Next
With the specification stable, focus shifts to implementation rollout and broader ecosystem adoption:
- Specification proposals will now require declarative config schema updates alongside SDK changes
- Problematic environment variables will be deprecated in favor of declarative config (but not removed)
- Dynamic configuration at runtime remains an active research area with proposals under development
- The ConfigProvider API for instrumentation configuration is still being prototyped across languages
The declarative-first policy ensures new features are designed with configuration in mind from the start, rather than retrofitting support later.
Migration Path
Teams can adopt declarative configuration incrementally without breaking existing setups. The stable schema is backward-compatible where possible, and existing environment variables continue to function. New projects should consider declarative config as the primary approach from day one.
Documentation and examples are available for all supported languages, with SDK-specific guides showing how to load and apply declarative configurations. Many vendors are adding declarative config support to their distributions.