diff --git a/CHANGELOG.md b/CHANGELOG.md index 4a81560c37e..8da9c9ca2ba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index efaa5239f1a..65153b3f5d6 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -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 diff --git a/spec-compliance-matrix/cpp.yaml b/spec-compliance-matrix/cpp.yaml index 54adfbe39e0..0aaf5524376 100644 --- a/spec-compliance-matrix/cpp.yaml +++ b/spec-compliance-matrix/cpp.yaml @@ -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: diff --git a/spec-compliance-matrix/dotnet.yaml b/spec-compliance-matrix/dotnet.yaml index 6f1c3547f8c..a2ef21ece1d 100644 --- a/spec-compliance-matrix/dotnet.yaml +++ b/spec-compliance-matrix/dotnet.yaml @@ -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: diff --git a/spec-compliance-matrix/erlang.yaml b/spec-compliance-matrix/erlang.yaml index c420308ba12..669013168e9 100644 --- a/spec-compliance-matrix/erlang.yaml +++ b/spec-compliance-matrix/erlang.yaml @@ -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: diff --git a/spec-compliance-matrix/go.yaml b/spec-compliance-matrix/go.yaml index be8e4f7b7de..5d91280b3e5 100644 --- a/spec-compliance-matrix/go.yaml +++ b/spec-compliance-matrix/go.yaml @@ -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: diff --git a/spec-compliance-matrix/java.yaml b/spec-compliance-matrix/java.yaml index a85185715f1..dc05756b766 100644 --- a/spec-compliance-matrix/java.yaml +++ b/spec-compliance-matrix/java.yaml @@ -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: diff --git a/spec-compliance-matrix/js.yaml b/spec-compliance-matrix/js.yaml index c21b4ad63d6..578edc0da45 100644 --- a/spec-compliance-matrix/js.yaml +++ b/spec-compliance-matrix/js.yaml @@ -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: diff --git a/spec-compliance-matrix/php.yaml b/spec-compliance-matrix/php.yaml index 29f02ebfe2e..76eb1cae2ea 100644 --- a/spec-compliance-matrix/php.yaml +++ b/spec-compliance-matrix/php.yaml @@ -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: diff --git a/spec-compliance-matrix/python.yaml b/spec-compliance-matrix/python.yaml index ff242091e95..98d0339639b 100644 --- a/spec-compliance-matrix/python.yaml +++ b/spec-compliance-matrix/python.yaml @@ -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: diff --git a/spec-compliance-matrix/ruby.yaml b/spec-compliance-matrix/ruby.yaml index 5a10f0fd1e5..d1bd419577e 100644 --- a/spec-compliance-matrix/ruby.yaml +++ b/spec-compliance-matrix/ruby.yaml @@ -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: diff --git a/spec-compliance-matrix/rust.yaml b/spec-compliance-matrix/rust.yaml index 00bc5e18011..0fa3be45b1e 100644 --- a/spec-compliance-matrix/rust.yaml +++ b/spec-compliance-matrix/rust.yaml @@ -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: diff --git a/spec-compliance-matrix/swift.yaml b/spec-compliance-matrix/swift.yaml index ae93a346c71..99c40c12931 100644 --- a/spec-compliance-matrix/swift.yaml +++ b/spec-compliance-matrix/swift.yaml @@ -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: diff --git a/spec-compliance-matrix/template.yaml b/spec-compliance-matrix/template.yaml index a56f56c48f1..55786b02c62 100644 --- a/spec-compliance-matrix/template.yaml +++ b/spec-compliance-matrix/template.yaml @@ -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: diff --git a/specification/configuration/api.md b/specification/configuration/api.md index ceb5cacfddd..34d48f9983e 100644 --- a/specification/configuration/api.md +++ b/specification/configuration/api.md @@ -5,7 +5,7 @@ weight: 1 # Instrumentation Configuration API -**Status**: [Development](../document-status.md) +**Status**: [Mixed](../document-status.md) @@ -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). diff --git a/specification/configuration/data-model.md b/specification/configuration/data-model.md index 012dfef7fc4..453a534ac15 100644 --- a/specification/configuration/data-model.md +++ b/specification/configuration/data-model.md @@ -5,7 +5,7 @@ weight: 2 # 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 be202a43f43..c5a199a57c5 100644 --- a/specification/configuration/sdk-environment-variables.md +++ b/specification/configuration/sdk-environment-variables.md @@ -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) diff --git a/specification/configuration/sdk.md b/specification/configuration/sdk.md index 5a1a1f0c983..40d0fe5d0c8 100644 --- a/specification/configuration/sdk.md +++ b/specification/configuration/sdk.md @@ -5,7 +5,7 @@ weight: 3 # Configuration SDK -**Status**: [Development](../document-status.md) +**Status**: [Stable](../document-status.md) except where otherwise specified @@ -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) @@ -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 + #### 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 + #### 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