Merge branch 'main' into reyang/docfx

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
 

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