diff --git a/CHANGELOG.md b/CHANGELOG.md index 4d28449a17e..fdbee8bab21 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -41,6 +41,8 @@ release. ([#4001](https://github.com/open-telemetry/opentelemetry-specification/pull/4001)) - Error out on invalid identifiers in environment variable substitution. ([#4002](https://github.com/open-telemetry/opentelemetry-specification/pull/4002)) +- Add end to end examples for file configuration + ([#4018](https://github.com/open-telemetry/opentelemetry-specification/pull/4018)) ### Common diff --git a/specification/configuration/file-configuration.md b/specification/configuration/file-configuration.md index acff78f0ed6..5e8739094c4 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) @@ -358,6 +361,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(resolvedConfigurationModel); +} 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