Skip to content

Commit 596bd9c

Browse files
stevejgordonstevejgordon
authored
Improve configuration story (#90)
* Improve configuration story * Update test assertion * Ensure we fallback to logging section and event listener respects value
1 parent abf079c commit 596bd9c

27 files changed

+1198
-159
lines changed

‎docs/configuration.asciidoc

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
[[configuration]]
2+
== Configuration
3+
4+
Configuration of the OpenTelemetry SDK should be performed through the
5+
mechanisms https://opentelemetry.io/docs/languages/net/automatic/configuration/[documented on the OpenTelemetry website].
6+
7+
The Elastic distribution can be further configured using advanced settings when
8+
you need complete control of its behaviour. Configuration can be achieved by setting environment variables,
9+
using the `IConfiguration` integration, or manually configuring the Elastic distribution.
10+
11+
=== Environment variables
12+
13+
The Elastic distribution can be configured using environment variables. This is a cross-platform
14+
way to configure the Elastic distribution and is especially useful in containerized environments.
15+
16+
Environment variables are read at startup and can be used to configure the Elastic distribution.
17+
For details of the various options available and their corresponding environment variable names,
18+
see <<configuration-options>>.
19+
20+
Environment variables always take precedence over configuration provided by the `IConfiguration`
21+
system.
22+
23+
=== IConfiguration integration
24+
25+
In applications that use the "host" pattern, such as ASP.NET Core and worker service, the Elastic
26+
distribution can be configured using the `IConfiguration` integration. This is done by passing an
27+
`IConfiguration` instance to the `AddElasticOpenTelemetry` extension method on the `IServiceCollection`.
28+
29+
When using an `IHostApplicationBuilder` such as modern ASP.NET Core applications, the current `IConfiguration`
30+
can be accessed via the `Configuration` property on the builder.
31+
32+
[source,csharp]
33+
----
34+
var builder = WebApplication.CreateBuilder(args);
35+
var currentConfig = builder.Configuration; <1>
36+
----
37+
<1> Access the current `IConfiguration` instance from the builder.
38+
39+
By default, at this stage, the configuration will be populated from the default configuration sources,
40+
including the `appsettings.json` file(s) and command-line arguments. You may use these sources to define
41+
the configuration for the Elastic distribution.
42+
43+
For example, you can define the configuration for the Elastic distribution in the `appsettings.json` file:
44+
45+
[source,json]
46+
----
47+
{
48+
"Elastic": {
49+
"OpenTelemetry": {
50+
"FileLogDirectory": "C:\\Logs" <1>
51+
}
52+
}
53+
}
54+
----
55+
<1> This example sets the file log directory to `C:\Logs` which enables diagnostic file logging.
56+
57+
Configuration from the "Elastic:OpenTelemetry" section of the `IConfiguration` instance will be
58+
bound to the `ElasticOpenTelemetryOptions` instance used to configure the Elastic distribution.
59+
60+
To learn more about the Microsoft configuration system, see
61+
https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration[Configuration in ASP.NET Core].
62+
63+
=== Manual configuration
64+
65+
In all other scenarios, configuration can be achieved manually in code. This is done by creating
66+
an instance of `ElasticOpenTelemetryBuilderOptions` and passing it to the `ElasticOpenTelemetryBuilder` constructor
67+
or an overload of the `AddElasticOpenTelemetry` extension method on the `IServiceCollection`.
68+
69+
For example, in traditional console applications, you can configure the Elastic distribution like this:
70+
71+
[source,csharp]
72+
----
73+
using Elastic.OpenTelemetry;
74+
using Elastic.OpenTelemetry.Configuration;
75+
using Elastic.OpenTelemetry.Extensions;
76+
using Microsoft.Extensions.DependencyInjection;
77+
using OpenTelemetry;
78+
79+
var services = new ServiceCollection();
80+
81+
var builderOptions = new ElasticOpenTelemetryBuilderOptions <1>
82+
{
83+
DistroOptions = new ElasticOpenTelemetryOptions <2>
84+
{
85+
FileLogDirectory = "C:\\Logs", <3>
86+
}
87+
};
88+
89+
await using var session = new ElasticOpenTelemetryBuilder(builderOptions) <4>
90+
.WithTracing(b => b.AddSource("MySource"))
91+
.Build();
92+
----
93+
<1> Create an instance of `ElasticOpenTelemetryBuilderOptions`
94+
<2> Create an instance of `ElasticOpenTelemetryOptions` and configure the file log directory by
95+
setting the corresponding property.
96+
<3> This example sets the file log directory to `C:\Logs` which enables diagnostic file logging.
97+
<4> Pass the `ElasticOpenTelemetryBuilderOptions` instance to the `ElasticOpenTelemetryBuilder` constructor
98+
to configure the Elastic distribution.
99+
100+
[[configuration-options]]
101+
=== Configuration options
102+
103+
[float]
104+
[[config-filelogdirectory]]
105+
==== `FileLogDirectory`
106+
107+
A string specifying the directory where the Elastic distribution will write diagnostic log files.
108+
When not provided, no file logging will occur. Each new .NET process will create a new log file in the
109+
specified directory.
110+
111+
[options="header"]
112+
|============
113+
| Environment variable name | IConfiguration key
114+
| `ELASTIC_OTEL_FILE_LOG_DIRECTORY` | `Elastic:OpenTelemetry:FileLogDirectory`
115+
|============
116+
117+
[options="header"]
118+
|============
119+
| Default | Type
120+
| `string.Empty` | String
121+
|============
122+
123+
124+
[float]
125+
[[config-fileloglevel]]
126+
==== `FileLogLevel`
127+
128+
Sets the logging level for the distribtuion.
129+
130+
Valid options: `Critical`, `Error`, `Warning`, `Information`, `Debug`, `Trace` and `None` (`None` disables the logging).
131+
132+
[options="header"]
133+
|============
134+
| Environment variable name | IConfiguration key
135+
| `ELASTIC_OTEL_FILE_LOG_LEVEL` | `Elastic:OpenTelemetry:FileLogLevel`
136+
|============
137+
138+
[options="header"]
139+
|============
140+
| Default | Type
141+
| `Information` | String
142+
|============
143+
144+
145+
[float]
146+
[[config-skipotlpexporter]]
147+
==== `SkipOtlpExporter`
148+
149+
Allows the distribution to used with its defaults, but without enabling the export of telemetry data to
150+
an OTLP endpoint. This can be useful when you want to test applications without sending telemetry data.
151+
152+
[options="header"]
153+
|============
154+
| Environment variable name | IConfiguration key
155+
| `ELASTIC_OTEL_SKIP_OTLP_EXPORTER` | `Elastic:OpenTelemetry:SkipOtlpExporter`
156+
|============
157+
158+
[options="header"]
159+
|============
160+
| Default | Type
161+
| `false` | Bool
162+
|============
163+
164+
165+
[float]
166+
[[config-enabledelasticdefaults]]
167+
==== `EnabledElasticDefaults`
168+
169+
A comma-separated list of Elastic defaults to enable. This can be useful when you want to enable
170+
only some of the Elastic distribution opinionated defaults.
171+
172+
Valid options: `None`, `Tracing`, `Metrics`, `Logging`.
173+
174+
Except for the `None` option, all other options can be combined.
175+
176+
When this setting is not configured or the value is `string.Empty`, all Elastic distribution defaults will be enabled.
177+
178+
When `None` is specified, no Elastic distribution defaults will be enabled, and you will need to manually
179+
configure the OpenTelemetry SDK to enable collection of telemetry signals. In this mode, the Elastic distribution
180+
does not provide any opinionated defaults, nor register any processors, allowing you to start with the "vanilla"
181+
OpenTelemetry SDK configuration. You may then choose to configure the various providers and register processors
182+
as required.
183+
184+
In all other cases, the Elastic distribution will enable the specified defaults. For example, to enable only
185+
Elastic defaults only for tracing and metrics, set this value to `Tracing,Metrics`.
186+
187+
[options="header"]
188+
|============
189+
| Environment variable name | IConfiguration key
190+
| `ELASTIC_OTEL_ENABLE_ELASTIC_DEFAULTS` | `Elastic:OpenTelemetry:EnabledElasticDefaults`
191+
|============
192+
193+
[options="header"]
194+
|============
195+
| Default | Type
196+
| `string.Empty` | String
197+
|============

‎docs/index.asciidoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,5 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
66
include::./intro.asciidoc[]
77

88
include::./getting-started.asciidoc[]
9+
10+
include::./configuration.asciidoc[]

‎examples/Example.MinimalApi/Program.cs

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,12 @@
88

99
var builder = WebApplication.CreateBuilder(args);
1010

11+
// This will add the OpenTelemetry services using Elastic defaults
1112
builder.AddServiceDefaults();
1213

1314
builder.Services
1415
.AddHttpClient() // Adds IHttpClientFactory
15-
.AddOpenTelemetry() // Adds the OpenTelemetry SDK
16+
.AddOpenTelemetry() // Adds app specific tracing
1617
.WithTracing(t => t.AddSource(Api.ActivitySourceName));
1718

1819
var app = builder.Build();

‎examples/Example.MinimalApi/appsettings.json

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,17 @@
33
"LogLevel": {
44
"Default": "Information",
55
"Microsoft.AspNetCore": "Warning",
6-
"Elastic.OpenTelemetry": "Information"
6+
"Elastic.OpenTelemetry": "Warning"
77
}
88
},
99
"AllowedHosts": "*",
1010
"AspNetCoreInstrumentation": {
1111
"RecordException": "true"
12+
},
13+
"Elastic": {
14+
"OpenTelemetry": {
15+
"FileLogDirectory": "C:\\Logs\\OtelDistro",
16+
"FileLogLevel": "Information"
17+
}
1218
}
1319
}

