Declarative configuration is stable!

By Jack Berg(Grafana Labs) |

What happened?

Key portions of the declarative configuration specification have been marked stable, including

  • The JSON schema for the data model, as defined in opentelemetry-configuration which released a stable 1.0.0 release
  • The YAML representation of the data model in files (spec link)
  • The in-memory representation of the data model (spec link)
  • The generic representation of a YAML mapping node, ConfigProperties (spec link)
  • The mechanism for referencing custom plugin components in the data model, PluginComponentProvider (spec link)
  • The SDK operations for parsing a YAML file and instantiating SDK components, Parse and Create (spec link)
  • The standard env var to indicate that declarative config should be used and to point to the path of a config file OTEL_CONFIG_FILE (spec link)

What’s the status of language implementations?

As of now, there are implementations available in five languages:

  • C++
  • Go
  • Java
  • JS
  • PHP

Development is underway for .NET and Python.

Additionally, the go implementation is leveraged in the Collector for configuring internal telemetry.

Going forward, implementation status can be tracked with the following resources:

What does this mean for you?

As language implementations progress, the ability to configure OpenTelemetry consistently in various languages will improve. In addition, the new configuration model provides a much richer language to specify options that go beyond the environment variables supported today. These were two of the goals of the configuration working group from the very beginning.

Language implementations stabilize on different timelines than the specification, but that should be coming soon. If a language you’re using doesn’t have an implementation yet, or is lacking a feature you’d like to implement or see implemented, let us know by opening an issue in opentelemetry-configuration! We’d love to hear from you.

See the docs in your relevant language for details on how to use. If the docs don’t exist yet, please open an issue in opentelemetry.io to request them!

Even without a particular language implementation declared stable, it’s possible the user-facing portions will be stable sooner. Stabilizing the schema is the most important thing for a stable user experience.

What’s next?

The work doesn’t end here, but the focus does shift:

  • Continue to model new concepts in the schema and stabilize existing types as corresponding specification concepts stabilize.
  • Adjust the specification proposal process to be “declarative configuration first”. What this means is when a feature is proposed for SDKs, the corresponding declarative config types and properties should be proposed alongside it. The declarative config schema is a key part of the SDK UX, and should be considered early in the design process.
  • Deprecate environment variables which don’t interoperate well. Deprecation doesn’t mean deletion, but we want to signal that declared configuration is the preferred path and where we’re investing. (tracking issue)
  • Even more languages need to implement declarative configuration! With the specification and data model stable, there’s no reason not to.
  • The API portion of declarative configuration for configuring instrumentation (i.e. ConfigProvider) is out of scope for this initial stabilization. We need more languages to build prototypes.
  • Dynamic configuration story, or how do I change my telemetry at runtime? (telemetry policy OTEP)

Thanks

A big thank you to all the amazing contributors who made this possible through years of collaboration. Special shout out to those who have been around since the beginning - not sure we would have started had we known up front it was going to take this long and this much effort 😅! Besides those listed below, I know I’ve missed others, including those involved in implementing, reviewing, and contributing in other ways.

Last modified March 5, 2026: Blog post announcing stable declarative configuration (#9289) (4aea08df)