Skip to content

Update DiagnosticSource and OTel Bridge documentation #2680

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 10 commits into
base: main
Choose a base branch
from
Open

Update DiagnosticSource and OTel Bridge documentation #2680

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
c88aa38
Update documentation
stevejgordon Oct 16, 2025
f4b1900
Further version updates
stevejgordon Oct 16, 2025
96e024d
Fix auto instrumentation
stevejgordon Oct 17, 2025
41f4a38
Tweak auto instrumentation
stevejgordon Oct 17, 2025
5e8de78
Update supported technologies
stevejgordon Oct 17, 2025
45970a1
Update with specific supported version numbers
stevejgordon Oct 21, 2025
0c512ca
Update supported technologies
stevejgordon Oct 21, 2025
b207bd4
Add IIS support note
stevejgordon Oct 21, 2025
37ec731
Update supported versions
stevejgordon Oct 21, 2025
bd7c645
Add note about web garden support
stevejgordon Oct 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/ISSUE_TEMPLATE/Bug_report.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,9 @@ The version of the `Elastic.Apm` nuget package used

**Operating system and version:**

**.NET Framework/Core name and version** (e.g. .NET 4.6.2, NET Core 3.1.100) :
**.NET Framework/Core name and version** (e.g. .NET 4.6.2, NET 8) :

**Application Target Framework(s)** (e.g. net462, netcoreapp3.1):
**Application Target Framework(s)** (e.g. net462, net8.0):

