OpenTelemetry Declarative Configuration Reaches Stability Milestone

The OpenTelemetry project has announced that key portions of its declarative configuration specification have reached stable status, marking a significant milestone for the observability framework. The announcement, documented by Jack Berg, a principal engineer at Grafana Labs, represents a major step forward in making telemetry collection more accessible and consistent across different programming languages and environments.

The stabilisation includes the JSON schema for the data model, the YAML representation of configuration files, and the in-memory representation of configuration data. According to Berg, "Declarative config schema is on track to become a crucial cross-language user-facing API for the whole project."

Language Support and Implementation Status

Language implementations are now available in five languages: C++, Go, Java, JavaScript, and PHP. Development work continues for .NET and Python implementations. Berg emphasised that the specification itself reaching stability is the most important step for ensuring a consistent user experience across all implementations.

During a recent Grafana OpenTelemetry community call, Marylia Gutierrez, an OpenTelemetry JavaScript approver and core contributor at Grafana Labs, provided additional perspective on the current state of language support. According to the compliance matrix shared during the call, Java and PHP are fully compliant with the basic requirements. JavaScript is under active development with more features being added, while Go has some capabilities available but documentation is being updated to show how to use them. Python support remains in development.

The Problem Declarative Configuration Solves

Before declarative configuration was added, users had to rely on environment variables to configure their telemetry settings. However, as Gutierrez explained during the community call, those environment variables could not handle complex configuration needs. The new YAML-based approach provides a more robust structure that lets users define a hierarchical configuration with all settings in one place.

Getting all three observability signals configured in a single place has historically been a juggling act of environment variables, programmatic SDK initialisation code, and collector configs. The OpenTelemetry declarative configuration format changes this by letting users define trace, metric, and log pipelines in a single YAML file that the SDK reads at startup.

Practical Benefits and Use Cases

One of the biggest benefits of declarative configuration is the ability to define telemetry settings in configuration files rather than environment variables. Berg pointed out that this method gives a much richer language for specifying options. The new system allows users to define complex telemetry pipelines in a declarative format that can be version-controlled and shared across teams.

A practical example shows how users can configure resource attributes, trace providers, metric readers and log processors in a single file format, then point their SDK to the file using the OTEL_CONFIG_FILE environment variable. This approach enables teams to manage telemetry configuration alongside their application code, making it easier to track changes and maintain consistency across different environments.

During the community call, Gutierrez demonstrated how declarative configuration simplifies setup across languages. The demonstration showed how users can configure a custom sampler and specify which spans to drop based on attribute patterns. She noted that achieving this with environment variables would also require custom code and separate libraries, making the declarative approach significantly more straightforward.

Remote and Dynamic Configuration

The community call also addressed the current language support and future capabilities. Gutierrez described remote and dynamic configuration as a future capability where operations teams could push configuration changes to adjust sampling rates or enable additional instrumentation without requiring code changes or redeployment.

The vision is that a change to a YAML file could be pushed and picked up by applications without a restart. This capability would enable operations teams to fine-tune telemetry collection in production environments without the risk and complexity of deploying new code.

Industry Adoption and Impact

OpenTelemetry has been gaining significant traction in the industry. Recently, Airbnb announced their migration of a high-volume metrics pipeline to OpenTelemetry, demonstrating the framework's capability to handle large-scale production workloads. The project has also published articles aimed at broadening adoption and demystifying the technology for new users.

OneUptime has published a detailed guide to using declarative configuration, covering the structure of configuration files, including resource attributes, tracer providers, metric readers and logger providers. This type of documentation is crucial for helping teams adopt the new configuration approach and understand its full capabilities.

Future Roadmap and Development

The OpenTelemetry project has indicated that it will keep expanding declarative configuration support. Dynamic configuration, which would allow runtime changes to telemetry settings, is still on the roadmap. This capability would further enhance the flexibility and operational efficiency of telemetry collection.

Berg summarised the importance of this milestone by stating, "Stabilising the schema is the most important thing for a stable user experience." This stability provides a foundation for developers and operations teams to build upon, knowing that the configuration format will remain consistent across different language implementations and future versions.

Conclusion

The stabilisation of OpenTelemetry's declarative configuration represents a significant milestone for the observability ecosystem. By providing a consistent, language-agnostic way to configure telemetry collection, OpenTelemetry is making it easier for teams to implement comprehensive observability practices across their applications.

The combination of YAML-based configuration files, cross-language consistency, and the ability to version-control telemetry settings makes declarative configuration a powerful tool for modern software development and operations teams. As more language implementations reach full compliance and dynamic configuration capabilities are added, OpenTelemetry's declarative configuration is likely to become an increasingly important part of the observability landscape.

For teams looking to implement OpenTelemetry, the stable declarative configuration specification provides a solid foundation to build upon, with comprehensive documentation and growing community support to help with adoption and implementation.