Skip to content

Commit e4dccf0

Browse files
bmorelli25bmorelli25
authored
Docs: Switch from Asciidoc to MDX (#110)
1 parent 9c62840 commit e4dccf0

6 files changed

+199
-214
lines changed

‎docs/configuration.asciidoc renamed to ‎docs/configure.mdx

Lines changed: 73 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,74 @@
1-
[[configuration]]
2-
== Configuration
1+
---
2+
slug: /otel-dotnet/configure
3+
title: Configure
4+
---
35

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+
Configuration of the OpenTelemetry SDK should be performed through the
7+
mechanisms [documented on the OpenTelemetry website](https://opentelemetry.io/docs/languages/net/automatic/configuration/).
68

7-
The Elastic distribution can be further configured using advanced settings when
9+
The Elastic distribution can be further configured using advanced settings when
810
you need complete control of its behaviour. Configuration can be achieved by setting environment variables,
911
using the `IConfiguration` integration, or manually configuring the Elastic distribution.
1012

11-
=== Environment variables
13+
## Environment variables
1214

1315
The Elastic distribution can be configured using environment variables. This is a cross-platform
1416
way to configure the Elastic distribution and is especially useful in containerized environments.
1517

1618
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+
For details of the various options available and their corresponding environment variable names,
20+
see [configuration otpions](#configuration_options).
1921

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

23-
=== IConfiguration integration
25+
## IConfiguration integration
2426

25-
In applications that use the "host" pattern, such as ASP.NET Core and worker service, the Elastic
27+
In applications that use the "host" pattern, such as ASP.NET Core and worker service, the Elastic
2628
distribution can be configured using the `IConfiguration` integration. This is done by passing an
2729
`IConfiguration` instance to the `AddElasticOpenTelemetry` extension method on the `IServiceCollection`.
2830

2931
When using an `IHostApplicationBuilder` such as modern ASP.NET Core applications, the current `IConfiguration`
3032
can be accessed via the `Configuration` property on the builder.
3133

32-
[source,csharp]
33-
----
34+
```csharp
3435
var builder = WebApplication.CreateBuilder(args);
35-
var currentConfig = builder.Configuration; <1>
36-
----
37-
<1> Access the current `IConfiguration` instance from the builder.
36+
var currentConfig = builder.Configuration; [^1]
37+
```
38+
[^1]: Access the current `IConfiguration` instance from the builder.
3839

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
40+
By default, at this stage, the configuration will be populated from the default configuration sources,
41+
including the `appsettings.json` file(s) and command-line arguments. You may use these sources to define
4142
the configuration for the Elastic distribution.
4243

4344
For example, you can define the configuration for the Elastic distribution in the `appsettings.json` file:
4445

45-
[source,json]
46-
----
46+
```json
4747
{
4848
"Elastic": {
4949
"OpenTelemetry": {
50-
"FileLogDirectory": "C:\\Logs" <1>
50+
"FileLogDirectory": "C:\\Logs" [^1]
5151
}
5252
}
5353
}
54-
----
55-
<1> This example sets the file log directory to `C:\Logs` which enables diagnostic file logging.
54+
```
55+
[^1]: This example sets the file log directory to `C:\Logs` which enables diagnostic file logging.
5656

57-
Configuration from the "Elastic:OpenTelemetry" section of the `IConfiguration` instance will be
57+
Configuration from the "Elastic:OpenTelemetry" section of the `IConfiguration` instance will be
5858
bound to the `ElasticOpenTelemetryOptions` instance used to configure the Elastic distribution.
5959

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].
60+
To learn more about the Microsoft configuration system, see
61+
[Configuration in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration).
6262

63-
=== Manual configuration
63+
## Manual configuration
6464

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
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
6767
or an overload of the `AddElasticOpenTelemetry` extension method on the `IServiceCollection`.
6868

6969
For example, in traditional console applications, you can configure the Elastic distribution like this:
7070

71-
[source,csharp]
72-
----
71+
```csharp
7372
using Elastic.OpenTelemetry;
7473
using Elastic.OpenTelemetry.Configuration;
7574
using Elastic.OpenTelemetry.Extensions;
@@ -78,95 +77,73 @@ using OpenTelemetry;
7877

7978
var services = new ServiceCollection();
8079

81-
var builderOptions = new ElasticOpenTelemetryBuilderOptions <1>
80+
var builderOptions = new ElasticOpenTelemetryBuilderOptions [^1]
8281
{
83-
DistroOptions = new ElasticOpenTelemetryOptions <2>
82+
DistroOptions = new ElasticOpenTelemetryOptions [^2]
8483
{
85-
FileLogDirectory = "C:\\Logs", <3>
84+
FileLogDirectory = "C:\\Logs", [^3]
8685
}
8786
};
8887

89-
await using var session = new ElasticOpenTelemetryBuilder(builderOptions) <4>
88+
await using var session = new ElasticOpenTelemetryBuilder(builderOptions) [^4]
9089
.WithTracing(b => b.AddSource("MySource"))
9190
.Build();
92-
----
93-
<1> Create an instance of `ElasticOpenTelemetryBuilderOptions`
94-
<2> Create an instance of `ElasticOpenTelemetryOptions` and configure the file log directory by
91+
```
92+
[^1]: Create an instance of `ElasticOpenTelemetryBuilderOptions`
93+
[^2]: Create an instance of `ElasticOpenTelemetryOptions` and configure the file log directory by
9594
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
95+
[^3]: This example sets the file log directory to `C:\Logs` which enables diagnostic file logging.
96+
[^4]: Pass the `ElasticOpenTelemetryBuilderOptions` instance to the `ElasticOpenTelemetryBuilder` constructor
9897
to configure the Elastic distribution.
9998

100-
[[configuration-options]]
101-
=== Configuration options
99+
## Configuration options
102100

103-
[float]
104-
[[config-filelogdirectory]]
105-
==== `FileLogDirectory`
101+
### `FileLogDirectory`
106102

107-
A string specifying the directory where the Elastic distribution will write diagnostic log files.
103+
A string specifying the directory where the Elastic distribution will write diagnostic log files.
108104
When not provided, no file logging will occur. Each new .NET process will create a new log file in the
109105
specified directory.
110106

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-
|============
107+
| Environment variable name | IConfiguration key |
108+
| ------------- |-------------|
109+
| `ELASTIC_OTEL_FILE_LOG_DIRECTORY` | `Elastic:OpenTelemetry:FileLogDirectory` |
122110

111+
| Default | Type |
112+
| ------------- |-------------|
113+
| `string.Empty` | String |
123114

124-
[float]
125-
[[config-fileloglevel]]
126-
==== `FileLogLevel`
115+
### `FileLogLevel`
127116

128117
Sets the logging level for the distribtuion.
129118

130119
Valid options: `Critical`, `Error`, `Warning`, `Information`, `Debug`, `Trace` and `None` (`None` disables the logging).
131120

132-
[options="header"]
133-
|============
134-
| Environment variable name | IConfiguration key
135-
| `ELASTIC_OTEL_FILE_LOG_LEVEL` | `Elastic:OpenTelemetry:FileLogLevel`
136-
|============
121+
| Environment variable name | IConfiguration key |
122+
| ------------- |-------------|
123+
| `ELASTIC_OTEL_FILE_LOG_LEVEL` | `Elastic:OpenTelemetry:FileLogLevel` |
137124

138-
[options="header"]
139-
|============
140-
| Default | Type
141-
| `Information` | String
142-
|============
125+
| Default | Type |
126+
| ------------- |-------------|
127+
| `Information` | String |
143128

129+
### `SkipOtlpExporter`
144130

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
131+
Allows the distribution to used with its defaults, but without enabling the export of telemetry data to
150132
an OTLP endpoint. This can be useful when you want to test applications without sending telemetry data.
151133

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-
|============
134+
| Environment variable name | IConfiguration key |
135+
| ------------- |-------------|
136+
| `ELASTIC_OTEL_SKIP_OTLP_EXPORTER` | `Elastic:OpenTelemetry:SkipOtlpExporter` |
163137

138+
| Default | Type |
139+
| ------------- |-------------|
140+
| `false` | Bool |
164141

165142
[float]
166143
[[config-enabledelasticdefaults]]
167-
==== `EnabledElasticDefaults`
144+
### `EnabledElasticDefaults`
168145

169-
A comma-separated list of Elastic defaults to enable. This can be useful when you want to enable
146+
A comma-separated list of Elastic defaults to enable. This can be useful when you want to enable
170147
only some of the Elastic distribution opinionated defaults.
171148

172149
Valid options: `None`, `Tracing`, `Metrics`, `Logging`.
@@ -178,20 +155,16 @@ When this setting is not configured or the value is `string.Empty`, all Elastic
178155
When `None` is specified, no Elastic distribution defaults will be enabled, and you will need to manually
179156
configure the OpenTelemetry SDK to enable collection of telemetry signals. In this mode, the Elastic distribution
180157
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
158+
OpenTelemetry SDK configuration. You may then choose to configure the various providers and register processors
182159
as required.
183160

184-
In all other cases, the Elastic distribution will enable the specified defaults. For example, to enable only
161+
In all other cases, the Elastic distribution will enable the specified defaults. For example, to enable only
185162
Elastic defaults only for tracing and metrics, set this value to `Tracing,Metrics`.
186163

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-
|============
164+
| Environment variable name | IConfiguration key |
165+
| ------------- |-------------|
166+
| `ELASTIC_OTEL_ENABLE_ELASTIC_DEFAULTS` | `Elastic:OpenTelemetry:EnabledElasticDefaults` |
167+
168+
| Default | Type |
169+
| ------------- |-------------|
170+
| `string.Empty` | String |

‎docs/elastic-otel-dotnet.docnav.json

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"mission": ".NET",
3+
"id": "elastic-otel-dotnet",
4+
"landingPageSlug": "/otel-dotnet/intro",
5+
"icon": "logoObservability",
6+
"description": "Elastic OpenTelemetry Distribution for .NET",
7+
"items": [
8+
{
9+
"label": "Get started",
10+
"slug": "/otel-dotnet/get-started"
11+
},
12+
{
13+
"label": "Configure",
14+
"slug": "/otel-dotnet/configure"
15+
}
16+
]
17+
}

0 commit comments

Comments
 (0)