Skip to content

Commit abf4244

Browse files
stevejgordonstevejgordon
committed
Add console app documentation
1 parent d9c3446 commit abf4244

File tree

6 files changed

+155
-6
lines changed

6 files changed

+155
-6
lines changed

‎docs/_edot-sdks/dotnet/configuration.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ available and their corresponding environment variable names, see [Configuration
3232
All OpenTelemetry environment variables from the upstream SDK may also be used to configure the SDK behavior for features
3333
such as resources, samples and exporters.
3434

35-
### `IConfiguration` integration
35+
### IConfiguration integration
3636

3737
In applications that use the [".NET generic host"](https://learn.microsoft.com/dotnet/core/extensions/generic-host), such as
3838
[ASP.NET Core](https://learn.microsoft.com/aspnet/core/introduction-to-aspnet-core) and

‎docs/_edot-sdks/dotnet/index.md

-1
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,6 @@ installing and using EDOT .NET in common application templates:
2828

2929
-------
3030

31-
3231
## Features
3332

3433
With EDOT .NET, you have access to all the features of the [OpenTelemetry SDK for .NET](https://github.com/open-telemetry/opentelemetry-dotnet) plus:

‎docs/_edot-sdks/dotnet/setup/aspnet.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,4 @@ parent: Setup
66
grand_parent: EDOT .NET
77
---
88

9-
# Set up OpenTelemetry for ASP.NET applications on .NET Framework
9+
# Set up EDOT .NET for ASP.NET applications on .NET Framework

‎docs/_edot-sdks/dotnet/setup/aspnetcore.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,4 @@ parent: Setup
66
grand_parent: EDOT .NET
77
---
88

9-
# Set up OpenTelemetry for ASP.NET Core applications
9+
# Set up EDOT .NET for ASP.NET Core applications

‎docs/_edot-sdks/dotnet/setup/console.md

+151-1
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,154 @@ parent: Setup
66
grand_parent: EDOT .NET
77
---
88

9-
# Set up OpenTelemetry for console applications
9+
# Set up EDOT .NET for console applications
10+
11+
Applications running without a [host](https://learn.microsoft.com/dotnet/core/extensions/generic-host) may initialize
12+
OpenTelemetry manually.
13+
14+
{: .note }
15+
> When building console applications, consider using the features provided by
16+
> [`Microsoft.Extensions.Hosting`](https://www.nuget.org/packages/microsoft.extensions.hosting) as this enables
17+
> dependency injection and logging capabilities.
18+
19+
```csharp
20+
using OpenTelemetry;
21+
22+
using OpenTelemetrySdk sdk = OpenTelemetrySdk.Create(builder => builder
23+
.WithElasticDefaults());
24+
```
25+
26+
The preceding code:
27+
28+
1. Imports the required types from the `OpenTelemetry` namespace.
29+
1. Creates an instance of the `OpenTelemetrySdk` using its factory `Create` method.
30+
1. Configures the `IOpenTelemetryBuilder` by passing a lambda.
31+
1. Enables EDOT .NET and its [opinionated defaults](./../setup/edot-defaults) by calling `WithElasticDefaults` on the `IOpenTelemetryBuilder`.
32+
33+
{: .warning }
34+
> The `using` keyword is applied in the preceding code to define a using declaration, which ensures that the
35+
> `OpenTelemetrySdk` instance is disposed of when the application terminates. Disposing of the OpenTelemetry SDK gives the
36+
> SDK a chance to flush any telemetry held in memory. Skipping this step may result in data loss.
37+
38+
The above code is sufficient for many applications to achieve a reasonable out-of-the-box experience. The
39+
`IOpenTelemetryBuilder` can be further configured as required within the target application.
40+
41+
For example, we can observe an additional `ActivitySource` by chaining a call to `WithTracing`,
42+
providing a lambda to configure the `TracerProviderBuilder` to add the name of the additional
43+
`ActivitySource`.
44+
45+
```csharp
46+
using OpenTelemetry;
47+
using OpenTelemetry.Trace;
48+
49+
using OpenTelemetrySdk sdk = OpenTelemetrySdk.Create(builder => builder
50+
.WithElasticDefaults()
51+
.WithTracing(t => t.AddSource("MyApp.SourceName")));
52+
```
53+
54+
We can further customise the OpenTelemetry SDK with the other built-in extension methods,
55+
such as `ConfigureResource`.
56+
57+
```csharp
58+
using OpenTelemetry;
59+
using OpenTelemetry.Trace;
60+
using OpenTelemetry.Resources;
61+
62+
using OpenTelemetrySdk sdk = OpenTelemetrySdk.Create(builder => builder
63+
.WithElasticDefaults()
64+
.ConfigureResource(r => r.AddService("MyAppName"))
65+
.WithTracing(t => t.AddSource("MyApp.SourceName")));
66+
```
67+
68+
## Providing configuration
69+
70+
When calling `OpenTelemetrySdk.Create` a dedicated `IServiceCollection` and `IServiceProvider` will be created for the
71+
SDK and shared by all signals. An `IConfiguration` is created automatically from environment variables. The
72+
recommended method to configure the OpenTelemetry SDK is via environment variables. At a minimum, we should set
73+
the environment variables used to configure the OTLP exporter using any suitable method for your operating system.
74+
75+
```
76+
"OTEL_EXPORTER_OTLP_ENDPOINT" = "https://{MyServerlessEndpoint}.apm.us-east-1.aws.elastic.cloud:443",
77+
"OTEL_EXPORTER_OTLP_HEADERS" = "Authorization=ApiKey {MyEncodedApiKey}"
78+
```
79+
80+
{: .note }
81+
> Replace the `{MyServerlessEndpoint}` and `{MyEncodedApiKey}` placeholders above with the values provided
82+
by your Elastic Observability backend.
83+
84+
### Configuring EDOT .NET
85+
86+
Several configuration settings are available to control the additional features offered by EDOT .NET.
87+
These may be configured using environment variables, `IConfiguration` and/or code-based configuration.
88+
89+
See the [configuration](./../configuration) documentation for more details.
90+
91+
As an example, manual code-based configuration can be used to disable the instrumentation assembly scanning
92+
feature.
93+
94+
```csharp
95+
using OpenTelemetry;
96+
using OpenTelemetry.Trace;
97+
using OpenTelemetry.Resources;
98+
using Elastic.OpenTelemetry;
99+
100+
var options = new ElasticOpenTelemetryOptions
101+
{
102+
SkipInstrumentationAssemblyScanning = true
103+
};
104+
105+
using OpenTelemetrySdk sdk = OpenTelemetrySdk.Create(builder => builder
106+
.WithElasticDefaults(options)
107+
.ConfigureResource(r => r.AddService("MyAppName3"))
108+
.WithTracing(t => t.AddSource("MyApp.SourceName")));
109+
```
110+
111+
The preceding code:
112+
113+
1. Creates an instance of `ElasticOpenTelemetryOptions`
114+
1. Configures `SkipInstrumentationAssemblyScanning` as `true` to disable the assembly scanning feature.
115+
1. Passes the `ElasticOpenTelemetryOptions` from the `options` variable into the `WithElasticDefaults` method.
116+
117+
It's also possible to use `IConfiguration` to control EDOT .NET.
118+
119+
```csharp
120+
using OpenTelemetry;
121+
using OpenTelemetry.Trace;
122+
using OpenTelemetry.Resources;
123+
using Microsoft.Extensions.Configuration;
124+
125+
const string edotPrefix = "Elastic:OpenTelemetry:";
126+
127+
var config = new ConfigurationBuilder()
128+
.AddJsonFile("appsettings.json")
129+
.AddInMemoryCollection(new Dictionary<string, string?>()
130+
{
131+
[$"{edotPrefix}SkipInstrumentationAssemblyScanning"] = "true",
132+
[$"{edotPrefix}LogDirectory"] = "C:\\Logs\\MyApp"
133+
})
134+
.Build();
135+
136+
using var sdk = OpenTelemetrySdk.Create(builder => builder
137+
.WithElasticDefaults(config)
138+
.ConfigureResource(r => r.AddService("MyAppName3"))
139+
.WithTracing(t => t.AddSource("MyApp.SourceName")));
140+
```
141+
142+
The preceding code:
143+
144+
1. Defines a constant string variable named `edotPrefix` to hold the configuration section prefix.
145+
1. Creates a new `ConfigurationBuilder` to bind configuration values from one or more providers (sources), such as JSON.
146+
1. Calls the `AddJsonFile` method to read configuration from a JSON file named "appsettings.json".
147+
1. Calls the `AddInMemoryCollection` method to add configuration settings from a `Dictionary` of supplied keys and values.
148+
1. Adds an entry for "SkipInstrumentationAssemblyScanning" prefixed with the correct section name, setting its value to "true."
149+
1. Adds an entry for "LogDirectory" prefixed with the correct section name, setting its value to "C:\Logs\MyApp".
150+
1. Builds an `IConfigurationRoot` (castable to `IConfiguration`) from the provided sources.
151+
1. Passes the `IConfiguration` from the `config` variable into the `WithElasticDefaults` method.
152+
153+
The example above requires the JSON configuration provider, which can be added as a NuGet package.
154+
155+
```xml
156+
<PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="<LATEST>" />
157+
```
158+
159+
Replace the `<LATEST>` version placeholder with the [latest available package from NuGet.org](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.Json).

‎docs/_edot-sdks/dotnet/setup/worker-services.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,4 @@ parent: Setup
66
grand_parent: EDOT .NET
77
---
88

9-
# Set up OpenTelemetry for worker services
9+
# Set up EDOT .NET for worker services

0 commit comments

Comments
 (0)