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
Open

Mark declarative config as stable #4568

Show file tree
Hide file tree
Changes from all 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
Expand Up @@ -5,7 +5,7 @@ weight: 2

# 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 @@ -374,21 +374,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 @@ -399,11 +398,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
29 changes: 15 additions & 14 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
Expand Up @@ -5,7 +5,7 @@ weight: 3

# Configuration SDK

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

<!-- toc -->

Expand All @@ -23,7 +23,7 @@ weight: 3
+ [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 @@ -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)
Expand Down Expand Up @@ -189,9 +191,6 @@ 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
Copy link
Member Author

Choose a reason for hiding this comment

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

Tracking here: #3771

Copy link
Member

Choose a reason for hiding this comment

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

Feel free to resolve.
PS. You can consider adding

<!-- TODO: https://github.com/open-telemetry/opentelemetry-specification/issues/3771 -->

if it helps you in future.


#### Parse

Parse and validate a [configuration file](./data-model.md#file-based-configuration-model).
Expand Down Expand Up @@ -255,7 +254,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)
* [ConfigProvider](#configprovider) (**Status**: [Development](../document-status.md))
Copy link
Member

Choose a reason for hiding this comment

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

nit: just to follow the existing pattern from other places of the specification

Suggested change
* [ConfigProvider](#configprovider) (**Status**: [Development](../document-status.md))
* **Status**: [Development](../document-status.md) - [ConfigProvider](#configprovider)

Copy link
Member Author

Choose a reason for hiding this comment

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

I'm not sure about this. I recently was talking with internal colleagues of mine who were reading the log spec and thought that the a variety of stable components were "In Development" because of confusing placement of the status text. For example:

Screenshot 2025-07-19 at 1 23 33 PM

Because there is no other text in the Logger section, and because its not clear where the "In development" ends, the entire SDK Logger component seems to be unstable, which of course is not the case.

I do think we should be consistent, but think that spec's current strategy for calling out a different status should be improved. Though in this particular case putting the status before the list entry doesn't seem to be more confusing.

Copy link
Member

@pellared pellared Jul 30, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Though in this particular case putting the status before the list entry doesn't seem to be more confusing.

I agree therefore I prefer consistency.

that spec's current strategy for calling out a different status should be improved

I also agree but this should be a subject of a separate PR.

I think we could consider making some sections like (using https://github.com/orgs/community/discussions/16925):

Note

Status: Development

Paragraph. Tell me something more.

Not sure how it will render in https://opentelemetry.io/.
@open-telemetry/docs-approvers, do you have any ideas?

For bullet-points, I think that the current strategy may be good enough.

Copy link
Member

Choose a reason for hiding this comment

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

Answering for the @open-telemetry/docs-approvers, it's a known issue that GitHub Markdown alerts don't render well on opentelemetry.io. That being said, there are spec docs that use this notation today.


The multiple responses MAY be returned using a tuple, or some other data
structure encapsulating the components.
Expand Down Expand Up @@ -284,8 +283,6 @@ 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).

TODO: define behavior if some portion of configuration model is not supported
Copy link
Member Author

Choose a reason for hiding this comment

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

We now have guidance around misalignment of file_format specified by user and supported by an SDK: https://github.com/open-telemetry/opentelemetry-configuration?tab=readme-ov-file#file-format

Also related, we're working on tooling to allow implementations to document what properties they support here: open-telemetry/opentelemetry-configuration#197


#### Register ComponentProvider

The SDK MUST provide a mechanism to
Expand All @@ -298,15 +295,19 @@ as `ComponentProvider`s.
**Parameters:**

* `component_provider` - The `ComponentProvider`.
* `type` - The type of plugin interface it provides (e.g. SpanExporter, Sampler,
etc).
* `type` - The type of plugin interface it provides.
Copy link
Member

Choose a reason for hiding this comment

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

I do not like that in one place we are saying "component" in other "plugin" or "plugin interfaces".
I know that it keeps the same intention, but it makes me harder to read and interpret the specification.
I propose to use the term "Component" everywhere and just mention in the "Component" definition that this is a plugin that allows extensibility of the Configuration SDK.

Copy link
Member Author

Choose a reason for hiding this comment

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

That's fine with me. I was trying to connect the dots because elsewhere in the spec we both the words component and plugin interface. I'll try to be consistent here with "component" but also have a callout with something to the effect of: "... (also called plugin interface elsewhere in the spec)"

Copy link
Member

Choose a reason for hiding this comment

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

The https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk.md#supported-sdk-extension-plugins should define "mappings" between a "type" and where it is supposed to be used in the configuration model e.g. that SpanProcessor component is represented in https://github.com/open-telemetry/opentelemetry-configuration/blob/d6b127882f41db92b26017c736a52ceb6f2b4451/schema/tracer_provider.json#L208

Copy link
Member Author

Choose a reason for hiding this comment

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

Yeah that linking would be helpful 👍

* `name` - The name used to identify the type of component. This is used
in [configuration model](./data-model.md) to specify that the
corresponding `component_provider` is to provide the component.

The `type` and `name` comprise a unique key. Register MUST return an error if it
is called multiple times with the same `type` and `name` combination.

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](#sdk-extension-components) for the set of
supported `type` values.

### Examples

#### Via configuration API
Expand Down Expand Up @@ -365,10 +366,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 @@ -378,11 +379,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