‎examples/ServiceDefaults/Extensions.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ public static IHostApplicationBuilder ConfigureOpenTelemetry(this IHostApplicati
4444
logging.IncludeScopes = true;
4545
});
4646

47-
builder.Services.AddOpenTelemetry()
47+
builder.Services.AddElasticOpenTelemetry(builder.Configuration)
4848
.WithMetrics(metrics =>
4949
{
5050
metrics.AddAspNetCoreInstrumentation()

‎src/Elastic.OpenTelemetry/ElasticOpenTelemetryOptions.cs renamed to ‎src/Elastic.OpenTelemetry/Configuration/ElasticOpenTelemetryBuilderOptions.cs

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,15 @@
55
using Microsoft.Extensions.DependencyInjection;
66
using Microsoft.Extensions.Logging;
77

8-
namespace Elastic.OpenTelemetry;
8+
namespace Elastic.OpenTelemetry.Configuration;
99

1010
/// <summary>
1111
/// Expert options to provide to <see cref="ElasticOpenTelemetryBuilder"/> to control its initial OpenTelemetry registration.
1212
/// </summary>
13-
public record ElasticOpenTelemetryOptions
13+
public record ElasticOpenTelemetryBuilderOptions
1414
{
15+
private ElasticOpenTelemetryOptions? _elasticOpenTelemetryOptions;
16+
1517
/// <summary>
1618
/// Provide an additional logger to the internal file logger.
1719
/// <para>
@@ -24,15 +26,15 @@ public record ElasticOpenTelemetryOptions
2426
/// Provides an <see cref="IServiceCollection"/> to register the <see cref="IInstrumentationLifetime"/> into.
2527
/// If null, a new local instance will be used.
2628
/// </summary>
27-
public IServiceCollection? Services { get; init; }
28-
29-
/// <summary>
30-
/// Stops <see cref="ElasticOpenTelemetryBuilder"/> from registering OLTP exporters, useful for testing scenarios.
31-
/// </summary>
32-
public bool SkipOtlpExporter { get; init; }
29+
internal IServiceCollection? Services { get; init; }
3330

3431
/// <summary>
35-
/// Optional name which is used when retrieving OTLP options.
32+
/// Advanced options which can be used to finely-tune the behaviour of the Elastic
33+
/// distribution of OpenTelemetry.
3634
/// </summary>
37-
public string? OtlpExporterName { get; init; }
35+
public ElasticOpenTelemetryOptions DistroOptions
36+
{
37+
get => _elasticOpenTelemetryOptions ?? new();
38+
init => _elasticOpenTelemetryOptions = value;
39+
}
3840
}

0 commit comments

Comments
 (0)