Improve configuration story

docs/configuration.asciidoc

@@ -0,0 +1,197 @@
+[[configuration]]
+== Configuration
+
+Configuration of the OpenTelemetry SDK should be performed through the 
+mechanisms https://opentelemetry.io/docs/languages/net/automatic/configuration/[documented on the OpenTelemetry website].
+
+The Elastic distribution can be further configured using advanced settings when 
+you need complete control of its behaviour. Configuration can be achieved by setting environment variables,
+using the `IConfiguration` integration, or manually configuring the Elastic distribution.
+
+=== Environment variables
+
+The Elastic distribution can be configured using environment variables. This is a cross-platform
+way to configure the Elastic distribution and is especially useful in containerized environments.
+
+Environment variables are read at startup and can be used to configure the Elastic distribution.
+For details of the various options available and their corresponding environment variable names, 
+see <<configuration-options>>.
+
+Environment variables always take precedence over configuration provided by the `IConfiguration`
+system.
+
+=== IConfiguration integration
+
+In applications that use the "host" pattern, such as ASP.NET Core and worker service, the Elastic 
+distribution can be configured using the `IConfiguration` integration. This is done by passing an
+`IConfiguration` instance to the `AddElasticOpenTelemetry` extension method on the `IServiceCollection`.
+
+When using an `IHostApplicationBuilder` such as modern ASP.NET Core applications, the current `IConfiguration`
+can be accessed via the `Configuration` property on the builder.
+
+[source,csharp]
+----
+var builder = WebApplication.CreateBuilder(args);
+var currentConfig = builder.Configuration; <1>
+----
+<1> Access the current `IConfiguration` instance from the builder.
+
+By default, at this stage, the configuration will be populated from the default configuration sources, 
+including the `appsettings.json` file(s) and command-line arguments. You may use these sources to define 
+the configuration for the Elastic distribution.
+
+For example, you can define the configuration for the Elastic distribution in the `appsettings.json` file:
+
+[source,json]
+----
+{
+  "Elastic": {
+    "OpenTelemetry": {
+      "FileLogDirectory": "C:\\Logs" <1>
+    }
+  }
+}
+----
+<1> This example sets the file log directory to `C:\Logs` which enables diagnostic file logging.
+
+Configuration from the "Elastic:OpenTelemetry" section of the `IConfiguration` instance will be 
+bound to the `ElasticOpenTelemetryOptions` instance used to configure the Elastic distribution.
+
+To learn more about the Microsoft configuration system, see 
+https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration[Configuration in ASP.NET Core].
+
+=== Manual configuration
+
+In all other scenarios, configuration can be achieved manually in code. This is done by creating 
+an instance of `ElasticOpenTelemetryBuilderOptions` and passing it to the `ElasticOpenTelemetryBuilder` constructor 
+or an overload of the `AddElasticOpenTelemetry` extension method on the `IServiceCollection`.
+
+For example, in traditional console applications, you can configure the Elastic distribution like this:
+
+[source,csharp]
+----
+using Elastic.OpenTelemetry;
+using Elastic.OpenTelemetry.Configuration;
+using Elastic.OpenTelemetry.Extensions;
+using Microsoft.Extensions.DependencyInjection;
+using OpenTelemetry;
+
+var services = new ServiceCollection();
+
+var builderOptions = new ElasticOpenTelemetryBuilderOptions <1>
+{
+	DistroOptions = new ElasticOpenTelemetryOptions <2>
+	{
+		FileLogDirectory = "C:\\Logs", <3>
+	}
+};
+
+await using var session = new ElasticOpenTelemetryBuilder(builderOptions) <4>
+	.WithTracing(b => b.AddSource("MySource"))
+	.Build();
+----
+<1> Create an instance of `ElasticOpenTelemetryBuilderOptions`
+<2> Create an instance of `ElasticOpenTelemetryOptions` and configure the file log directory by
+setting the corresponding property.
+<3> This example sets the file log directory to `C:\Logs` which enables diagnostic file logging.
+<4> Pass the `ElasticOpenTelemetryBuilderOptions` instance to the `ElasticOpenTelemetryBuilder` constructor 
+to configure the Elastic distribution.
+
+[[configuration-options]]
+=== Configuration options
+
+[float]
+[[config-filelogdirectory]]
+==== `FileLogDirectory`
+
+A string specifying the directory where the Elastic distribution will write diagnostic log files. 
+When not provided, no file logging will occur. Each new .NET process will create a new log file in the
+specified directory.
+
+[options="header"]
+|============
+| Environment variable name       | IConfiguration key
+| `ELASTIC_OTEL_FILE_LOG_DIRECTORY`         | `Elastic:OpenTelemetry:FileLogDirectory`
+|============
+
+[options="header"]
+|============
+| Default        | Type
+| `string.Empty`       | String
+|============
+
+
+[float]
+[[config-fileloglevel]]
+==== `FileLogLevel`
+
+Sets the logging level for the distribtuion.
+
+Valid options: `Critical`, `Error`, `Warning`, `Information`, `Debug`, `Trace` and `None` (`None` disables the logging).
+
+[options="header"]
+|============
+| Environment variable name       | IConfiguration key
+| `ELASTIC_OTEL_FILE_LOG_LEVEL`         | `Elastic:OpenTelemetry:FileLogLevel`
+|============
+
+[options="header"]
+|============
+| Default        | Type
+| `Information`       | String
+|============
+
+
+[float]
+[[config-skipotlpexporter]]
+==== `SkipOtlpExporter`
+
+Allows the distribution to used with its defaults, but without enabling the export of telemetry data to 
+an OTLP endpoint. This can be useful when you want to test applications without sending telemetry data.
+
+[options="header"]
+|============
+| Environment variable name       | IConfiguration key
+| `ELASTIC_OTEL_SKIP_OTLP_EXPORTER`         | `Elastic:OpenTelemetry:SkipOtlpExporter`
+|============
+
+[options="header"]
+|============
+| Default        | Type
+| `false`       | Bool
+|============
+
+
+[float]
+[[config-enabledelasticdefaults]]
+==== `EnabledElasticDefaults`
+
+A comma-separated list of Elastic defaults to enable. This can be useful when you want to enable 
+only some of the Elastic distribution opinionated defaults.
+
+Valid options: `None`, `Tracing`, `Metrics`, `Logging`.
+
+Except for the `None` option, all other options can be combined.
+
+When this setting is not configured or the value is `string.Empty`, all Elastic distribution defaults will be enabled.
+
+When `None` is specified, no Elastic distribution defaults will be enabled, and you will need to manually
+configure the OpenTelemetry SDK to enable collection of telemetry signals. In this mode, the Elastic distribution
+does not provide any opinionated defaults, nor register any processors, allowing you to start with the "vanilla"
+OpenTelemetry SDK configuration. You may then choose to configure the various providers and register processors 
+as required.
+
+In all other cases, the Elastic distribution will enable the specified defaults. For example, to enable only 
+Elastic defaults only for tracing and metrics, set this value to `Tracing,Metrics`.
+
+[options="header"]
+|============
+| Environment variable name       | IConfiguration key
+| `ELASTIC_OTEL_ENABLE_ELASTIC_DEFAULTS`         | `Elastic:OpenTelemetry:EnabledElasticDefaults`
+|============
+
+[options="header"]
+|============
+| Default        | Type
+| `string.Empty`       | String
+|============

