From 159e27267fd77f2e1eaea367b08aa6792ef5049c Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Thu, 11 Jul 2024 16:34:01 -0500 Subject: [PATCH] structure initial outline --- docs/configure.asciidoc | 109 ++++++++++++++---- docs/get-started.asciidoc | 212 ++++++++++++++++++++++++----------- docs/intro.asciidoc | 68 ++++++----- docs/release-status.asciidoc | 9 ++ 4 files changed, 283 insertions(+), 115 deletions(-) create mode 100644 docs/release-status.asciidoc diff --git a/docs/configure.asciidoc b/docs/configure.asciidoc index f251881..130dee3 100644 --- a/docs/configure.asciidoc +++ b/docs/configure.asciidoc @@ -1,37 +1,64 @@ [[configure]] == Configure +:language: .NET +:language_lc: dotnet +:distro_name: Elastic Distribution for OpenTelemetry {language} + +include::release-status.asciidoc[] + +The {distro_name} ("the distro") offers a lot of flexibility... + +//// +How do users set configuration options? +//// +[discrete] +[[configure-methods]] +=== Configuration methods + 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 distro can be further configured using advanced settings when you need complete control of its behavior. -The Elastic Distribution for OpenTelemetry .NET 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. +You can set configuration options using a few different methods: + +* <> +* <> +* <> [discrete] [[configure-environment-variables]] -=== Environment variables +==== Environment variables -The Elastic Distribution for OpenTelemetry .NET can be configured using environment variables. This is a cross-platform -way to configure the Elastic Distribution for OpenTelemetry .NET and is especially useful in containerized environments. +// What and why +The distro can be configured using environment variables. +This is a cross-platform way to configure the distro and is especially useful in containerized environments. +// How 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 <>. +// Example + +// Order of operations Environment variables always take precedence over configuration provided by the `IConfiguration` system. [discrete] [[configure-iconfiguration-integration]] -=== IConfiguration integration +==== IConfiguration integration + +// What and why +In applications that use the "host" pattern, such as ASP.NET Core and worker service, the distro +can be configured using the `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 -`IConfiguration` instance to the `AddElasticOpenTelemetry` extension method on the `IServiceCollection`. +// How +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. +can be accessed via the `Configuration` property on the builder: [source,csharp] ---- @@ -44,6 +71,7 @@ By default, at this stage, the configuration will be populated from the default including the `appsettings.json` file(s) and command-line arguments. You may use these sources to define the configuration for the Elastic Distribution for OpenTelemetry .NET. +// Example For example, you can define the configuration for the Elastic Distribution for OpenTelemetry .NET in the `appsettings.json` file: [source,json] @@ -58,6 +86,7 @@ For example, you can define the configuration for the Elastic Distribution for O ---- <1> This example sets the file log directory to `C:\Logs` which enables diagnostic file logging. +// Order of operations Configuration from the "Elastic:OpenTelemetry" section of the `IConfiguration` instance will be bound to the `ElasticOpenTelemetryOptions` instance used to configure the Elastic distribution. @@ -66,13 +95,19 @@ https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration[Configu [discrete] [[configure-manual-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 -or an overload of the `AddElasticOpenTelemetry` extension method on the `IServiceCollection`. +// What and why +In all other scenarios, configuration can be achieved manually in code. -For example, in traditional console applications, you can configure the Elastic Distribution for OpenTelemetry .NET like this: +// How +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`. + +// Example +For example, in traditional console applications, you can configure the +Elastic Distribution for OpenTelemetry .NET like this: [source,csharp] ---- @@ -103,13 +138,43 @@ setting the corresponding property. <4> Pass the `ElasticOpenTelemetryBuilderOptions` instance to the `ElasticOpenTelemetryBuilder` constructor to configure the Elastic Distribution for OpenTelemetry .NET. +// Order of operations + +//// +What are the available configuration options? +//// [discrete] [[configure-configuration-options]] === Configuration options +//// +Is this true? Is the distro a wrapper around the OpenTelemetry .NET agent +which is a wrapper around the general OpenTelemetry SDK? 🌀 +//// +Because the {distro_name} ("the distro") is a wrapper around the https://github.com/open-telemetry/opentelemetry-{language_lc}-instrumentation[OpenTelemetry {language} agent], it supports both: + +* General OpenTelemetry SDK configuration options +* Elastic-specific configuration options that are only available when using the distro + +[discrete] +[[configure-otel-sdk-options]] +==== OpenTelemetry SDK configuration options + +//// +Is this true? Are there any options that aren't supported? +Any options that shouldn't be used? +//// +The distro supports all configuration options listed in the https://opentelemetry.io/docs/languages/sdk-configuration/general/[OpenTelemetry General SDK Configuration documentation]. + +[discrete] +[[configure-distro-options]] +==== Elastic-specific configuration options + +The distro supports the following custom options. + [discrete] [[configure-filelogdirectory]] -==== `FileLogDirectory` +===== `FileLogDirectory` A string specifying the directory where the Elastic Distribution for OpenTelemetry .NET 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 @@ -129,7 +194,7 @@ specified directory. [discrete] [[configure-fileloglevel]] -==== `FileLogLevel` +===== `FileLogLevel` Sets the logging level for the distribution. @@ -149,7 +214,7 @@ Valid options: `Critical`, `Error`, `Warning`, `Information`, `Debug`, `Trace` a [discrete] [[configure-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. @@ -168,7 +233,7 @@ an OTLP endpoint. This can be useful when you want to test applications without [discrete] [[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 for OpenTelemetry .NET opinionated defaults. @@ -199,3 +264,7 @@ Elastic defaults only for tracing and metrics, set this value to `Tracing,Metric | Default | Type | `string.Empty` | String |=== + +:!language: +:!language_lc: +:!distro_name: diff --git a/docs/get-started.asciidoc b/docs/get-started.asciidoc index c23f311..6c154ce 100644 --- a/docs/get-started.asciidoc +++ b/docs/get-started.asciidoc @@ -1,38 +1,46 @@ [[get-started]] == Get started -This page will show you how to get started with Elastic OpenTelemetry distribution for .NET. +:language: .NET +:language_lc: dotnet +:distro_name: Elastic Distribution for OpenTelemetry {language} -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. +include::release-status.asciidoc[] -.Alpha release -[WARNING] -==== -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, follow the steps below to get started. -==== +This guide shows you how to use the {distro_name} ("the distro") to instrument your {language} application and send OpenTelemetry data to an Elastic Observability deployment. +//// +What does a user need to know and/or do before they install the distro? +//// [discrete] [[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 -https://dotnet.microsoft.com/en-us/download/dotnet[.NET SDK version] installed locally. +Before getting started: + +// Familiarity with OpenTelemetry +* *Familiarize yourself with the OpenTelemetry SDK.* The distro 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 familiar with this, start with the https://opentelemetry.io/docs/languages/net[OpenTelemetry SDK documentation]. +// Any dependencies (including supported versions) +* *Check your .NET SDK version.* 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. + +//// +// Possible items to add: +// +// Elastic Observability deployment +// Other +//// +//// +How does a user install the distro? +//// [discrete] -[[get-started-installation]] -=== Installation +[[get-started-install]] +=== Install -To get started with the Elastic OpenTelemetry Distribution for .NET, you must add the `Elastic.OpenTelemetry` -NuGet package to your project. This can be achieved by adding the package reference to your project file. +//// +Step-by-step instructions +//// +To get started with the Elastic OpenTelemetry Distribution for .NET, add the `Elastic.OpenTelemetry` NuGet package reference to your project file: [source,xml] ---- @@ -40,70 +48,96 @@ NuGet package to your project. This can be achieved by adding the package refere ---- After adding the package reference, you can start using the Elastic OpenTelemetry Distribution for .NET -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 OpenTelemetry Distribution for .NET -references them. +in your application. + +//// +Any additional info related to installation +//// +[NOTE] +.The Elastic distro and the OpenTelemetry SDK +==== +The distro includes a transitive dependency on the OpenTelemetry SDK, so you do not _need_ to add the +OpenTelemetry SDK package to your project directly. However, you _can_ explicitly add the OpenTelemetry SDK as a dependency if you want to opt into newer SDK versions. If you do this, the OpenTelemetry SDK dependency must +be defined _before_ the Elastic OpenTelemetry Distribution for .NET is defined. +==== -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. +[NOTE] +.Migrating from the OpenTelemetry SDK to the Elastic distro +==== +The distro is designed to be easy to use and integrate into your applications. +This includes applications that 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. +switch to the opinionated configuration provided by the Elastic distro. +==== +//// +Are there any configuration options that are _required_? +What does the minimal configuration / set up look like? +What should they expect to see after setting up and running the distro? +How do they know it worked as expected? +//// [discrete] -[[get-started-asp.net core usage]] +[[get-started-asp-net-core-usage]] === ASP.NET Core usage -A common requirement is to instrument ASP.NET Core applications based on the `Microsoft.Extensions.Hosting` -libraries which provide dependency injection via an `IServiceProvider`. +It's common to want 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 for OpenTelemetry .NET provide extension methods to enable observability -features in your application by adding a few lines of code. +//// +I don't understand how this sentence relates to the paragraph before and after... -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]. +The OpenTelemetry SDK and the distro provide extension methods to enable observability +features in your application with a few lines of code. +//// + +If you want to instrument an ASP.NET Core minimal API application using the distro, follow the +steps below. Similar steps can also be used to instrument other ASP.NET Core workloads and other +host-based applications like 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. +The examples below assume your code uses 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 -NuGet package to your project: +[discrete] +[[get-started-asp-net-core-dependencies]] +==== Add dependencies +. To take advantage of the OpenTelemetry SDK instrumentation for ASP.NET Core, add the following +NuGet package to your project: ++ [source,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 Distribution for OpenTelemetry .NET. +The ASP.NET Core instrumentation is not included by default in the distro. 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: - +. Inside the `Program.cs` file of the ASP.NET Core application, add the following two using directives: ++ [source,csharp] ---- using OpenTelemetry; using OpenTelemetry.Trace; ---- ++ +The OpenTelemetry SDK provides extension methods on the `IServiceCollection` to enable the providers +and configure the SDK. The distro overrides the default OpenTelemetry SDK registration, adding several +opinionated defaults. -The OpenTelemetry SDK provides extension methods on the `IServiceCollection` to support enabling the -providers and configuring the SDK. The Elastic Distribution for OpenTelemetry .NET overrides the default SDK registration, -adding several opinionated defaults. - -In the minimal API template, the `WebApplicationBuilder` exposes a `Services` property that can be used +. 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. - +ensure that the OpenTelemetry SDK is registered: ++ [source,csharp] ---- var builder = WebApplication.CreateBuilder(args); @@ -117,12 +151,16 @@ builder.Services 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 -container. When available, the Elastic Distribution for OpenTelemetry .NET will override this to add opinionated defaults. +container. When available, the distro will override this to add opinionated defaults. <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 for OpenTelemetry .NET to collect traces and metrics, which are exported via -OTLP. +OpenTelemetry SDK and the distro to collect traces and metrics, which are exported via the +OpenTelemetry protocol (OTLP). + +[discrete] +[[get-started-asp-net-core-sample-endpoint]] +==== Add an endpoint To demonstrate the tracing capabilities, add a simple endpoint to the application: @@ -141,22 +179,64 @@ app.MapGet("/", async (IHttpClientFactory httpClientFactory) => ---- <1> Using this URL will require two redirects, allowing us to see multiple spans in the trace. -The Elastic Distribution for OpenTelemetry .NET 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 distro 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 -to view the configuration details that should be supplied to the application. +[discrete] +[[get-started-asp-net-core-environment-variables]] +==== Set environment variables +[NOTE] +==== +The steps below assume you are using an Elastic Cloud deployment as the destination +for your observability data. +==== + +//// +Step-by-step instructions +//// +To view the configuration details that should be supplied to the application: + +. In {kib}, go to *Setup guides*. +. Select *Observability*. +. Select *Monitor my application performance*. +. Scroll down and select the *OpenTelemetry* option. ++ image:images/elastic-cloud-opentelemetry-configuration.png[Elastic Cloud OpenTelemetry configuration] -Configure environment variables for the application either in `launchSettings.json` or in the environment +. 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. +[discrete] +[[get-started-asp-net-core-view-traces]] +==== View traces + +To view the traces, you can use the Elastic APM UI: + +//// +Step-by-step instructions +//// image:images/trace-sample-minimal-api.png[Minimal API request trace sample in the Elastic APM UI] + +//// +What should they do next? +//// +[discrete] +[[get-started-next-steps]] +=== Next steps + +//// +// Examples: +// +// See all configuration options +// Learn more about interpreting data +// Other +//// + +:!language: +:!language_lc: +:!distro_name: diff --git a/docs/intro.asciidoc b/docs/intro.asciidoc index 0d08cd7..abe7a73 100644 --- a/docs/intro.asciidoc +++ b/docs/intro.asciidoc @@ -1,35 +1,45 @@ [[intro]] -== Elastic OpenTelemetry Distribution for .NET +== Elastic Distribution for OpenTelemetry .NET ++++ Introduction ++++ -.Alpha release -[WARNING] -==== -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, see <>. -==== - -The `Elastic.OpenTelemetry` package contains an Elastic Distribution for OpenTelemetry .NET 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]. - -The Elastic Distribution for OpenTelemtry .NET 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 -signals. +:language: .NET +:language_lc: dotnet +:distro_name: Elastic Distribution for OpenTelemetry {language} + +include::release-status.asciidoc[] + +//// +Intro +//// +The {distro_name} ("the distro") is a {language} package that provides: + +* An easy way to instrument your application with OpenTelemetry. +* Configuration defaults for best usage. + +//// +What is it? +Why use it? +//// +A _distribution_ is a wrapper around an upstream OpenTelemetry repository with some customizations. The {distro_name} is a wrapper around the https://opentelemetry.io/docs/languages/{language_lc}[OpenTelemetry SDK for {language}] and includes the following customizations: + +* Uses Elastic-specific processors that ensure optimal compatibility when exporting OpenTelemetry signal data to an Elastic backend like Elastic APM server. +* Preconfigures the collection of tracing and metrics signals, applying some opinionated defaults, such as which sources are collected by default. +* Ensures that the OpenTelemetry protocol (OTLP) exporter is enabled by default. + +NOTE: For more details about OpenTelemetry distributions in general, visit the https://opentelemetry.io/docs/concepts/distributions[OpenTelemetry documentation]. + +//// +How to use it? +//// +Use the distro to start the OpenTelemetry SDK with your {language} application to automatically capture tracing data, performance metrics, and logs. Traces, metrics, and logs are sent to any OTLP collector you choose. + +Start with helpful defaults to begin collecting and exporting OpenTelemetry signals quickly. Then, further refine how you use the distro using extension methods that allow you to fully control the creation of the underlying tracer and metric providers. + +After you start sending data to Elastic, use an {observability-guide}/index.html[Elastic Observability] deployment -- hosted on Elastic Cloud or on-premises -- to monitor your applications, create alerts, and quickly identify root causes of service issues. + +:!language: +:!language_lc: +:!distro_name: diff --git a/docs/release-status.asciidoc b/docs/release-status.asciidoc new file mode 100644 index 0000000..4d99f5a --- /dev/null +++ b/docs/release-status.asciidoc @@ -0,0 +1,9 @@ +.Alpha release +[WARNING] +==== +The {distro_name} 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. + +We welcome your feedback! You can reach us by https://github.com/elastic/elastic-otel-{language_lc}/issues[opening a GitHub issue] or starting a discussion thread on the https://discuss.elastic.co/tags/c/observability/apm/58/{language_lc}[Elastic Discuss forum]. +====