diff --git a/README.md b/README.md index bceeb58..6ffdb9e 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ > > We welcome your feedback! You can reach us by [opening a GitHub issue](https://github.com/elastic/elastic-otel-dotnet/issues) or starting a discussion thread on the [Elastic Discuss forum](https://discuss.elastic.co/tags/c/observability/apm/58/dotnet). -The Elastic Distribution of OpenTelemetry .NET (EDOT .NET) provides a zero code change extension of the [OpenTelemetry SDK for .NET](https://opentelemetry.io/docs/languages/net). EDOT .NET makes it easier to get started using OpenTelemetry in your .NET applications through strictly OpenTelemetry native means, while also providing a smooth and rich out of the box experience with [Elastic Observability](https://www.elastic.co/observability). It's an explicit goal of this distribution to introduce **no new concepts** in addition to those defined by the wider OpenTelemetry community. +The Elastic Distribution of OpenTelemetry .NET (EDOT .NET) provides a lightly customized version of the [OpenTelemetry SDK for .NET](https://opentelemetry.io/docs/languages/net). EDOT .NET makes it easier to get started using OpenTelemetry in your .NET applications through strictly OpenTelemetry native means, while also providing a smooth and rich out of the box experience with [Elastic Observability](https://www.elastic.co/observability). It's an explicit goal of this distribution to introduce **no new concepts** in addition to those defined by the wider OpenTelemetry community. > [!NOTE] > For more details about OpenTelemetry distributions in general, visit the [OpenTelemetry documentation](https://opentelemetry.io/docs/concepts/distributions). @@ -39,6 +39,39 @@ NuGet package to your project. This can be achieved by adding the package refere * [Get started](./docs/get-started.md) * [Configuration](./docs/configure.md) +## Features + +Several instrumentations are enabled by default. These improve the getted started experience, providing meaningful traces +out of the box, with less configuration required. + +### Tracing defaults + +When using the Elastic Distribution of OpenTelemetry .NET, several common, zero dependency tracing instrumentations are enabled by default: + +* [`OpenTelemetry.Instrumentation.Http`](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Http) +* [`OpenTelemetry.Instrumentation.GrpcNetClient`](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.GrpcNetClient) +* [`OpenTelemetry.Instrumentation.EntityFrameworkCore`](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.EntityFrameworkCore) +* [`OpenTelemetry.Instrumentation.SqlClient`](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.SqlClient) +* [`OpenTelemetry.Instrumentation.ElasticsearchClient`](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.ElasticsearchClient) + +> [!NOTE] +> When using auto-instrumentation, `OpenTelemetry.Instrumentation.ElasticsearchClient` is not enabled by default. + +Additionally, traces from `Elastic.Transport`, used by several Elastic libraries, +including [`Elastic.Clients.Elasticsearch`](https://www.nuget.org/packages/Elastic.Clients.Elasticsearch) +are observed. + +### Metrics defaults + +When using the Elastic Distribution of OpenTelemetry .NET, several common, zero dependency meters are enabled by default: + +* [`OpenTelemetry.Instrumentation.Runtime`](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Runtime) +* [`OpenTelemetry.Instrumentation.Process`](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Process) + +### Exporter defaults + +When using the Elastic Distribution of OpenTelemetry .NET, OTLP exporters are enabled for all signals. + ## Instrument your application The OpenTelemetry SDK and EDOT .NET provide extension methods to enable observability features in your application with a few lines of code. Choose from: -* [**ASP.NET Core application**](#aspnet-core-application) for ASP.NET Core minimal API applications, other ASP.NET Core workloads and other host-based applications like [worker services](https://learn.microsoft.com/en-us/dotnet/core/extensions/workers). -* [**`Microsoft.Extensions.Hosting`**](#microsoftextensionshosting) for console applications and services that are written against a builder that exposes an `IServiceCollection`. -* [**Manual instrumentation**](#manual-instrumentation) for environments where an `IServiceCollection` is unavailable. +* [**ASP.NET Core application**](#aspnet-core-application) for ASP.NET Core minimal API applications, MVC applications and other ASP.NET Core workloads. +* [**Microsoft.Extensions.Hosting**](#microsoftextensionshosting) for console applications and services that are written against a builder that exposes an `IServiceCollection` like [worker services](https://learn.microsoft.com/en-us/dotnet/core/extensions/workers). +* [**Manual builder**](#manual-builder) for environments where an `IServiceCollection` is unavailable. ### ASP.NET Core application If you want to instrument an ASP.NET Core minimal API application using EDOT .NET, follow the -steps below. Similar steps can also be used to instrument other ASP.NET Core workloads and other -host-based applications like [worker services](https://learn.microsoft.com/en-us/dotnet/core/extensions/workers). +steps below. Similar steps can also be used to instrument other ASP.NET Core workloads. > [!NOTE] -> 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. +> The examples below assume your code uses the top-level statements feature introduced in C# 9.0. This is the default choice for applications created using the latest templates. 1. To take advantage of the OpenTelemetry SDK instrumentation for ASP.NET Core, add the following NuGet package to your project: @@ -111,10 +110,9 @@ host-based applications like [worker services](https://learn.microsoft.com/en-us // the dependency injection container. This is NOT required to enable OpenTelemetry, // but the example endpoint will use it to send an HTTP request. .AddHttpClient() - // The `AddOpenTelemetry` method registers the OpenTelemetry SDK with the - // dependency injection container. When available, EDOT .NET will override - // this to add opinionated defaults. - .AddOpenTelemetry() + // The `AddElasticOpenTelemetry` method registers the OpenTelemetry SDK with the + // dependency injection container, adding Elastic opinionated defaults and processors. + .AddElasticOpenTelemetry() // Configure tracing to instrument requests handled by ASP.NET Core. .WithTracing(t => t.AddAspNetCoreInstrumentation()); ``` @@ -144,10 +142,11 @@ EDOT .NET will automatically enable the exporting of signals via the OTLP export exporter requires that endpoint(s) are configured. A common mechanism for configuring endpoints is via environment variables. -### `Microsoft.Extensions.Hosting` +### Microsoft.Extensions.Hosting -For console applications, services, etc that are written against a builder that exposes an `IServiceCollection` you can install this package: +For console applications, services, etc. that are written against a host builder that exposes an `IServiceCollection`, such as +[worker services](https://learn.microsoft.com/en-us/dotnet/core/extensions/workers) you can install this package: ```xml @@ -156,18 +155,19 @@ For console applications, services, etc that are written against a builder that > [!NOTE] > Replace the `` placeholder with the latest available package from [NuGet.org](https://www.nuget.org/packages/Elastic.OpenTelemetry). -Ensure you call `AddOpenTelemetry` to enable OpenTelemetry just as you would when using OpenTelemetry directly. Our package intercepts this call to set up our defaults, but can be further build upon as per usual: +Ensure you call `AddElasticOpenTelemetry` to enable OpenTelemetry (instead of `AddOpenTelemetry` when using the OpenTelemetry SDK). The Elastic +extension method sets up our defaults, but can be further built upon as per usual: ```csharp var builder = Host.CreateApplicationBuilder(args); -builder.Services.AddOpenTelemetry() +builder.Services.AddElasticOpenTelemetry() .ConfigureResource(r => r.AddService(serviceName: "MyService")) .WithTracing(t => t.AddSource(Worker.ActivitySourceName).AddConsoleExporter()) .WithMetrics(m => m.AddMeter(Worker.MeterName).AddConsoleExporter()); ``` -### Manual instrumentation +### Manual builder In environments where an `IServiceCollection` is unavailable you may manually start instrumenting by creating an instance of `ElasticOpenTelemetryBuilder`. @@ -180,7 +180,7 @@ await using var session = new ElasticOpenTelemetryBuilder() This will setup instrumentation for as long as `session` is not disposed. We would generally expect the `session` to live for the life of the application. -`ElasticOpenTelemetryBuilder` is an implementation of [`IOpenTelemetryBuilder`](https://github.com/open-telemetry/opentelemetry-dotnet/blob/70657395b82ba00b8a1e848e8832b77dff94b6d2/src/OpenTelemetry.Api.ProviderBuilderExtensions/IOpenTelemetryBuilder.cs#L12). +`ElasticOpenTelemetryBuilder` is an implementation of [`IOpenTelemetryBuilder`](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry.Api.ProviderBuilderExtensions/IOpenTelemetryBuilder.cs). This is important to know because any instrumentation configuration is automatically exposed by the base OpenTelemetry package as extension methods on `IOpenTelemetryBuilder`. You will not lose functionality by