Skip to content

Commit

Permalink
Docs: Switch from Asciidoc to MDX (#110)
Browse files Browse the repository at this point in the history
  • Loading branch information
@bmorelli25
bmorelli25 authored Jul 3, 2024
1 parent 9c62840 commit e4dccf0
Show file tree
Hide file tree
Showing 6 changed files with 199 additions and 214 deletions.
173 changes: 73 additions & 100 deletions docs/configuration.asciidoc → docs/configure.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,75 +1,74 @@
[[configuration]]
== Configuration
---
slug: /otel-dotnet/configure
title: Configure
---

Configuration of the OpenTelemetry SDK should be performed through the
mechanisms https://opentelemetry.io/docs/languages/net/automatic/configuration/[documented on the OpenTelemetry website].
Configuration of the OpenTelemetry SDK should be performed through the
mechanisms [documented on the OpenTelemetry website](https://opentelemetry.io/docs/languages/net/automatic/configuration/).

The Elastic distribution can be further configured using advanced settings when
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
## 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>>.
For details of the various options available and their corresponding environment variable names,
see [configuration otpions](#configuration_options).

Environment variables always take precedence over configuration provided by the `IConfiguration`
system.

=== IConfiguration integration
## IConfiguration integration

In applications that use the "host" pattern, such as ASP.NET Core and worker service, the Elastic
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]
----
```csharp
var builder = WebApplication.CreateBuilder(args);
var currentConfig = builder.Configuration; <1>
----
<1> Access the current `IConfiguration` instance from the builder.
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
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]
----
```json
{
"Elastic": {
"OpenTelemetry": {
"FileLogDirectory": "C:\\Logs" <1>
"FileLogDirectory": "C:\\Logs" [^1]
}
}
}
----
<1> This example sets the file log directory to `C:\Logs` which enables diagnostic file logging.
```
[^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
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].
To learn more about the Microsoft configuration system, see
[Configuration in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration).

=== Manual configuration
## 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
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]
----
```csharp
using Elastic.OpenTelemetry;
using Elastic.OpenTelemetry.Configuration;
using Elastic.OpenTelemetry.Extensions;
Expand All @@ -78,95 +77,73 @@ using OpenTelemetry;

var services = new ServiceCollection();

var builderOptions = new ElasticOpenTelemetryBuilderOptions <1>
var builderOptions = new ElasticOpenTelemetryBuilderOptions [^1]
{
DistroOptions = new ElasticOpenTelemetryOptions <2>
DistroOptions = new ElasticOpenTelemetryOptions [^2]
{
FileLogDirectory = "C:\\Logs", <3>
FileLogDirectory = "C:\\Logs", [^3]
}
};

await using var session = new ElasticOpenTelemetryBuilder(builderOptions) <4>
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
```
[^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
[^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
## Configuration options

[float]
[[config-filelogdirectory]]
==== `FileLogDirectory`
### `FileLogDirectory`

A string specifying the directory where the Elastic distribution will write diagnostic log files.
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
|============
| Environment variable name | IConfiguration key |
| ------------- |-------------|
| `ELASTIC_OTEL_FILE_LOG_DIRECTORY` | `Elastic:OpenTelemetry:FileLogDirectory` |

| Default | Type |
| ------------- |-------------|
| `string.Empty` | String |

[float]
[[config-fileloglevel]]
==== `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`
|============
| Environment variable name | IConfiguration key |
| ------------- |-------------|
| `ELASTIC_OTEL_FILE_LOG_LEVEL` | `Elastic:OpenTelemetry:FileLogLevel` |

[options="header"]
|============
| Default | Type
| `Information` | String
|============
| Default | Type |
| ------------- |-------------|
| `Information` | String |

### `SkipOtlpExporter`

[float]
[[config-skipotlpexporter]]
==== `SkipOtlpExporter`

Allows the distribution to used with its defaults, but without enabling the export of telemetry data to
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
|============
| Environment variable name | IConfiguration key |
| ------------- |-------------|
| `ELASTIC_OTEL_SKIP_OTLP_EXPORTER` | `Elastic:OpenTelemetry:SkipOtlpExporter` |

| Default | Type |
| ------------- |-------------|
| `false` | Bool |

[float]
[[config-enabledelasticdefaults]]
==== `EnabledElasticDefaults`
### `EnabledElasticDefaults`

A comma-separated list of Elastic defaults to enable. This can be useful when you want to enable
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`.
Expand All @@ -178,20 +155,16 @@ When this setting is not configured or the value is `string.Empty`, all Elastic
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
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
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
|============
| Environment variable name | IConfiguration key |
| ------------- |-------------|
| `ELASTIC_OTEL_ENABLE_ELASTIC_DEFAULTS` | `Elastic:OpenTelemetry:EnabledElasticDefaults` |

| Default | Type |
| ------------- |-------------|
| `string.Empty` | String |
17 changes: 17 additions & 0 deletions docs/elastic-otel-dotnet.docnav.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
{
"mission": ".NET",
"id": "elastic-otel-dotnet",
"landingPageSlug": "/otel-dotnet/intro",
"icon": "logoObservability",
"description": "Elastic OpenTelemetry Distribution for .NET",
"items": [
{
"label": "Get started",
"slug": "/otel-dotnet/get-started"
},
{
"label": "Configure",
"slug": "/otel-dotnet/configure"
}
]
}
Loading

0 comments on commit e4dccf0

Please sign in to comment.