Skip to content

Commit 8d8d3ba

Browse files
colleenmcginnisMpdreamz
colleenmcginnis
and
Mpdreamz
authored
[docs] Prepare docs (#127)
Closes elastic/observability-docs#4056 Closes elastic/obs-docs-projects#240 Builds out minimal viable docs. ## What's included This includes the overall structure of the initial doc set. There is some missing information. I've left code comments with questions to be answered throughout the files. Read more about what needs to be included in these docs in [Elastic Distributions for OpenTelemetry (Mini docs style guide)](https://docs.google.com/document/d/1W0pvuEdVQpa8_dpiBBO0mQwZXZwTgBu8S4SkV40kjJQ/edit#heading=h.bg370r7gv0lr) (internal doc). ## To do - [x] @colleenmcginnis convert back to AsciiDoc - [x] @colleenmcginnis add initial outline with questions for the dev team in code comments - [x] @colleenmcginnis continue clean up / aligning across languages - [x] @elastic/apm-agent-net review content that's already there, add content that's missing (especially where there are questions in code comments) * Feel free to either commit directly to this PR or add suggestions in PR comments &mdash; whichever works best for you! - [x] @colleenmcginnis clean up content - [x] @elastic/obs-docs peer review - [x] @colleenmcginnis address feedback - [x] 🆕 @colleenmcginnis convert to Markdown - [x] 🆕 @colleenmcginnis reorganize content as needed to be consumed on GitHub - [x] 🆕 @colleenmcginnis slight content reframing - [x] 🆕 @colleenmcginnis update product naming as needed - [x] @elastic/apm-agent-net final review, approve - [x] @colleenmcginnis merge --------- Co-authored-by: Martijn Laarman <[email protected]>
1 parent 6e5241f commit 8d8d3ba

19 files changed

+609
-464
lines changed

‎README.md

Lines changed: 87 additions & 74 deletions
Large diffs are not rendered by default.

‎docs/configure.md

Lines changed: 262 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,262 @@
1+
<!--
2+
Goal of this doc:
3+
Provide a complete reference of all available configuration options and where/how they can be set. (Any Elastic-specific configuration options are listed directly. General OpenTelemetry configuration options are linked.)
4+
5+
Assumptions we're comfortable making about the reader:
6+
* They are familiar with Elastic
7+
* They are familiar with OpenTelemetry
8+
-->
9+
10+
# Configure
11+
12+
Configure the Elastic Distribution of OpenTelemetry .NET (EDOT .NET) to send data to Elastic.
13+
14+
<!-- ✅ How users set configuration options -->
15+
## Configuration methods
16+
17+
Configure the OpenTelemetry SDK using the mechanisms listed in the [OpenTelemetry documentation](https://opentelemetry.io/docs/languages/net/automatic/configuration/),
18+
including:
19+
20+
* Setting [environment variables](#environment-variables)
21+
* Using the [`IConfiguration` integration](#iconfiguration-integration)
22+
* [Manually configuring](#manual-configuration) EDOT .NET
23+
24+
<!-- Order of precedence -->
25+
Configuration options set manually in the code take precedence over environment variables, and
26+
environment variables take precedence over configuration options set using the `IConfiguration` system.
27+
28+
### Environment variables
29+
30+
<!-- ✅ What and why -->
31+
EDOT .NET can be configured using environment variables.
32+
This is a cross-platform way to configure EDOT .NET and is especially useful in containerized environments.
33+
34+
<!-- ✅ How -->
35+
Environment variables are read at startup and can be used to configure EDOT .NET.
36+
For details of the various options available and their corresponding environment variable names,
37+
see [Configuration options](#configuration-options)
38+
39+
### `IConfiguration` integration
40+
41+
<!-- ✅ What and why -->
42+
In applications that use the "host" pattern, such as ASP.NET Core and worker service, EDOT .NET
43+
can be configured using the `IConfiguration` integration.
44+
45+
<!-- ✅ How -->
46+
This is done by passing an `IConfiguration` instance to the `AddElasticOpenTelemetry` extension
47+
method on the `IServiceCollection`.
48+
49+
When using an `IHostApplicationBuilder` such as modern ASP.NET Core applications, the current `IConfiguration`
50+
can be accessed via the `Configuration` property on the builder:
51+
52+
```csharp
53+
var builder = WebApplication.CreateBuilder(args);
54+
// Access the current `IConfiguration` instance from the builder.
55+
var currentConfig = builder.Configuration;
56+
```
57+
58+
By default, at this stage, the configuration will be populated from the default configuration sources,
59+
including the `appsettings.json` file(s) and command-line arguments. You may use these sources to define
60+
the configuration for the Elastic Distribution of OpenTelemetry .NET.
61+
62+
<!-- ✅ Example -->
63+
For example, you can define the configuration for the Elastic Distribution of OpenTelemetry .NET in the `appsettings.json` file:
64+
65+
```json
66+
{
67+
"Elastic": {
68+
"OpenTelemetry": {
69+
"FileLogDirectory": "C:\\Logs"
70+
}
71+
}
72+
}
73+
```
74+
75+
> [!NOTE]
76+
> This example sets the file log directory to `C:\Logs` which enables diagnostic file logging.
77+
78+
Configuration from the "Elastic:OpenTelemetry" section of the `IConfiguration` instance will be
79+
bound to the `ElasticOpenTelemetryOptions` instance used to configure EDOT .NET.
80+
81+
To learn more about the Microsoft configuration system, see
82+
[Configuration in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration).
83+
84+
### Manual configuration
85+
86+
<!-- ✅ What and why -->
87+
In all other scenarios, you can configure EDOT .NET manually in code.
88+
89+
<!-- ✅ How -->
90+
Create an instance of `ElasticOpenTelemetryBuilderOptions` and pass it to the `ElasticOpenTelemetryBuilder`
91+
constructor or an overload of the `AddElasticOpenTelemetry` extension method on the `IServiceCollection`.
92+
93+
<!-- ✅ Example -->
94+
For example, in traditional console applications, you can configure the
95+
Elastic Distribution of OpenTelemetry .NET like this:
96+
97+
```csharp
98+
using Elastic.OpenTelemetry;
99+
using Elastic.OpenTelemetry.Configuration;
100+
using Elastic.OpenTelemetry.Extensions;
101+
using Microsoft.Extensions.DependencyInjection;
102+
using OpenTelemetry;
103+
104+
var services = new ServiceCollection();
105+
106+
// Create an instance of `ElasticOpenTelemetryBuilderOptions`.
107+
var builderOptions = new ElasticOpenTelemetryBuilderOptions
108+
{
109+
// Create an instance of `ElasticOpenTelemetryOptions` and configure
110+
// the file log directory by setting the corresponding property.
111+
DistroOptions = new ElasticOpenTelemetryOptions
112+
{
113+
// This example sets the file log directory to `C:\Logs`
114+
// which enables diagnostic file logging.
115+
FileLogDirectory = "C:\\Logs",
116+
}
117+
};
118+
119+
// Pass the `ElasticOpenTelemetryBuilderOptions` instance to the
120+
// `ElasticOpenTelemetryBuilder` constructor to configure EDOT .NET.
121+
await using var session = new ElasticOpenTelemetryBuilder(builderOptions)
122+
.WithTracing(b => b.AddSource("MySource"))
123+
.Build();
124+
```
125+
126+
<!-- ✅ List all available configuration options -->
127+
## Configuration options
128+
129+
Because the Elastic Distribution of OpenTelemetry .NET (EDOT .NET) is an extension of the [OpenTelemetry .NET agent](https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation), it supports both:
130+
131+
* General OpenTelemetry SDK configuration options
132+
* Elastic-specific configuration options that are only available when using EDOT .NET
133+
134+
### OpenTelemetry SDK configuration options
135+
136+
EDOT .NET supports all configuration options listed in the [OpenTelemetry General SDK Configuration documentation](https://opentelemetry.io/docs/languages/sdk-configuration/general/).
137+
138+
### Elastic-specific configuration options
139+
140+
EDOT .NET supports the following Elastic-specific options.
141+
142+
#### `FileLogDirectory`
143+
144+
* _Type_: String
145+
* _Default_: `string.Empty`
146+
147+
A string specifying the directory where the Elastic Distribution of OpenTelemetry .NET will write diagnostic log files.
148+
When not provided, no file logging will occur. Each new .NET process will create a new log file in the
149+
specified directory.
150+
151+
| Configuration method | Key |
152+
|---|---|
153+
| Environment variable | `ELASTIC_OTEL_FILE_LOG_DIRECTORY` |
154+
| `IConfiguration` integration | `Elastic:OpenTelemetry:FileLogDirectory` |
155+
156+
#### `FileLogLevel`
157+
158+
* _Type_: String
159+
* _Default_: `Information`
160+
161+
Sets the logging level for EDOT .NET.
162+
163+
Valid options: `Critical`, `Error`, `Warning`, `Information`, `Debug`, `Trace` and `None` (`None` disables the logging).
164+
165+
| Configuration method | Key |
166+
|---|---|
167+
| Environment variable | `ELASTIC_OTEL_FILE_LOG_LEVEL` |
168+
| `IConfiguration` integration | `Elastic:OpenTelemetry:FileLogLevel` |
169+
170+
#### `SkipOtlpExporter`
171+
172+
* _Type_: Bool
173+
* _Default_: `false`
174+
175+
Allows EDOT .NET to used with its defaults, but without enabling the export of telemetry data to
176+
an OTLP endpoint. This can be useful when you want to test applications without sending telemetry data.
177+
178+
| Configuration method | Key |
179+
|---|---|
180+
| Environment variable | `ELASTIC_OTEL_SKIP_OTLP_EXPORTER` |
181+
| `IConfiguration` integration | `Elastic:OpenTelemetry:SkipOtlpExporter` |
182+
183+
#### `ElasticDefaults`
184+
185+
* _Type_: String
186+
* _Default_: `string.Empty`
187+
188+
A comma-separated list of Elastic defaults to enable. This can be useful when you want to enable
189+
only some of the Elastic Distribution of OpenTelemetry .NET opinionated defaults.
190+
191+
Valid options: `None`, `Traces`, `Metrics`, `Logs`, `All`.
192+
193+
Except for the `None` option, all other options can be combined.
194+
195+
When this setting is not configured or the value is `string.Empty`, all Elastic Distribution of OpenTelemetry .NET defaults will be enabled.
196+
197+
When `None` is specified, no Elastic Distribution of OpenTelemetry .NET defaults will be enabled, and you will need to manually
198+
configure the OpenTelemetry SDK to enable collection of telemetry signals. In this mode, EDOT .NET
199+
does not provide any opinionated defaults, nor register any processors, allowing you to start with the "vanilla"
200+
OpenTelemetry SDK configuration. You may then choose to configure the various providers and register processors
201+
as required.
202+
203+
In all other cases, the Elastic Distribution of OpenTelemetry .NET will enable the specified defaults. For example, to enable only
204+
Elastic defaults only for tracing and metrics, set this value to `Traces,Metrics`.
205+
206+
| Configuration method | Key |
207+
|---|---|
208+
| Environment variable | `ELASTIC_OTEL_DEFAULTS_ENABLED` |
209+
| `IConfiguration` integration | `Elastic:OpenTelemetry:ElasticDefaults` |
210+
211+
<!-- ✅ List auth methods -->
212+
## Authentication methods
213+
214+
When sending data to Elastic, there are two ways you can authenticate: using an APM agent key or using a secret token.
215+
216+
### Use an APM agent key (API key)
217+
218+
<!-- ✅ What and why -->
219+
[APM agent keys](https://www.elastic.co/guide/en/observability/current/apm-api-key.html) are
220+
used to authorize requests to an Elastic Observability endpoint.
221+
APM agent keys are revocable, you can have more than one of them, and
222+
you can add or remove them without restarting APM Server.
223+
224+
<!-- ✅ How do you authenticate using this method? -->
225+
To create and manage APM agent keys in Kibana:
226+
227+
1. Go to **APM Settings**.
228+
1. Select the **Agent Keys** tab.
229+
230+
When using an APM agent key, the `OTEL_EXPORTER_OTLP_HEADERS` is set using a
231+
different auth schema (`ApiKey` rather than `Bearer`). For example:
232+
233+
<!-- ✅ Code example -->
234+
```sh
235+
export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io
236+
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey TkpXUkx...dVZGQQ=="
237+
```
238+
239+
### Use a secret token
240+
241+
<!-- ✅ What is this -->
242+
<!-- ✅ Why use this -->
243+
[Secret tokens](https://www.elastic.co/guide/en/observability/current/apm-secret-token.html) are used to authorize requests to the APM Server. Both EDOT .NET and APM Server must be configured with the same secret token for the request to be accepted.
244+
245+
<!-- ✅ How do you authenticate using this method? -->
246+
You can find the values of these variables in Kibana's APM tutorial.
247+
In Kibana:
248+
249+
1. Go to **Setup guides**.
250+
1. Select **Observability**.
251+
1. Select **Monitor my application performance**.
252+
1. Scroll down and select the **OpenTelemetry** option.
253+
1. The appropriate values for `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` are shown there.
254+
255+
![Elastic Cloud OpenTelemetry configuration](images/elastic-cloud-opentelemetry-configuration.png)
256+
257+
For example:
258+
259+
```sh
260+
export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io
261+
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer P....l"
262+
```

0 commit comments

Comments
 (0)