Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@stevejgordon
stevejgordon committed Feb 11, 2025
1 parent f707563 commit 324c7f5
Show file tree
Hide file tree
Showing 2 changed files with 53 additions and 20 deletions.
35 changes: 34 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down Expand Up @@ -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.

<!-- ## Getting started
As EDOT .NET is a lightweight extension of the OpenTelemetry SDK, you should be broadly
Expand Down
38 changes: 19 additions & 19 deletions docs/get-started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ This guide shows you how to use the Elastic Distribution of OpenTelemetry .NET (

**Already familiar with OpenTelemetry?** It's an explicit goal of this distribution to introduce _no new concepts_ outside those defined by the wider OpenTelemetry community.

**New to OpenTelemetry?** This section will guide you through the _minimal_ configuration options to get EDOT Java set up in your application. You do _not_ need any existing experience with OpenTelemetry to set up EDOT Java initially. If you need more control over your configuration after getting set up, you can learn more in the [OpenTelemetry documentation](https://opentelemetry.io/docs/languages/net).
**New to OpenTelemetry?** This section will guide you through the _minimal_ configuration options to get EDOT Java set up in your application. You do _not_ need any existing experience with OpenTelemetry to set up EDOT .NET initially. If you need more control over your configuration after getting set up, you can learn more in the [OpenTelemetry documentation](https://opentelemetry.io/docs/languages/net).

> [!NOTE]
> As an OpenTelemetry SDK, EDOT .NET supports sending data to any OpenTelemetry protocol (OTLP) endpoint ([OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)), but this guide assumes you are sending data to Elastic.
Expand All @@ -29,7 +29,7 @@ This guide shows you how to use the Elastic Distribution of OpenTelemetry .NET (

Before getting started:

* **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 [.NET SDK version](https://dotnet.microsoft.com/en-us/download/dotnet) installed locally.
* **Check your .NET SDK version**. The current documentation and examples are written with .NET 8 and newer applications in mind. Before continuing, ensure that you have a supported [.NET SDK version](https://dotnet.microsoft.com/en-us/download/dotnet) installed locally.
* **Set up Elastic Observability**. You'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. This doc assumes you're using an [Elastic Observability](https://www.elastic.co/observability) cloud deployment. You can use an existing one or set up a new one.
<details>
<summary><strong>Expand for setup instructions</strong></summary>
Expand Down Expand Up @@ -61,25 +61,24 @@ After adding the package reference, you can start using EDOT .NET in your applic
> 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. If you do this, the OpenTelemetry SDK dependency must be defined _before_ the Elastic OpenTelemetry Distribution for .NET is defined.
> [!NOTE]
> EDOT .NET 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 EDOT .NET.
> EDOT .NET 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 changes are to add the `Elastic.OpenTelemetry` NuGet package to the project and to switch to the `AddElasticOpenTelemetry` extension methods. Doing so will switch to the opinionated configuration provided by EDOT .NET.
<!-- ✅ Start-to-finish operation -->
## 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.
<!-- ✅ Any dependencies that need to be installed in addition to EDOT .NET -->
1. To take advantage of the OpenTelemetry SDK instrumentation for ASP.NET Core, add the following NuGet package to your project:
Expand Down Expand Up @@ -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());
```
Expand Down Expand Up @@ -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

<!-- ✅ Any dependencies that need to be installed in addition to EDOT .NET -->
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
<PackageReference Include="Elastic.OpenTelemetry" Version="<LATEST>" />
Expand All @@ -156,18 +155,19 @@ For console applications, services, etc that are written against a builder that
> [!NOTE]
> Replace the `<LATEST>` 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`.

Expand All @@ -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
Expand Down

0 comments on commit 324c7f5

Please sign in to comment.