From 04649ba9b1abf60ddde88f25c845dc4f177e1bfc Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Tue, 24 Jun 2025 09:43:21 -0500 Subject: [PATCH 1/2] Mark declarative config as stable --- spec-compliance-matrix.md | 2 +- specification/configuration/data-model.md | 2 +- .../configuration/sdk-environment-variables.md | 17 ++++++++--------- specification/configuration/sdk.md | 14 ++++++++------ 4 files changed, 18 insertions(+), 17 deletions(-) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 1a30f6d2bd4..aa5f158d34e 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -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 diff --git a/specification/configuration/data-model.md b/specification/configuration/data-model.md index e6b4dad8183..201cb9c221d 100644 --- a/specification/configuration/data-model.md +++ b/specification/configuration/data-model.md @@ -1,6 +1,6 @@ # Configuration Data Model -**Status**: [Development](../document-status.md) +**Status**: [Stable](../document-status.md) diff --git a/specification/configuration/sdk-environment-variables.md b/specification/configuration/sdk-environment-variables.md index 67fe69feaa1..0108456fa07 100644 --- a/specification/configuration/sdk-environment-variables.md +++ b/specification/configuration/sdk-environment-variables.md @@ -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 @@ -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) diff --git a/specification/configuration/sdk.md b/specification/configuration/sdk.md index 98d0dbf5b4c..35e7e344d56 100644 --- a/specification/configuration/sdk.md +++ b/specification/configuration/sdk.md @@ -1,6 +1,6 @@ # Configuration SDK -**Status**: [Development](../document-status.md) +**Status**: [Stable](../document-status.md) except where otherwise specified @@ -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) @@ -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) @@ -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 @@ -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 From e1a7e093a5b74eea4280da2c5d3e245a5f0c6296 Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Thu, 10 Jul 2025 16:51:56 -0500 Subject: [PATCH 2/2] PR feedback --- specification/configuration/sdk.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/specification/configuration/sdk.md b/specification/configuration/sdk.md index 35e7e344d56..04cdd195b91 100644 --- a/specification/configuration/sdk.md +++ b/specification/configuration/sdk.md @@ -186,9 +186,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 - #### Parse Parse and validate a [configuration file](./data-model.md#file-based-configuration-model). @@ -252,7 +249,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)) The multiple responses MAY be returned using a tuple, or some other data structure encapsulating the components. @@ -281,8 +278,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 - #### Register ComponentProvider The SDK MUST provide a mechanism to @@ -295,8 +290,7 @@ 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. * `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. @@ -304,6 +298,11 @@ as `ComponentProvider`s. 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