What Reached Stable Status

Several components of the OpenTelemetry declarative configuration specification have been marked stable [1]. The list includes the JSON schema for the data model, released as version 1.0.0 of the opentelemetry-configuration repository; the YAML file format for representing the data model; and the in-memory representation of that data model. Also reaching stable status are the ConfigProperties type, which provides a generic representation of a YAML mapping node; the PluginComponentProvider mechanism for referencing custom plugin components; the Parse and Create SDK operations; and the OTEL_CONFIG_FILE environment variable, which signals that declarative configuration should be used and points to the path of a configuration file [1].

The Data Model and Schema

The declarative configuration system is built around three layered representations of the same underlying data model [1]. The JSON schema, maintained in the opentelemetry-configuration repository and now at a stable 1.0.0 release, defines the structure of valid configuration. The YAML file format provides a human-readable, file-based serialization of that schema. The in-memory configuration model is the runtime representation that SDK implementations construct after reading and parsing a YAML file. Together, these three layers form a consistent pipeline from configuration file to instantiated SDK components.

SDK Operations and Plugin Support

Two SDK operations anchor the runtime behavior of declarative configuration [1]. The Parse operation reads a YAML configuration file and produces an in-memory configuration model. The Create operation takes that in-memory model and instantiates the appropriate SDK components. ConfigProperties supports this pipeline by providing a standardized representation of a YAML mapping node, which allows configuration data to be passed through the system in a consistent format. The PluginComponentProvider mechanism extends this further by allowing custom plugin components to be referenced within the data model, enabling teams to incorporate non-standard exporters, samplers, or other SDK extensions without modifying core specification code [1].

Declarative vs. Programmatic Configuration

Declarative configuration uses a YAML file to describe the desired SDK state — the exporters, processors, propagators, and other components that make up an SDK — which the SDK then instantiates from that file [1]. This supplements configuring those components programmatically in code. The OTEL_CONFIG_FILE environment variable allows operators to point the SDK to a configuration file at runtime, decoupling configuration from application code. This separation means the same configuration file can, in principle, be applied across different language SDKs that implement the specification.

Adoption and Language SDK Support

Several language SDKs have implemented the declarative configuration specification [1]. The languages with implementations include C++, Go, Java, JavaScript, and PHP. The specification’s stability milestone is intended to encourage broader and more consistent adoption across the OpenTelemetry ecosystem, with the stable JSON schema and YAML format providing a common target for implementors.

What This Means for Operators

For teams running OpenTelemetry in production, the stable status of the declarative configuration specification introduces a supported, file-based path for managing SDK configuration [1]. The OTEL_CONFIG_FILE environment variable provides a standardized way to inject configuration at deployment time, which aligns with common infrastructure-as-code and container-based deployment patterns. The PluginComponentProvider mechanism means that custom instrumentation components can be incorporated without requiring code changes to the core SDK setup. The 1.0.0 release of the opentelemetry-configuration JSON schema also gives tooling authors a stable target for building validators, editors, and configuration generators.

FAQ

Q. Which language SDKs currently implement declarative configuration? As of the stable release announcement, implementations exist for C++, Go, Java, JavaScript, and PHP [1].

Q. What does the OTEL_CONFIG_FILE environment variable do? It signals to the SDK that declarative configuration should be used and provides the file system path to the YAML configuration file [1].

Q. Can custom exporters or samplers be used with declarative configuration? Yes. The PluginComponentProvider mechanism allows custom plugin components to be referenced within the data model, supporting non-standard SDK extensions [1].

Q. Does declarative configuration replace programmatic configuration entirely? The sources describe declarative configuration as an alternative to code-based SDK setup, but do not state that programmatic configuration is deprecated or removed [1].

Q. Is the JSON schema versioned and stable for tooling use? The opentelemetry-configuration repository released a stable 1.0.0 version of the JSON schema as part of this announcement, providing a fixed target for validators and other tooling [1].

Key takeaways

  • The opentelemetry-configuration JSON schema reached a stable 1.0.0 release, alongside stable status for the YAML file format, in-memory model, ConfigProperties, PluginComponentProvider, Parse, Create, and OTEL_CONFIG_FILE [1].
  • The Parse and Create SDK operations define a standard pipeline from YAML file to instantiated SDK components [1].
  • PluginComponentProvider enables custom plugin components to be referenced in configuration without modifying core SDK code [1].
  • Language SDKs with implementations include C++, Go, Java, JavaScript, and PHP [1].
  • The OTEL_CONFIG_FILE environment variable gives operators a standardized, runtime mechanism for pointing SDKs to a configuration file [1].