open-telemetry · jack-berg · Feb 27, 2026 · Jun 24, 2025 · Jun 24, 2025 · Jul 10, 2025
@@ -40,6 +40,9 @@ release.
 
 ### SDK Configuration
 
+- Mark significant portions of declarative configuration as stable.
+  ([#4568](https://github.com/open-telemetry/opentelemetry-specification/pull/4568))
+
 ### Supplementary Guidelines
 
 ### OTEPs

@@ -285,7 +285,7 @@ Note: Support for environment variables is optional.
 | OTEL_METRICS_EXEMPLAR_FILTER | + | + |  |  | + |  | + |  | - | + |  |
 | OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE | + | + | + | + | + |  | + |  | - | + |  |
 | OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION | + | + |  | + | + |  |  |  | - |  |  |
-| OTEL_EXPERIMENTAL_CONFIG_FILE | - |  |  |  |  |  | + |  | - |  |  |
+| OTEL_CONFIG_FILE | - |  |  |  |  |  | + |  | - |  |  |
 
 ## Declarative configuration
 

@@ -501,7 +501,7 @@ sections:
         status: '-'
       - name: OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION
         status: '-'
-      - name: OTEL_EXPERIMENTAL_CONFIG_FILE
+      - name: OTEL_CONFIG_FILE
         status: '-'
   - name: Declarative configuration
     features:

@@ -501,7 +501,7 @@ sections:
         status: '+'
       - name: OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION
         status: '?'
-      - name: OTEL_EXPERIMENTAL_CONFIG_FILE
+      - name: OTEL_CONFIG_FILE
         status: '?'
   - name: Declarative configuration
     features:

@@ -501,7 +501,7 @@ sections:
         status: '?'
       - name: OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION
         status: '?'
-      - name: OTEL_EXPERIMENTAL_CONFIG_FILE
+      - name: OTEL_CONFIG_FILE
         status: '?'
   - name: Declarative configuration
     features:

@@ -501,7 +501,7 @@ sections:
         status: '+'
       - name: OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION
         status: '+'
-      - name: OTEL_EXPERIMENTAL_CONFIG_FILE
+      - name: OTEL_CONFIG_FILE
         status: '-'
   - name: Declarative configuration
     features:

@@ -501,7 +501,7 @@ sections:
         status: '+'
       - name: OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION
         status: '+'
-      - name: OTEL_EXPERIMENTAL_CONFIG_FILE
+      - name: OTEL_CONFIG_FILE
         status: '?'
   - name: Declarative configuration
     features:

@@ -501,7 +501,7 @@ sections:
         status: '+'
       - name: OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION
         status: '?'
-      - name: OTEL_EXPERIMENTAL_CONFIG_FILE
+      - name: OTEL_CONFIG_FILE
         status: '?'
   - name: Declarative configuration
     features:

@@ -501,7 +501,7 @@ sections:
         status: '+'
       - name: OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION
         status: '?'
-      - name: OTEL_EXPERIMENTAL_CONFIG_FILE
+      - name: OTEL_CONFIG_FILE
         status: '+'
   - name: Declarative configuration
     features:

@@ -501,7 +501,7 @@ sections:
         status: '+'
       - name: OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION
         status: '+'
-      - name: OTEL_EXPERIMENTAL_CONFIG_FILE
+      - name: OTEL_CONFIG_FILE
         status: '?'
   - name: Declarative configuration
     features:

@@ -501,7 +501,7 @@ sections:
         status: '+'
       - name: OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION
         status: '+'
-      - name: OTEL_EXPERIMENTAL_CONFIG_FILE
+      - name: OTEL_CONFIG_FILE
         status: '?'
   - name: Declarative configuration
     features:

@@ -501,7 +501,7 @@ sections:
         status: '?'
       - name: OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION
         status: '?'
-      - name: OTEL_EXPERIMENTAL_CONFIG_FILE
+      - name: OTEL_CONFIG_FILE
         status: '?'
   - name: Declarative configuration
     features:

@@ -501,7 +501,7 @@ sections:
         status: '?'
       - name: OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION
         status: '?'
-      - name: OTEL_EXPERIMENTAL_CONFIG_FILE
+      - name: OTEL_CONFIG_FILE
         status: '?'
   - name: Declarative configuration
     features:

@@ -319,7 +319,7 @@ sections:
       - name: OTEL_METRICS_EXEMPLAR_FILTER
       - name: OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE
       - name: OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION
-      - name: OTEL_EXPERIMENTAL_CONFIG_FILE
+      - name: OTEL_CONFIG_FILE
     hide_optional_column: true
   - name: Declarative configuration
     features:

@@ -5,7 +5,7 @@ weight: 1
 
 # Instrumentation Configuration API
 
-**Status**: [Development](../document-status.md)
+**Status**: [Mixed](../document-status.md)
 
 <!-- toc -->
 
@@ -35,6 +35,8 @@ It consists of the following main components:
 
 ### ConfigProvider
 
+**Status**: [Development](../document-status.md)
+
 `ConfigProvider` provides access to configuration properties relevant to
 instrumentation.
 
@@ -65,6 +67,8 @@ return an empty `ConfigProperties` (as if `.instrumentation: {}` was set).
 
 ### ConfigProperties
 
+**Status**: [Stable](../document-status.md)
+
 `ConfigProperties` is a programmatic representation of a configuration mapping
 node (i.e. a YAML mapping node).
 

@@ -5,7 +5,7 @@ weight: 2
 
 # Configuration Data Model
 
-**Status**: [Development](../document-status.md)
+**Status**: [Stable](../document-status.md)
 
 <!-- toc -->
 

@@ -316,21 +316,20 @@ that use [periodic exporting MetricReader](../metrics/sdk.md#periodic-exporting-
 
 ## Declarative configuration
 
-**Status**: [Development](../document-status.md)
-
 Environment variables involved in [declarative configuration](./README.md#declarative-configuration).
 
-| Name                          | Description                                                                                                                                                                   | Default | Type       | Notes     |
-|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|------------|-----------|
-| OTEL_EXPERIMENTAL_CONFIG_FILE | The path of the configuration file used to configure the SDK. If set, the configuration in this file takes precedence over all other SDK configuration environment variables. |         | [String][] | See below |
+| Name                            | Description                                                                                                                                                                   | Default | Type       | Notes                                           |
+|---------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|------------|-------------------------------------------------|
+| `OTEL_EXPERIMENTAL_CONFIG_FILE` | The path of the configuration file used to configure the SDK. If set, the configuration in this file takes precedence over all other SDK configuration environment variables. |         | [String][] | **Deprecated**. Use `OTEL_CONFIG_FILE` instead. |
+| `OTEL_CONFIG_FILE`              | The path of the configuration file used to configure the SDK. If set, the configuration in this file takes precedence over all other SDK configuration environment variables. |         | [String][] | See below                                       |
 
-If `OTEL_EXPERIMENTAL_CONFIG_FILE` is set, the file at the specified path is used to
+If `OTEL_CONFIG_FILE` is set, the file at the specified path is used to
 call [Parse](./sdk.md#parse). The
 resulting [configuration model](./sdk.md#in-memory-configuration-model) is
 used to call [Create](./sdk.md#create) to produce fully configured
 SDK components.
 
-When `OTEL_EXPERIMENTAL_CONFIG_FILE` is set, all other environment variables
+When `OTEL_CONFIG_FILE` is set, all other environment variables
 besides those referenced in the configuration file
 for [environment variable substitution](./data-model.md#environment-variable-substitution)
 MUST be ignored. Ignoring the environment variables is necessary because
@@ -341,11 +340,11 @@ model returned by `Parse` before `Create` is called. For example, a user may
 call `Parse` on multiple files and define logic from merging the resulting
 configuration models, or overlay values from environment variables on top of a
 configuration model. Implementations MAY provide a mechanism to customize the
-configuration model parsed from `OTEL_EXPERIMENTAL_CONFIG_FILE`.
+configuration model parsed from `OTEL_CONFIG_FILE`.
 
 Users are encouraged to
 use [`otel-sdk-migration-config.yaml`](https://github.com/open-telemetry/opentelemetry-configuration/blob/main/examples/otel-sdk-migration-config.yaml)
-as a starting point for `OTEL_EXPERIMENTAL_CONFIG_FILE`. This file represents a
+as a starting point for `OTEL_CONFIG_FILE`. This file represents a
 common SDK configuration scenario, and includes environment variable
 substitution references to environment variables which are otherwise ignored.
 Alternatively, [`otel-sdk-config.yaml`](https://github.com/open-telemetry/opentelemetry-configuration/blob/main/examples/otel-sdk-config.yaml)

@@ -5,7 +5,7 @@ weight: 3
 
 # Configuration SDK
 
-**Status**: [Development](../document-status.md)
+**Status**: [Stable](../document-status.md) except where otherwise specified
 
 <!-- toc -->
 
@@ -23,7 +23,7 @@ weight: 3
     + [Register PluginComponentProvider](#register-plugincomponentprovider)
   * [Examples](#examples)
     + [Via configuration API](#via-configuration-api)
-    + [Via OTEL_EXPERIMENTAL_CONFIG_FILE](#via-otel_experimental_config_file)
+    + [Via OTEL_CONFIG_FILE](#via-otel_config_file)
   * [References](#references)
 
 <!-- tocstop -->
@@ -62,6 +62,8 @@ the name `Configuration` is RECOMMENDED.
 
 ### ConfigProvider
 
+**Status**: [Development](../document-status.md)
+
 The SDK implementation of [`ConfigProvider`](./api.md#configprovider) MUST be
 created using a [`ConfigProperties`](./api.md#configproperties) representing
 the [`.instrumentation`](https://github.com/open-telemetry/opentelemetry-configuration/blob/670901762dd5cce1eecee423b8660e69f71ef4be/examples/kitchen-sink.yaml#L438-L439)
@@ -183,8 +185,7 @@ Note: Because these operations are stateless pure functions, they are not
 defined as part of any type, class, interface, etc. SDKs may organize them in
 whatever manner is idiomatic for the language.
 
-TODO: Add operation to update SDK components with new configuration for usage
-with OpAmp
+<!-- TODO: https://github.com/open-telemetry/opentelemetry-specification/issues/3771 -->
 
 #### Parse
 
@@ -251,7 +252,7 @@ Interpret configuration model and return SDK components.
 * [MeterProvider](../metrics/sdk.md#meterprovider)
 * [LoggerProvider](../logs/sdk.md#loggerprovider)
 * [Propagators](../context/api-propagators.md#composite-propagator)
-* [ConfigProvider](#configprovider)
+* **Status**: [Development](../document-status.md) - [ConfigProvider](#configprovider)
 
 The multiple responses MAY be returned using a tuple, or some other data
 structure encapsulating the components.
@@ -296,10 +297,11 @@ This SHOULD return an error if it encounters an error in `configuration` (i.e.
 fail fast) in accordance with
 initialization [error handling principles](../error-handling.md#basic-error-handling-principles).
 
-SDK implementations MAY provide options to allow programmatic customization of
-the components initialized by `Create`. This allows configuration of concepts which
-are not yet or may never be representable in the configuration model. For example,
-java OTLP exporters allow configuration of the [ExecutorService](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html),
+**Status**: [Development](../document-status.md) SDK implementations MAY provide
+options to allow programmatic customization of the components initialized by `Create`.
+This allows configuration of concepts which are not yet or may never be representable
+in the configuration model. For example, java OTLP exporters allow configuration
+of the [ExecutorService](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html),
 a niche but important option for applications which need strict control of thread pools.
 This programmatic customization might take the form of passing an optional callback to
 `Create`, invoked with each SDK subcomponent (or a subset of SDK component types) as
@@ -319,7 +321,7 @@ Batch SpanProcessor, and a Tracer Provider. This pattern provides the opportunit
 to programmatically configure lower-level without needing to walk to a particular
 component from the resolved top level SDK components.
 
-TODO: define behavior if some portion of configuration model is not supported
+<!-- TODO: https://github.com/open-telemetry/opentelemetry-specification/issues/4804 -->
 
 #### Register PluginComponentProvider
 
@@ -405,10 +407,10 @@ ContextPropagators propagators = openTelemetry.getPropagators();
 ConfigProvider configProvider = openTelemetry.getConfigProvider();
 ```
 
-#### Via OTEL_EXPERIMENTAL_CONFIG_FILE
+#### Via OTEL_CONFIG_FILE
 
 Setting
-the [OTEL_EXPERIMENTAL_CONFIG_FILE](./sdk-environment-variables.md#declarative-configuration)
+the [OTEL_CONFIG_FILE](./sdk-environment-variables.md#declarative-configuration)
 environment variable (for languages that support it) provides users a convenient
 way to initialize OpenTelemetry components without needing to learn
 language-specific configuration details or use a large number of environment
@@ -418,11 +420,11 @@ resemble:
 
 ```shell
 # Set the required env var to the location of the configuration file
-export OTEL_EXPERIMENTAL_CONFIG_FILE="/app/sdk-config.yaml"
+export OTEL_CONFIG_FILE="/app/sdk-config.yaml"
 ```
 
 ```java
-// Initialize SDK using autoconfigure model, which recognizes that OTEL_EXPERIMENTAL_CONFIG_FILE is set and configures the SDK accordingly
+// Initialize SDK using autoconfigure model, which recognizes that OTEL_CONFIG_FILE is set and configures the SDK accordingly
 OpenTelemetry openTelemetry = AutoConfiguredOpenTelemetrySdk.initialize().getOpenTelemetrySdk();
 
 // Access SDK components and install instrumentation