From e0623adf34ecd9f9f491d48b94e956134abe8beb Mon Sep 17 00:00:00 2001 From: bmorelli25 Date: Mon, 17 Jun 2024 09:20:50 -0700 Subject: [PATCH 1/3] rename files befor conversion to preserve history --- .../{configuration.asciidoc => configure.mdx} | 32 +++++++++---------- docs/elastic-otel-dotnet.docnav.json | 17 ++++++++++ ...tting-started.asciidoc => get-started.mdx} | 0 docs/{intro.asciidoc => intro.mdx} | 0 4 files changed, 33 insertions(+), 16 deletions(-) rename docs/{configuration.asciidoc => configure.mdx} (91%) create mode 100644 docs/elastic-otel-dotnet.docnav.json rename docs/{getting-started.asciidoc => get-started.mdx} (100%) rename docs/{intro.asciidoc => intro.mdx} (100%) diff --git a/docs/configuration.asciidoc b/docs/configure.mdx similarity index 91% rename from docs/configuration.asciidoc rename to docs/configure.mdx index eff42f2..8a642b3 100644 --- a/docs/configuration.asciidoc +++ b/docs/configure.mdx @@ -1,10 +1,10 @@ [[configuration]] == Configuration -Configuration of the OpenTelemetry SDK should be performed through the +Configuration of the OpenTelemetry SDK should be performed through the mechanisms https://opentelemetry.io/docs/languages/net/automatic/configuration/[documented on the OpenTelemetry website]. -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. @@ -14,7 +14,7 @@ The Elastic distribution can be configured using environment variables. This is 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, +For details of the various options available and their corresponding environment variable names, see <>. Environment variables always take precedence over configuration provided by the `IConfiguration` @@ -22,7 +22,7 @@ system. === 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`. @@ -36,8 +36,8 @@ 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: @@ -54,16 +54,16 @@ For example, you can define the configuration for the Elastic distribution in th ---- <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 +To learn more about the Microsoft configuration system, see https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration[Configuration in ASP.NET Core]. === 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: @@ -94,7 +94,7 @@ await using var session = new ElasticOpenTelemetryBuilder(builderOptions) <4> <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 +<4> Pass the `ElasticOpenTelemetryBuilderOptions` instance to the `ElasticOpenTelemetryBuilder` constructor to configure the Elastic distribution. [[configuration-options]] @@ -104,7 +104,7 @@ to configure the Elastic distribution. [[config-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. @@ -146,7 +146,7 @@ Valid options: `Critical`, `Error`, `Warning`, `Information`, `Debug`, `Trace` a [[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"] @@ -166,7 +166,7 @@ an OTLP endpoint. This can be useful when you want to test applications without [[config-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`. @@ -178,10 +178,10 @@ 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"] diff --git a/docs/elastic-otel-dotnet.docnav.json b/docs/elastic-otel-dotnet.docnav.json new file mode 100644 index 0000000..89444fe --- /dev/null +++ b/docs/elastic-otel-dotnet.docnav.json @@ -0,0 +1,17 @@ +{ + "mission": ".NET", + "id": "elastic-otel-dotnet", + "landingPageId": "otelDotNetInto", + "icon": "faceHappy", + "description": "Elastic OpenTelemetry Distribution for .NET", + "items": [ + { + "label": "Get started", + "pageId": "otelDotNetGetStarted" + }, + { + "label": "Configure", + "pageId": "otelDotNetConfigure" + } + ] +} \ No newline at end of file diff --git a/docs/getting-started.asciidoc b/docs/get-started.mdx similarity index 100% rename from docs/getting-started.asciidoc rename to docs/get-started.mdx diff --git a/docs/intro.asciidoc b/docs/intro.mdx similarity index 100% rename from docs/intro.asciidoc rename to docs/intro.mdx From a433c5e4b864d1082e6cf688371ade498966276a Mon Sep 17 00:00:00 2001 From: bmorelli25 Date: Mon, 17 Jun 2024 10:01:49 -0700 Subject: [PATCH 2/3] test build --- docs/configure.mdx | 144 ++++++++++++++++---------------------- docs/get-started.mdx | 163 +++++++++++++++++++++---------------------- docs/index.asciidoc | 10 --- docs/intro.mdx | 42 +++++++---- 4 files changed, 165 insertions(+), 194 deletions(-) delete mode 100644 docs/index.asciidoc diff --git a/docs/configure.mdx b/docs/configure.mdx index 8a642b3..9439f64 100644 --- a/docs/configure.mdx +++ b/docs/configure.mdx @@ -1,26 +1,29 @@ -[[configuration]] -== Configuration +--- +id: otelDotNetConfigure +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]. +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 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 <>. +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 distribution can be configured using the `IConfiguration` integration. This is done by passing an @@ -29,12 +32,11 @@ distribution can be configured using the `IConfiguration` integration. This is d 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 @@ -42,25 +44,24 @@ 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 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]. +[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 @@ -68,8 +69,7 @@ or an overload of the `AddElasticOpenTelemetry` extension method on the `IServic 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; @@ -78,93 +78,71 @@ 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. 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 | - -[float] -[[config-skipotlpexporter]] -==== `SkipOtlpExporter` +### `SkipOtlpExporter` 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 only some of the Elastic distribution opinionated defaults. @@ -184,14 +162,10 @@ as required. 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 -|============ \ No newline at end of file +| Environment variable name | IConfiguration key | +| ------------- |-------------| +| `ELASTIC_OTEL_ENABLE_ELASTIC_DEFAULTS` | `Elastic:OpenTelemetry:EnabledElasticDefaults` | + +| Default | Type | +| ------------- |-------------| +| `string.Empty` | String | \ No newline at end of file diff --git a/docs/get-started.mdx b/docs/get-started.mdx index 56dd08c..48a7618 100644 --- a/docs/get-started.mdx +++ b/docs/get-started.mdx @@ -1,155 +1,150 @@ -[[getting-started]] -== Getting started +--- +id: otelDotNetGetStarted +slug: /otel-dotnet/get-started +title: Get started +--- -This page will show you how to get started with Elastic OpenTelemetry distribution for .NET. +This page will show you how to get started with Elastic OpenTelemetry distribution for .NET. -As the distribution is a lightweight wrapper around the OpenTelemetry SDK, you should be broadly +As the distribution is a lightweight wrapper around the OpenTelemetry SDK, you should be broadly familiar with the OpenTelemetry SDK concepts and instrumenting applications using the Microsoft -diagnostic APIs. If you are not, we recommend you read the -https://opentelemetry.io/docs/languages/net[OpenTelemetry SDK documentation] first. +diagnostic APIs. If you are not, we recommend you read the +[OpenTelemetry SDK documentation](https://opentelemetry.io/docs/languages/net) first. -[IMPORTANT] --- -The Elastic distribution is currently in early alpha release status. It is not yet feature -complete and may contain bugs. We are actively working on improving the distribution and -adding new features. + + This project is not yet recommended for production use. + Functionality may be changed or removed in future releases. + Alpha releases are not subject to the support SLA of official GA features. -If you would like to experience the alpha and help us improve the distribution by providing -early feedback, you can follow the steps below to get started. --- + If you would like to experience the alpha and help us improve the distribution by providing + early feedback, follow the steps below to get started. + -=== Prerequisites +## Prerequisites -The current documentation and examples are written with .NET 6 and newer applications in mind. -Before continuing, ensure that you have a supported +The current documentation and examples are written with .NET 6 and newer applications in mind. +Before continuing, ensure that you have a supported https://dotnet.microsoft.com/en-us/download/dotnet[.NET SDK version] installed locally. -=== Installation +## Installation -To get started with the Elastic OpenTelemetry distribution, you must add the Elastic OpenTelemetry +To get started with the Elastic OpenTelemetry distribution, you must add the Elastic OpenTelemetry NuGet package to your project. This can be achieved by adding the package reference to your project file. -[source,xml] ----- +```xml ----- +``` -After adding the package reference, you can start using the Elastic OpenTelemetry distribution -in your application. The distribution includes a transitive dependency on the OpenTelemetry SDK, -so you do not need to add the OpenTelemetry SDK package to your project, although doing so will -cause no harm and may be used to opt into newer SDK versions before the Elastic distribution +After adding the package reference, you can start using the Elastic OpenTelemetry distribution +in your application. The distribution includes a transitive dependency on the OpenTelemetry SDK, +so you do not need to add the OpenTelemetry SDK package to your project, although doing so will +cause no harm and may be used to opt into newer SDK versions before the Elastic distribution references them. -The Elastic OpenTelemetry distribution is designed to be easy to use and integrate into your -applications. This includes applications which have previously used the OpenTelemetry SDK directly. -In situations where the OpenTelemetry SDK is already used, the only required change is -to add the `Elastic.OpenTelemetry` NuGet package to the project. Doing so will automatically +The Elastic OpenTelemetry distribution is designed to be easy to use and integrate into your +applications. This includes applications which have previously used the OpenTelemetry SDK directly. +In situations where the OpenTelemetry SDK is already used, the only required change is +to add the `Elastic.OpenTelemetry` NuGet package to the project. Doing so will automatically switch to the opinionated configuration provided by the Elastic distribution. -=== ASP.NET Core usage +## ASP.NET Core usage -A common requirement is to instrument ASP.NET Core applications based on the `Microsoft.Extensions.Hosting` +A common requirement is to instrument ASP.NET Core applications based on the `Microsoft.Extensions.Hosting` libraries which provide dependency injection via an `IServiceProvider`. -The OpenTelemetry SDK and the Elastic distribution provide extension methods to enable observability +The OpenTelemetry SDK and the Elastic distribution provide extension methods to enable observability features in your application by adding a few lines of code. -In this section, we'll focus on instrumenting an ASP.NET Core minimal API application using the Elastic -OpenTelemetry distribution. Similar steps can also be used to instrument other ASP.NET Core workloads +In this section, we'll focus on instrumenting an ASP.NET Core minimal API application using the Elastic +OpenTelemetry distribution. Similar steps can also be used to instrument other ASP.NET Core workloads and other host-based applications such as https://learn.microsoft.com/en-us/dotnet/core/extensions/workers[worker services]. -[NOTE] --- -These examples assume the use of the top-level statements feature introduced in C# 9.0 and the -default choice for applications created using the latest templates. --- + + These examples assume the use of the top-level statements feature introduced in C# 9.0 and the + default choice for applications created using the latest templates. + -To take advantage of the OpenTelemetry SDK instrumentation for ASP.NET Core, add the following +To take advantage of the OpenTelemetry SDK instrumentation for ASP.NET Core, add the following NuGet package to your project: -[source,xml] ----- +```xml ----- +``` This package includes instrumentation to collect traces for requests handled by ASP.NET Core endpoints. -[NOTE] --- -The ASP.NET Core instrumentation is not included by default in the Elastic OpenTelemetry distribution. -As with all optional instrumentation libraries, you can choose to include them in your application by -adding a suitable package reference. --- + + The ASP.NET Core instrumentation is not included by default in the Elastic OpenTelemetry distribution. + As with all optional instrumentation libraries, you can choose to include them in your application by + adding a suitable package reference. + Inside the `Program.cs` file of the ASP.NET Core application, add the following two using directives: -[source,csharp] ----- +```csharp using OpenTelemetry; using OpenTelemetry.Trace; ----- +``` -The OpenTelemetry SDK provides extension methods on the `IServiceCollection` to support enabling the -providers and configuring the SDK. The Elastic distribution overrides the default SDK registration, +The OpenTelemetry SDK provides extension methods on the `IServiceCollection` to support enabling the +providers and configuring the SDK. The Elastic distribution overrides the default SDK registration, adding several opinionated defaults. -In the minimal API template, the `WebApplicationBuilder` exposes a `Services` property that can be used -to register services with the dependency injection container. To enable tracing and metrics collection, +In the minimal API template, the `WebApplicationBuilder` exposes a `Services` property that can be used +to register services with the dependency injection container. To enable tracing and metrics collection, ensure that the OpenTelemetry SDK is registered. -[source,csharp] ----- +```csharp var builder = WebApplication.CreateBuilder(args); builder.Services - .AddHttpClient() <1> - .AddOpenTelemetry() <2> - .WithTracing(t => t.AddAspNetCoreInstrumentation()); <3> ----- -<1> The `AddHttpClient` method registers the `IHttpClientFactory` service with the dependency -injection container. This is NOT required to enable OpenTelemetry, but the example endpoint will use it to + .AddHttpClient() [^1] + .AddOpenTelemetry() [^2] + .WithTracing(t => t.AddAspNetCoreInstrumentation()); [^3] +``` +[^1]: The `AddHttpClient` method registers the `IHttpClientFactory` service with the dependency +injection container. This is NOT required to enable OpenTelemetry, but the example endpoint will use it to send an HTTP request. -<2> The `AddOpenTelemetry` method registers the OpenTelemetry SDK with the dependency injection +[^2]: The `AddOpenTelemetry` method registers the OpenTelemetry SDK with the dependency injection container. When available, the Elastic distribution will override this to add opinionated defaults. -<3> Configure tracing to instrument requests handled by ASP.NET Core. +[^3]: Configure tracing to instrument requests handled by ASP.NET Core. -With these limited changes to the `Program.cs` file, the application is now configured to use the -OpenTelemetry SDK and the Elastic distribution to collect traces and metrics, which are exported via +With these limited changes to the `Program.cs` file, the application is now configured to use the +OpenTelemetry SDK and the Elastic distribution to collect traces and metrics, which are exported via OTLP. To demonstrate the tracing capabilities, add a simple endpoint to the application: -[source,csharp] ----- +```csharp app.MapGet("/", async (IHttpClientFactory httpClientFactory) => { using var client = httpClientFactory.CreateClient(); await Task.Delay(100); - var response = await client.GetAsync("http://elastic.co"); <1> + var response = await client.GetAsync("http://elastic.co"); [^1] await Task.Delay(50); return response.StatusCode == System.Net.HttpStatusCode.OK ? Results.Ok() : Results.StatusCode(500); }); ----- -<1> Using this URL will require two redirects, allowing us to see multiple spans in the trace. +``` +[^1]: Using this URL will require two redirects, allowing us to see multiple spans in the trace. -The Elastic distribution will automatically enable the exporting of signals via the OTLP exporter. This -exporter requires that endpoint(s) are configured. A common mechanism for configuring endpoints is -via environment variables. +The Elastic distribution will automatically enable the exporting of signals via the OTLP exporter. This +exporter requires that endpoint(s) are configured. A common mechanism for configuring endpoints is +via environment variables. -This demo uses an Elastic Cloud deployment as the destination for our observability data. From Kibana -running in Elastic Cloud, navigate to the observability set up guides. Select the OpenTelemetry option +This demo uses an Elastic Cloud deployment as the destination for our observability data. From Kibana +running in Elastic Cloud, navigate to the observability set up guides. Select the OpenTelemetry option to view the configuration details that should be supplied to the application. -image::./images/elastic-cloud-opentelemetry-configuration.png[Elastic Cloud OpenTelemetry configuration] +![Elastic Cloud OpenTelemetry configuration](./images/elastic-cloud-opentelemetry-configuration.png) -Configure environment variables for the application either in `launchSettings.json` or in the environment -where the application is running. +Configure environment variables for the application either in `launchSettings.json` or in the environment +where the application is running. -Once configured, run the application and make a request to the root endpoint. A trace will be generated +Once configured, run the application and make a request to the root endpoint. A trace will be generated and exported to the OTLP endpoint. To view the traces, you can use the Elastic APM UI. -image::./images/trace-sample-minimal-api.png[Minimal API request trace sample in the Elastic APM UI] \ No newline at end of file +![Minimal API request trace sample in the Elastic APM UI](./images/trace-sample-minimal-api.png) \ No newline at end of file diff --git a/docs/index.asciidoc b/docs/index.asciidoc deleted file mode 100644 index fb5e068..0000000 --- a/docs/index.asciidoc +++ /dev/null @@ -1,10 +0,0 @@ -include::{asciidoc-dir}/../../shared/versions/stack/current.asciidoc[] -include::{asciidoc-dir}/../../shared/attributes.asciidoc[] - -= Elastic OpenTelemetry Distribution - -include::./intro.asciidoc[] - -include::./getting-started.asciidoc[] - -include::./configuration.asciidoc[] \ No newline at end of file diff --git a/docs/intro.mdx b/docs/intro.mdx index d799551..19dd7bc 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -1,20 +1,32 @@ -[[introduction]] -== Introduction +--- +id: otelDotNetIntro +slug: /otel-dotnet/intro +title: Elastic OpenTelemetry Distribution for .NET +--- -The `Elastic.OpenTelemetry` package contains an Elastic distribution of the -https://opentelemetry.io/docs/languages/net[OpenTelemetry SDK for .NET]. A distribution -is a wrapper around an upstream OpenTelemetry repository with some customizations. For -more details about distributions in general, visit the -https://opentelemetry.io/docs/concepts/distributions[OpenTelemetry documentation]. + + This project is not yet recommended for production use. + Functionality may be changed or removed in future releases. + Alpha releases are not subject to the support SLA of official GA features. -The Elastic distribution includes some Elastic-specific processors to ensure the best -compatibility when exporting OpenTelemetry signal data to an Elastic backend such -as Elastic APM server. The distribution also preconfigures the collection of tracing -and metrics signals, applying some opinionated defaults, such as which sources are -collected by default. The distribution also ensures that the OTLP exporter is enabled + If you would like to experience the alpha and help us improve the distribution by providing + early feedback, see [get started](get-started). + + +The `Elastic.OpenTelemetry` package contains an Elastic distribution of the +[OpenTelemetry SDK for .NET](https://opentelemetry.io/docs/languages/net). A distribution +is a wrapper around an upstream OpenTelemetry repository with some customizations. For +more details about distributions in general, visit the +[OpenTelemetry documentation](https://opentelemetry.io/docs/concepts/distributions). + +The Elastic distribution includes some Elastic-specific processors to ensure the best +compatibility when exporting OpenTelemetry signal data to an Elastic backend such +as Elastic APM server. The distribution also preconfigures the collection of tracing +and metrics signals, applying some opinionated defaults, such as which sources are +collected by default. The distribution also ensures that the OTLP exporter is enabled by default. -The distribution includes extension methods to fully control the creation of the -underlying tracer and metric providers, providing a helpful set of defaults -to get developers up and running quickly with collecting and exporting OpenTelemetry +The distribution includes extension methods to fully control the creation of the +underlying tracer and metric providers, providing a helpful set of defaults +to get developers up and running quickly with collecting and exporting OpenTelemetry signals. \ No newline at end of file From 783b01e1a987ba695f91fc9a5fc31570bdd5d9a8 Mon Sep 17 00:00:00 2001 From: bmorelli25 Date: Mon, 17 Jun 2024 10:24:42 -0700 Subject: [PATCH 3/3] update for docsmobile 2.0.0 --- docs/configure.mdx | 1 - docs/elastic-otel-dotnet.docnav.json | 8 ++++---- docs/get-started.mdx | 1 - docs/intro.mdx | 1 - 4 files changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/configure.mdx b/docs/configure.mdx index 9439f64..c1486d6 100644 --- a/docs/configure.mdx +++ b/docs/configure.mdx @@ -1,5 +1,4 @@ --- -id: otelDotNetConfigure slug: /otel-dotnet/configure title: Configure --- diff --git a/docs/elastic-otel-dotnet.docnav.json b/docs/elastic-otel-dotnet.docnav.json index 89444fe..8a15006 100644 --- a/docs/elastic-otel-dotnet.docnav.json +++ b/docs/elastic-otel-dotnet.docnav.json @@ -1,17 +1,17 @@ { "mission": ".NET", "id": "elastic-otel-dotnet", - "landingPageId": "otelDotNetInto", - "icon": "faceHappy", + "landingPageSlug": "/otel-dotnet/intro", + "icon": "logoObservability", "description": "Elastic OpenTelemetry Distribution for .NET", "items": [ { "label": "Get started", - "pageId": "otelDotNetGetStarted" + "slug": "/otel-dotnet/get-started" }, { "label": "Configure", - "pageId": "otelDotNetConfigure" + "slug": "/otel-dotnet/configure" } ] } \ No newline at end of file diff --git a/docs/get-started.mdx b/docs/get-started.mdx index 48a7618..260b1dd 100644 --- a/docs/get-started.mdx +++ b/docs/get-started.mdx @@ -1,5 +1,4 @@ --- -id: otelDotNetGetStarted slug: /otel-dotnet/get-started title: Get started --- diff --git a/docs/intro.mdx b/docs/intro.mdx index 19dd7bc..bd120ae 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -1,5 +1,4 @@ --- -id: otelDotNetIntro slug: /otel-dotnet/intro title: Elastic OpenTelemetry Distribution for .NET ---