From 6360b49d20ae451b28f7ba0be168ed9a799ac9e1 Mon Sep 17 00:00:00 2001
From: jack-berg <34418638+jack-berg@users.noreply.github.com>
Date: Wed, 1 May 2024 11:34:59 -0500
Subject: [PATCH] Add file configuration examples (#4018)

Resolves #3465

---------

Co-authored-by: Reiley Yang <reyang@microsoft.com>
---
 CHANGELOG.md                                  |  2 +
 .../configuration/file-configuration.md       | 87 +++++++++++++++++++
 2 files changed, 89 insertions(+)

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)
 
 <!-- tocstop -->
@@ -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