Skip to content

Mark declarative config as stable #4568

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
+25 −25
Open

Mark declarative config as stable #4568

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
04649ba
Mark declarative config as stable
jack-berg Jun 24, 2025
274afc5
Merge branch 'main' into stabilize-declarative-config
jack-berg Jun 24, 2025
678225d
Merge branch 'main' of https://github.com/open-telemetry/opentelemetr…
jack-berg Jul 10, 2025
e1a7e09
PR feedback
jack-berg Jul 10, 2025
72946fb
Merge branch 'main' into stabilize-declarative-config
codeboten Aug 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion spec-compliance-matrix.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -282,7 +282,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

Expand Down
2 changes: 1 addition & 1 deletion specification/configuration/data-model.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Configuration Data Model

**Status**: [Development](../document-status.md)
**Status**: [Stable](../document-status.md)

<!-- toc -->

Expand Down
17 changes: 8 additions & 9 deletions specification/configuration/sdk-environment-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -369,21 +369,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
Expand All @@ -394,11 +393,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 [`sdk-migration-config.yaml`](https://github.com/open-telemetry/opentelemetry-configuration/blob/main/examples/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, [`sdk-config.yaml`](https://github.com/open-telemetry/opentelemetry-configuration/blob/main/examples/sdk-config.yaml)
Expand Down
14 changes: 8 additions & 6 deletions specification/configuration/sdk.md
View file
Open in desktop
Copy link
Member

@pellared pellared Jul 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The type parameter in https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk.md#register-componentprovider is not well-defined.
Is it an enumeration? I guess that the intention is that these are "SDK extension plugin interface" names.

Side note (for sure not needed for stabilization):
Do we want to also add some "instrumentation plugin" which could be any object so that the instrumentation/distribution could parse and interpret after it is returned by https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/api.md#get-instrumentation-config?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Took a crack at it by adding this guidance:

SDKs should represent type in a manner that is idiomatic for their language.
For example, a class literal, an enumeration, or similar.
See supported SDK extension plugins for the set of
supported type values.

Let me know what you think.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is a lot better. But please create a separate PR for it 😉

PS. I hope you are OK that I made some comments here instead of creating new (spamming) GitHub issues.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes the comments are great.

Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Configuration SDK

**Status**: [Development](../document-status.md)
**Status**: [Stable](../document-status.md) except where otherwise specified

<!-- toc -->

Expand All @@ -18,7 +18,7 @@
+ [Register ComponentProvider](#register-componentprovider)
* [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 -->
Expand Down Expand Up @@ -57,6 +57,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)
Expand Down Expand Up @@ -360,10 +362,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
Expand All @@ -373,11 +375,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
Expand Down
Loading