From aceb6fd945d0262c2d512edbaba332104d8b4232 Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Fri, 26 Apr 2024 17:18:55 -0500 Subject: [PATCH 1/4] Add file configuration examples --- .../configuration/file-configuration.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) diff --git a/specification/configuration/file-configuration.md b/specification/configuration/file-configuration.md index 29a18645f65..8cdafab1107 100644 --- a/specification/configuration/file-configuration.md +++ b/specification/configuration/file-configuration.md @@ -350,6 +350,90 @@ register [component providers](#component-provider). 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. +## Examples + +### Via File Configuration API + +The file configuration [Parse](#parse) and [Create](#create) operations along +with the [Configuration Model](#configuration-model) can be combined in a +variety of ways to achieve simple or complex configuration goals. + +For example, a simple case would consist of calling `Parse` with a configuration +file, and passing the result to `Create` to obtain configured SDK components: + +```java +OpenTelemetry openTelemetry = OpenTelemetry.noop(); +try { + // Parse configuration file to configuration model + OpenTelemetryConfiguration configurationModel = FileConfiguration.parse(new File("/app/sdk-config.yaml")); + // Create SDK components from configuration model + openTelemetry = FileConfiguration.create(configurationModel); +} catch (Throwable e) { + log.error("Error initializing SDK from configuration file", e); +} + +// Access SDK components and install instrumentation +TracerProvider tracerProvider = openTelemetry.getTracerProvider(); +MeterProvider meterProvider = openTelemetry.getMeterProvider(); +LoggerProvider loggerProvider = openTelemetry.getLogsBridge(); +ContextPropagators propagators = openTelemetry.getPropagators(); +``` + +A more complex case might consist of parsing multiple configuration files from +different sources, merging them using custom logic, and creating SDK components +from the merged configuration model: + +```java +OpenTelemetry openTelemetry = OpenTelemetry.noop(); +try { + // Parse local and remote configuration files to configuration models + OpenTelemetryConfiguration localConfigurationModel = FileConfiguration.parse(new File("/app/sdk-config.yaml")); + OpenTelemetryConfiguration remoteConfigurationModel = FileConfiguration.parse(getRemoteConfiguration("http://example-host/config/my-application")); + + // Merge the configuration models using custom logic + OpenTelemetryConfiguration resolvedConfigurationModel = merge(localConfigurationModel, remoteConfigurationModel); + + // Create SDK components from resolved configuration model + openTelemetry = FileConfiguration.create(configurationModel); +} catch (Throwable e) { + log.error("Error initializing SDK from configuration file", e); +} + +// Access SDK components and install instrumentation +TracerProvider tracerProvider = openTelemetry.getTracerProvider(); +MeterProvider meterProvider = openTelemetry.getMeterProvider(); +LoggerProvider loggerProvider = openTelemetry.getLogsBridge(); +ContextPropagators propagators = openTelemetry.getPropagators(); +``` + +### Via OTEL_EXPERIMENTAL_CONFIG_FILE + +If an SDK +supports [OTEL_EXPERIMENTAL_CONFIG_FILE](./sdk-environment-variables.md#file-configuration), +then setting `OTEL_EXPERIMENTAL_CONFIG_FILE` provides a simple way to obtain an +SDK initialized from the specified config file. The pattern for accessing the +configured SDK components and installing into instrumentation will vary by +language. For example, the usage in java might resemble: + +```shell +# Set the required env var to the location of the configuration file +export OTEL_EXPERIMENTAL_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 +OpenTelemetry openTelemetry = AutoConfiguredOpenTelemetrySdk.initialize().getOpenTelemetrySdk(); + +// Access SDK components and install instrumentation +TracerProvider tracerProvider = openTelemetry.getTracerProvider(); +MeterProvider meterProvider = openTelemetry.getMeterProvider(); +LoggerProvider loggerProvider = openTelemetry.getLogsBridge(); +ContextPropagators propagators = openTelemetry.getPropagators(); +``` + +If using auto-instrumentation, this initialization flow might occur +automatically. + ## References * Configuration From 4132c00c34d04634f2bd7d6715cd54e2507e581b Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Mon, 29 Apr 2024 11:05:09 -0500 Subject: [PATCH 2/4] Markdown toc --- specification/configuration/file-configuration.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/specification/configuration/file-configuration.md b/specification/configuration/file-configuration.md index 8cdafab1107..973b54d26cc 100644 --- a/specification/configuration/file-configuration.md +++ b/specification/configuration/file-configuration.md @@ -23,6 +23,9 @@ linkTitle: File + [Parse](#parse) + [Create](#create) + [Register Component Provider](#register-component-provider) +- [Examples](#examples) + * [Via File Configuration API](#via-file-configuration-api) + * [Via OTEL_EXPERIMENTAL_CONFIG_FILE](#via-otel_experimental_config_file) - [References](#references) From f31f29e51b8befaa4347c48a55b27cec142633d7 Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Mon, 29 Apr 2024 11:06:19 -0500 Subject: [PATCH 3/4] PR feedback --- specification/configuration/file-configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/configuration/file-configuration.md b/specification/configuration/file-configuration.md index 973b54d26cc..ae8f9839aa4 100644 --- a/specification/configuration/file-configuration.md +++ b/specification/configuration/file-configuration.md @@ -397,7 +397,7 @@ try { OpenTelemetryConfiguration resolvedConfigurationModel = merge(localConfigurationModel, remoteConfigurationModel); // Create SDK components from resolved configuration model - openTelemetry = FileConfiguration.create(configurationModel); + openTelemetry = FileConfiguration.create(resolvedConfigurationModel); } catch (Throwable e) { log.error("Error initializing SDK from configuration file", e); } @@ -416,7 +416,7 @@ supports [OTEL_EXPERIMENTAL_CONFIG_FILE](./sdk-environment-variables.md#file-con then setting `OTEL_EXPERIMENTAL_CONFIG_FILE` provides a simple way to obtain an SDK initialized from the specified config file. The pattern for accessing the configured SDK components and installing into instrumentation will vary by -language. For example, the usage in java might resemble: +language. For example, the usage in Java might resemble: ```shell # Set the required env var to the location of the configuration file From 5588d0eb0d8cba6ffad5fa3b1e2c0eb97e096e03 Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Mon, 29 Apr 2024 11:10:06 -0500 Subject: [PATCH 4/4] Add changelog entry --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9218fe4caf4..2181cdc6bec 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -37,6 +37,8 @@ release. - Clarify syntax for environment variable substitution regular expression ([#4001](https://github.com/open-telemetry/opentelemetry-specification/pull/4001)) +- Add end to end examples for file configuration + ([#4018](https://github.com/open-telemetry/opentelemetry-specification/pull/4018)) ### Common