Set up the EDOT .NET SDK

Elastic Stack Serverless Observability

Learn how to set up and configure the Elastic Distribution of OpenTelemetry .NET to instrument your application or service.

EDOT .NET is designed to be straightforward to integrate into your applications. Integration includes applications that have previously used the OpenTelemetry SDK, those that are transitioning from the Elastic APM Agent and those introducing observability instrumentation for the first time. When the OpenTelemetry SDK or Elastic APM Agent are already in use, minor code changes are required at the point of registration. Refer to Migration for more details.

This quickstart guide documents the introductory steps required to set up OpenTelemetry using EDOT .NET for an ASP.NET Core minimal API application. For detailed, technology-specific steps, see:

• ASP.NET (.NET Framework)
• Console applications
• Worker services
• Zero code

Before getting started:

• Check your .NET SDK version. Before continuing, install a locally supported .NET SDK version.
• Create a new ASP.NET Core minimal API project. You need an application to instrument with OpenTelemetry. This quickstart guide uses an ASP.NET Core minimal API project. You can follow along with a new or existing ASP.NET Core application. Refer to the technology-specific documentation for guidance with specific .NET application templates.
• Set up Elastic Observability. You need somewhere to send the gathered OpenTelemetry data so that it can be viewed and analyzed. This documentation assumes you're using Elastic Cloud with an Elastic Observability hosted deployment or serverless project. You can use an existing one or set up a new one.

To get started with the Elastic Distribution of OpenTelemetry .NET, add the Elastic.OpenTelemetry NuGet package reference to your project file:

<PackageReference Include="Elastic.OpenTelemetry" Version="<LATEST>" />

EDOT .NET 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.

To observe and capture the built-in ASP.NET Core instrumentation, the OpenTelemetry instrumentation for ASP.NET Core NuGet package is required. Due to its dependencies, this package is not automatically available when adding Elastic.OpenTelemetry to your project.

Manually add the latest version to your project file:

<PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="<LATEST>" />

The presence of this package is detected by the EDOT instrumentation assembly scanning feature (turned on by default).

To register the OpenTelemetry SDK via EDOT .NET, the recommended approach is to use the extension method available on IHostApplicationBuilder. IHostApplicationBuilder is the abstraction representing the .NET generic host responsible for managing application startup and lifetime in ASP.NET Core.

var builder = WebApplication.CreateBuilder(args);
builder.AddElasticOpenTelemetry();

Immediately after creating the WebApplicationBuilder, which implements IHostApplicationBuilder, call the AddElasticOpenTelemetry method. AddElasticOpenTelemetry registers the OpenTelemetry SDK for .NET, applying the Elastic opinionated defaults. The Elastic defaults enable tracing, metrics, log signals, and the OTLP exporter.

Additionally, EDOT performs automatic instrumentation assembly scanning to enable the ASP.NET Core instrumentation that we added in the previous step. With the upstream SDK, additional lines of code would be required to register the instrumentation. EDOT .NET aims to simplify the experience of getting started.

When exporting telemetry data from an application, resource attributes are used to represent metadata about the entity producing the telemetry. While defaults are applied for required attributes such as service.name. Explicitly set a descriptive service name to distinguish its data in the Elastic Observability UI.

The OpenTelemetry SDK supports several mechanisms to configure resource attributes. For simple scenarios, the service information can be set programmatically. To achieve this when using EDOT, the AddElasticOpenTelemetry method includes an overload accepting an Action<IOpenTelemetryBuilder> used to configure the OpenTelemetry SDK through its builder API.

To specify a service name, we can amend the preceding code as follows:

builder.AddElasticOpenTelemetry(b => b
  .ConfigureResource(r => r.AddService("MyAppName")));

The preceding code requires two additional using directives:

using OpenTelemetry;
using OpenTelemetry.Resources;

Alternatively, the OTEL_SERVICE_NAME environment variable can be used to configure the service name. There are two ways to specify this with the OpenTelemetry SDK. Either, as a traditional environment variable, configured before launching the process, or as an entry in the .NET configuration APIs. These APIs are available and used by default in generic host applications such as ASP.NET Core.

To use IConfiguration to specify the service name, create an entry for the key OTEL_SERVICE_NAME, with the value representing your preferred service name. Configuring this entry can be achieved through any of the available .NET configuration providers, for example, by creating a configuration entry in the appsettings.json file:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "OTEL_SERVICE_NAME": "MyNameFromConfig"
}

OpenTelemetry configuration environment variables should be specified as a top-level key/value pair as with the OTEL_SERVICE_NAME in the preceding code snippet.

The configuration documented so far ensures that when the application starts, the OpenTelemetry SDK is launched with the EDOT .NET defaults, activating all signals and exporting telemetry through OTLP. Unless configured otherwise, the OTLP exporter in the SDK defaults to sending data to localhost on the default port for OTLP over gRPC, 4317. If you are running a local Collector, this might be sufficient, but in most cases you will need to configure the correct endpoint for exporting telemetry data.

In this quickstart guide, Elastic Cloud Serverless is the backend. The onboarding Add data page of Elastic Observability provides the environment variables required to send telemetry data to the Elastic Observability backend. This information includes the endpoint URL and API key that should be used when exporting data. The application must be configured to use the endpoint and authorization header when exporting telemetry data.

As with most OpenTelemetry configuration, you can also configure the endpoint through environment variables, including providing them through application configuration. The values are sensitive and should be secured. Use the Secret Manager feature during local development. Once enabled for your application, add OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS as keys with their respective values.

EDOT .NET enables the collection of trace, metric, and log signals by default. With no additional configuration, your configured Elastic Observability backend will receive telemetry data from your application at runtime. Development teams are encouraged to enrich the value of telemetry by instrumenting their code to emit application-specific telemetry data such as traces, metrics, and logs.

In .NET, use the built-in .NET APIs for each signal:

• Logs
• Traces
• Metrics

Refer to the technology-specific documentation pages for further details on using EDOT .NET in those application types. The OpenTelemetry SDK documentation provides more examples of working with the .NET SDK.