### Describe the bug
A clear and concise description of what the bug is.
Expand Down
5 changes: 4 additions & 1 deletion docs/reference/config-core.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -365,7 +365,7 @@ Sets the minimum duration of exit spans. Exit spans with a duration lesser than
apm_agent_dotnet: ga 1.13
```

Setting this option to `false` will disable the [OpenTelemetry Bridge](/reference/opentelemetry-bridge.md). This will disable the use of the vendor-neutral OpenTelemetry Tracing API (the [Activity API](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.activity?view=net-5.0) in .NET) to manually instrument your code, and have the Elastic .NET APM agent handle those API calls.
Setting this option to `false` will disable the [OpenTelemetry Bridge](/reference/opentelemetry-bridge.md). This will disable the use of the vendor-neutral OpenTelemetry Tracing API (the [Activity API](https://learn.microsoft.com/dotnet/api/system.diagnostics.activity) in .NET) to manually instrument your code, and have the Elastic .NET APM agent handle those API calls.

| Environment variable name | IConfiguration key |
| --- | --- |
Expand All @@ -375,3 +375,6 @@ Setting this option to `false` will disable the [OpenTelemetry Bridge](/referenc
| --- | --- |
| `true` | Boolean |

::::{note}
The OpenTelemetry Bridge is not supported on .NET Framework.
::::
2 changes: 1 addition & 1 deletion docs/reference/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ The Elastic APM .NET Agent automatically measures the performance of your applic

## How does the Agent work? [how-it-works]

The agent auto-instruments [supported technologies](/reference/supported-technologies.md) and records interesting events, like HTTP requests and database queries. To do this, it uses built-in capabilities of the instrumented frameworks like [Diagnostic Source](https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics.diagnosticsource?view=netcore-3.0), an HTTP module for IIS, or [IDbCommandInterceptor](https://docs.microsoft.com/en-us/dotnet/api/system.data.entity.infrastructure.interception.idbcommandinterceptor?view=entity-framework-6.2.0) for Entity Framework. This means that for the supported technologies, there are no code changes required beyond enabling [auto-instrumentation](/reference/set-up-apm-net-agent.md).
The agent auto-instruments [supported technologies](/reference/supported-technologies.md) and records interesting events, like HTTP requests and database queries. To do this, it uses built-in capabilities of the instrumented frameworks like [Diagnostic Source](https://docs.microsoft.com/dotnet/api/system.diagnostics.diagnosticsource), an HTTP module for IIS, or [IDbCommandInterceptor](https://docs.microsoft.com/dotnet/api/system.data.entity.infrastructure.interception.idbcommandinterceptor?view=entity-framework-6.2.0) for Entity Framework. This means that for the supported technologies, there are no code changes required beyond enabling [auto-instrumentation](/reference/set-up-apm-net-agent.md).

The Agent automatically registers callback methods for built-in Diagnostic Source events. With this, the supported frameworks trigger Agent code for relevant events to measure their duration and collect metadata, like DB statements, as well as HTTP related information, like the URL, parameters, and headers. These events, called Transactions and Spans, are sent to the APM Server. The APM Server converts them to a format suitable for Elasticsearch, and sends them to an Elasticsearch cluster. You can then use the APM app in Kibana to gain insight into latency issues and error culprits within your application.

Expand Down
2 changes: 1 addition & 1 deletion docs/reference/metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ These metrics will be sent regularly to the APM Server and from there to Elastic

The metrics will be stored in the `apm-*` index and have the `processor.event` property set to `metric`.

"Platform: all" means that the metric is available on every platform where .NET Core is supported.
"Platform: all" means that the metric is available on every platform where .NET (i.e. not .NET Framework) is supported.


## System metrics [metrics-system]
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/nuget-packages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ Agent instrumentations are released as a set of NuGet packages available on [nug
The following NuGet packages are available:

[**Elastic.Apm**](https://www.nuget.org/packages/Elastic.Apm)
: The core agent package, containing the [*Public API*](/reference/public-api.md) of the agent. It also contains every tracing component to trace classes that are part of .NET Standard 2.0, which includes the monitoring part for `HttpClient`. Every other Elastic APM package references this package.
: The core agent package, contains the [*Public API*](/reference/public-api.md) of the agent. It also contains every tracing component to trace classes that are part of .NET Standard 2.0, which includes the monitoring part for `HttpClient`. Every other Elastic APM package references this package.

[**Elastic.Apm.NetCoreAll**](https://www.nuget.org/packages/Elastic.Apm.NetCoreAll)
: A meta package that references all other Elastic APM .NET agent package that can automatically configure instrumentation.
Expand Down
14 changes: 10 additions & 4 deletions docs/reference/opentelemetry-bridge.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,10 @@ applies_to:

The OpenTelemetry Bridge in the Elastic .NET APM Agent bridges OpenTelemetry spans into Elastic APM transactions and spans. The Elastic APM OpenTelemetry bridge allows you to use the vendor-neutral OpenTelemetry Tracing API to manually instrument your code and have the Elastic .NET APM agent handle those API calls. This means you can use the Elastic APM agent for tracing, without any vendor lock-in from adding manual tracing using the APM agent’s own [Public API](/reference/public-api.md).

::::{note}
The OpenTelemetry Bridge is not supported on .NET Framework.
::::


## Getting started [otel-getting-started]

Expand All @@ -21,11 +25,11 @@ The OpenTelemetry bridge is part of the core agent package ([`Elastic.Apm`](http

### Disabling the OpenTelemetry Bridge [otel-enable-bridge]

The OpenTelemetry bridge is enabled out of the box starting version `1.23.0`.
The OpenTelemetry bridge is enabled by default since version `1.23.0`.

This allows you to instrument code through `ActivitySource` and `StartActivity()` without any additional configuration.

If you want to disable the bridge you can disable it for now through the [OpenTelemetryBridgeEnabled](/reference/config-core.md#config-opentelemetry-bridge-enabled) configuration setting.
If you want to disable the bridge you can disable it for using the [OpenTelemetryBridgeEnabled](/reference/config-core.md#config-opentelemetry-bridge-enabled) configuration setting.

If you configured the agent via environment variables, set the `ELASTIC_APM_OPENTELEMETRY_BRIDGE_ENABLED` environment variable to `false`.

Expand Down Expand Up @@ -106,15 +110,17 @@ Furthermore, the agent offers the [BaggageToAttach](/reference/config-http.md#co

### Supported OpenTelemetry implementations [supported-opentelemetry-implementations]

OpenTelemetry in .NET is implemented via the [Activity API](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.activity?view=net-6.0) and there is an [OpenTelemetry shim](https://opentelemetry.io/docs/instrumentation/net/shim/) which follows the OpenTelemetry specification more closer. This shim is built on top of the Activity API.
OpenTelemetry in .NET is implemented via the [Activity API](https://learn.microsoft.com/dotnet/api/system.diagnostics.activity) and there is an [OpenTelemetry shim](https://opentelemetry.io/docs/instrumentation/net/shim/) which follows the OpenTelemetry specification more closer. This shim is built on top of the Activity API.

The OpenTelemetry bridge in the Elastic .NET APM Agent targets the [Activity API](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.activity?view=net-6.0). Since the [OpenTelemetry .NET shim](https://opentelemetry.io/docs/instrumentation/net/shim/) builds on top of the [Activity API](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.activity?view=net-6.0), the shim is implicitly supported as well, although we don’t directly test it, because the Activity API is the recommended OpenTelemetry API for .NET.
The OpenTelemetry bridge in the Elastic .NET APM Agent targets the [Activity API](https://learn.microsoft.com/dotnet/api/system.diagnostics.activity). Since the [OpenTelemetry .NET shim](https://opentelemetry.io/docs/instrumentation/net/shim/) builds on top of the [Activity API](https://learn.microsoft.com/dotnet/api/system.diagnostics.activity), the shim is implicitly supported as well, although we don’t directly test it, because the Activity API is the recommended OpenTelemetry API for .NET.


## Caveats [otel-caveats]

Not all features of the OpenTelemetry API are supported.

The OpenTelemetry Bridge is not supported on .NET Framework.


#### Metrics [otel-metrics]

Expand Down
4 changes: 2 additions & 2 deletions docs/reference/set-up-apm-net-agent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,14 +20,14 @@ NuGet packages
: The agent ships as a set of [NuGet packages](/reference/nuget-packages.md) available on [nuget.org](https://nuget.org). You can add the Agent and specific instrumentations to a .NET application by referencing one or more of these packages and following the package documentation.

Host startup hook
: On **.NET Core 3.0+ or .NET 5+**, the agent supports auto instrumentation without any code change and without any recompilation of your projects. See [Zero code change setup on .NET Core](/reference/setup-dotnet-net-core.md#zero-code-change-setup) for more details.
: On **.NET**, the agent supports auto instrumentation without any code change and without any recompilation of your projects. See [Zero code change setup on .NET](/reference/setup-dotnet-net-core.md#zero-code-change-setup) for more details.


## Get started [_get_started]

* [Profiler Auto instrumentation](/reference/setup-auto-instrumentation.md)
* [ASP.NET Core](/reference/setup-asp-net-core.md)
* [.NET Core and .NET 5+](/reference/setup-dotnet-net-core.md)
* [.NET](/reference/setup-dotnet-net-core.md)
* [ASP.NET](/reference/setup-asp-dot-net.md)
* [Azure Functions](/reference/setup-azure-functions.md)
* [Manual instrumentation](/reference/setup-general.md)
3 changes: 1 addition & 2 deletions docs/reference/setup-asp-dot-net.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ applies_to:

## Quick start [_quick_start_4]

To enable auto instrumentation for ASP.NET (Full .NET Framework), you need to install the `Elastic.Apm.AspNetFullFramework` package, add a reference to the package in your `web.config` file, and then compile and deploy your application.
To enable auto instrumentation for ASP.NET (.NET Framework), you need to install the `Elastic.Apm.AspNetFullFramework` package, add a reference to the package in your `web.config` file, and then compile and deploy your application.

1. Ensure you have access to the application source code and install the [`Elastic.Apm.AspNetFullFramework`](https://www.nuget.org/packages/Elastic.Apm.AspNetFullFramework) package.
2. Reference the `Elastic.Apm.AspNetFullFramework` in your application’s `web.config` file by adding the `ElasticApmModule` IIS module:
Expand Down Expand Up @@ -61,7 +61,6 @@ Our IIS module requires:
* IIS 7 or later
* Application pool’s pipeline mode has to be set to integrated (default for IIS 7 and up)
* The deployed .NET application must NOT run under quirks mode. This makes `LegacyAspNetSynchronizationContext` the async context handler and can break `HttpContext.Items` correctly restoring when async code introduces a thread switch.

::::


Expand Down
53 changes: 29 additions & 24 deletions docs/reference/setup-auto-instrumentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,24 +14,31 @@ applies_to:

### Quick start [_quick_start]

The agent can automatically instrument .NET Framework, .NET Core, and .NET applications using the [.NET CLR Profiling APIs](https://docs.microsoft.com/en-us/dotnet/framework/unmanaged-api/profiling/profiling-overview#the-profiling-api). The Profiling APIs provide a way to instrument an application or dependency code without code changes.
The agent can automatically instrument .NET Framework and .NET applications using the [.NET CLR Profiling APIs](https://docs.microsoft.com/en-us/dotnet/framework/unmanaged-api/profiling/profiling-overview#the-profiling-api). The Profiling APIs provide a way to instrument an application or dependency code without code changes.

This approach works with the following

| | |
| --- | --- |
| | **Operating system** |
| **Architecture*** | ***Windows*** | ***Linux** ** |
| x64 | .NET Framework 4.6.2+*<br>.NET Core 2.1+<br>.NET 5+ | .NET Core 2.1+<br>.NET 5+ |
| **Architecture** | **Windows** | **Linux** \*\* |
| x64 | .NET Framework 4.6.2-4.8.1\*<br>.NET 8+ | .NET 8+ |

** Due to binding issues introduced by Microsoft, we recommend at least .NET Framework 4.7.2 for best compatibility.*
\* Due to binding issues introduced by Microsoft, we recommend at least .NET Framework 4.7.2 for best compatibility.*

*** Minimum GLIBC version 2.14.*
\*\* Minimum GLIBC version 2.14.

::::{note}
The profiler-based agent only supports 64-bit applications. 32-bit applications aren’t supported.
While the rofiler-based agent **may** work on older .NET runtimes such as .NET 6, it is only officially tested and supported on runtimes that are supported by Microsoft, currently .NET 8 and newer.
::::

::::{note}
While the rofiler-based agent **may** work in the web garden (multi-worker process) mode of IIS, this is not officially tested or supported.
::::

::::{note}
The profiler-based agent only supports 64-bit applications. 32-bit applications aren’t supported.
::::

::::{note}
The profiler-based agent does not currently support ARM.
Expand All @@ -40,37 +47,35 @@ The profiler-based agent does not currently support ARM.

It instruments the following assemblies:

| Integration name | NuGet package version(s) | Assembly version(s) |
| Integration name | NuGet package version(s)
| --- | --- | --- |
| AdoNet | part of .NET | System.Data 4.0.0 - 4.*.* |
| part of .NET | System.Data.Common 4.0.0 - 5.*.* |
| AspNet | part of .NET Framework | System.Web 4.0.0 - 4.*.* |
| Kafka | [Confluent.Kafka 1.4.0 - 2.*.*](https://www.nuget.org/packages/Confluent.Kafka) | Confluent.Kafka 1.4.0 - 2.*.* |
| MySqlCommand | [MySql.Data 6.7.0 - 8.*.*](https://www.nuget.org/packages/MySql.Data) | MySql.Data 6.7.0 - 8.*.* |
| NpgsqlCommand | [Npgsql 4.0.0 - 7.*.*](https://www.nuget.org/packages/Npgsql) | Npgsql 4.0.0 - 7.*.* |
| OracleCommand | [Oracle.ManagedDataAccess 12.2.1100 - 21.*.*](https://www.nuget.org/packages/Oracle.ManagedDataAccess) | Oracle.ManagedDataAccess 4.122.0 - 4.122.* |
| [Oracle.ManagedDataAccess.Core 2.0.0 - 3.*.*](https://www.nuget.org/packages/Oracle.ManagedDataAccess.Core) | Oracle.ManagedDataAccess 2.0.0 - 3.*.* |
| RabbitMQ | [RabbitMQ.Client 3.6.9 - 6.*.*](https://www.nuget.org/packages/RabbitMQ.Client) | RabbitMQ.Client 3.6.9 - 6.*.* |
| SqlCommand | part of .NET | System.Data 4.0.0 - 4.*.* |
| [System.Data.SqlClient 4.0.0 - 4.*.*](https://www.nuget.org/packages/System.Data.SqlClient) | System.Data.SqlClient 4.0.0 - 4.*.* |
| [Microsoft.Data.SqlClient 1.0.0 - 5.*.*](https://www.nuget.org/packages/Microsoft.Data.SqlClient) | Microsoft.Data.SqlClient 1.0.0 - 5.*.* |
| SqliteCommand | [Microsoft.Data.Sqlite 2.0.0 - 7.*.*](https://www.nuget.org/packages/Microsoft.Data.Sqlite) | Microsoft.Data.Sqlite 2.0.0 - 7.*.* |
| [System.Data.SQLite 1.0.0 - 2.*.*](https://www.nuget.org/packages/System.Data.SQLite) | System.Data.SQLite 1.0.0 - 2.*.* |
| AdoNet | part of .NET Framework |
| AspNet | part of .NET Framework |
| Kafka | [Confluent.Kafka 1.4.0 - 2.12.0](https://www.nuget.org/packages/Confluent.Kafka) |
| MySqlCommand | [MySql.Data 6.7.0 - 8.4.0](https://www.nuget.org/packages/MySql.Data) |
| NpgsqlCommand | [Npgsql 4.0.0 - 7.0.10](https://www.nuget.org/packages/Npgsql) |
| OracleCommand | [Oracle.ManagedDataAccess 12.2.1100 - 21.20.0](https://www.nuget.org/packages/Oracle.ManagedDataAccess) |
| [Oracle.ManagedDataAccess.Core 2.0.0 - 3.21.200](https://www.nuget.org/packages/Oracle.ManagedDataAccess.Core) |
| RabbitMQ | [RabbitMQ.Client 3.6.9 - 6.8.1](https://www.nuget.org/packages/RabbitMQ.Client) |
| SqlCommand | part of .NET Framework |
| [System.Data.SqlClient 4.0.0 - 4.9.0](https://www.nuget.org/packages/System.Data.SqlClient) |
| [Microsoft.Data.SqlClient 1.0.0 - 5.2.3](https://www.nuget.org/packages/Microsoft.Data.SqlClient) |
| SqliteCommand | [Microsoft.Data.Sqlite 2.0.0 - 7.0.20](https://www.nuget.org/packages/Microsoft.Data.Sqlite) |
| SQLite | [System.Data.SQLite 1.0.0 - 2.0.2](https://www.nuget.org/packages/System.Data.SQLite) |

::::{important}
**The .NET CLR Profiling API allows only one profiler to be attached to a .NET process**. In light of this limitation, only one solution that uses the .NET CLR profiling API should be used by an application.

Auto instrumentation using the .NET CLR Profiling API can be used in conjunction with

* the [Public API](/reference/public-api.md) to perform manual instrumentation.
* OpenTelemetry native instrumentation using the [Activity](https://learn.microsoft.com/dotnet/api/system.diagnostics.activity) API and the [OpenTelemetry Bridge](/reference/opentelemetry-bridge.md).
* The [Public API](/reference/public-api.md) to perform manual instrumentation.
* NuGet packages that perform instrumentation using a `IDiagnosticsSubscriber` to subscribe to diagnostic events.

The version number of NuGet packages referenced by a project instrumented with a profiler must be the same as the version number of profiler zip file used.

::::



### General steps [_general_steps]

The general steps in configuring profiler auto instrumentation are as follows; See [Instrumenting containers and services](#instrumenting-containers-and-services) for configuration for common deployment environments.
Expand Down
Loading
Loading