docs/index.asciidoc

@@ -6,3 +6,5 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
 include::./intro.asciidoc[]
 
 include::./getting-started.asciidoc[]
+
+include::./configuration.asciidoc[]

examples/Example.MinimalApi/Program.cs

@@ -8,11 +8,12 @@
 
 var builder = WebApplication.CreateBuilder(args);
 
+// This will add the OpenTelemetry services using Elastic defaults
 builder.AddServiceDefaults();
 
 builder.Services
 	.AddHttpClient() // Adds IHttpClientFactory
-	.AddOpenTelemetry() // Adds the OpenTelemetry SDK
+	.AddOpenTelemetry() // Adds app specific tracing
 		.WithTracing(t => t.AddSource(Api.ActivitySourceName));
 
 var app = builder.Build();

examples/Example.MinimalApi/appsettings.json

@@ -3,11 +3,17 @@
     "LogLevel": {
       "Default": "Information",
       "Microsoft.AspNetCore": "Warning",
-      "Elastic.OpenTelemetry": "Information"
+      "Elastic.OpenTelemetry": "Warning"
     }
   },
   "AllowedHosts": "*",
   "AspNetCoreInstrumentation": {
     "RecordException": "true"
+  },
+  "Elastic": {
+    "OpenTelemetry": {
+      "FileLogDirectory": "C:\\Logs\\OtelDistro",
+      "FileLogLevel": "Information"
+    }
   }
 }

examples/ServiceDefaults/Extensions.cs

@@ -44,7 +44,7 @@ public static IHostApplicationBuilder ConfigureOpenTelemetry(this IHostApplicati
 			logging.IncludeScopes = true;
 		});
 
-		builder.Services.AddOpenTelemetry()
+		builder.Services.AddElasticOpenTelemetry(builder.Configuration)
 			.WithMetrics(metrics =>
 			{
 				metrics.AddAspNetCoreInstrumentation()

src/Elastic.OpenTelemetry/ElasticOpenTelemetryOptions.cs → src/Elastic.OpenTelemetry/Configuration/ElasticOpenTelemetryBuilderOptions.cs

@@ -5,13 +5,15 @@
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Logging;
 
-namespace Elastic.OpenTelemetry;
+namespace Elastic.OpenTelemetry.Configuration;
 
 /// <summary>
 /// Expert options to provide to <see cref="ElasticOpenTelemetryBuilder"/> to control its initial OpenTelemetry registration.
 /// </summary>
-public record ElasticOpenTelemetryOptions
+public record ElasticOpenTelemetryBuilderOptions
 {
+	private ElasticOpenTelemetryOptions? _elasticOpenTelemetryOptions;
+
 	/// <summary>
 	/// Provide an additional logger to the internal file logger.
 	/// <para>
@@ -24,15 +26,15 @@ public record ElasticOpenTelemetryOptions
 	/// Provides an <see cref="IServiceCollection"/> to register the <see cref="IInstrumentationLifetime"/> into.
 	/// If null, a new local instance will be used.
 	/// </summary>
-	public IServiceCollection? Services { get; init; }
-
-	/// <summary>
-	/// Stops <see cref="ElasticOpenTelemetryBuilder"/> from registering OLTP exporters, useful for testing scenarios.
-	/// </summary>
-	public bool SkipOtlpExporter { get; init; }
+	internal IServiceCollection? Services { get; init; }
 
 	/// <summary>
-	/// Optional name which is used when retrieving OTLP options.
+	/// Advanced options which can be used to finely-tune the behaviour of the Elastic
+	/// distribution of OpenTelemetry.
 	/// </summary>
-	public string? OtlpExporterName { get; init; }
+	public ElasticOpenTelemetryOptions DistroOptions
+	{
+		get => _elasticOpenTelemetryOptions ?? new();
+		init => _elasticOpenTelemetryOptions = value;
+	}
 }