diff --git a/.github/ISSUE_TEMPLATE/Bug_report.md b/.github/ISSUE_TEMPLATE/Bug_report.md index 1bff68f56..63e3be296 100644 --- a/.github/ISSUE_TEMPLATE/Bug_report.md +++ b/.github/ISSUE_TEMPLATE/Bug_report.md @@ -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. diff --git a/docs/reference/config-core.md b/docs/reference/config-core.md index 41fe7de62..678c0a900 100644 --- a/docs/reference/config-core.md +++ b/docs/reference/config-core.md @@ -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 | | --- | --- | @@ -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. +:::: \ No newline at end of file diff --git a/docs/reference/index.md b/docs/reference/index.md index d3858b354..3c31c00f1 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -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. diff --git a/docs/reference/metrics.md b/docs/reference/metrics.md index 2b89eaab9..2237a0de2 100644 --- a/docs/reference/metrics.md +++ b/docs/reference/metrics.md @@ -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] diff --git a/docs/reference/nuget-packages.md b/docs/reference/nuget-packages.md index 2e2cd81b1..c9f990c7d 100644 --- a/docs/reference/nuget-packages.md +++ b/docs/reference/nuget-packages.md @@ -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. diff --git a/docs/reference/opentelemetry-bridge.md b/docs/reference/opentelemetry-bridge.md index 6e5550b1a..d0260e35b 100644 --- a/docs/reference/opentelemetry-bridge.md +++ b/docs/reference/opentelemetry-bridge.md @@ -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] @@ -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`. @@ -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] diff --git a/docs/reference/set-up-apm-net-agent.md b/docs/reference/set-up-apm-net-agent.md index e859042df..3c2ec5907 100644 --- a/docs/reference/set-up-apm-net-agent.md +++ b/docs/reference/set-up-apm-net-agent.md @@ -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) diff --git a/docs/reference/setup-asp-dot-net.md b/docs/reference/setup-asp-dot-net.md index 4fcdd4193..c1574f8b7 100644 --- a/docs/reference/setup-asp-dot-net.md +++ b/docs/reference/setup-asp-dot-net.md @@ -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: @@ -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. - :::: diff --git a/docs/reference/setup-auto-instrumentation.md b/docs/reference/setup-auto-instrumentation.md index d7095f989..b567fb845 100644 --- a/docs/reference/setup-auto-instrumentation.md +++ b/docs/reference/setup-auto-instrumentation.md @@ -14,24 +14,27 @@ 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+*
.NET Core 2.1+
.NET 5+ | .NET Core 2.1+
.NET 5+ | +| **Architecture** | **Windows** | **Linux** \*\* | +| x64 | .NET Framework 4.6.2-4.8.1\*
.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 profiler **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} +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. @@ -40,37 +43,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. diff --git a/docs/reference/setup-dotnet-net-core.md b/docs/reference/setup-dotnet-net-core.md index 76d36564c..3ee2f559b 100644 --- a/docs/reference/setup-dotnet-net-core.md +++ b/docs/reference/setup-dotnet-net-core.md @@ -9,12 +9,12 @@ applies_to: apm_agent_dotnet: ga --- -# .NET Core and .NET 5+ [setup-dotnet-net-core] +# .NET 8+ [setup-dotnet-net-core] ## Quick start [_quick_start_3] -In .NET (Core) applications using `Microsoft.Extensions.Hosting`, the agent can be registered on the `IServiceCollection`. This applies to ASP.NET Core and to other .NET applications that depend on the hosting APIs, such as those created using the [worker services](https://learn.microsoft.com/en-us/dotnet/core/extensions/workers) template. +In .NET applications using `Microsoft.Extensions.Hosting`, the agent can be registered on the `IServiceCollection`. This applies to ASP.NET Core and to other .NET applications that depend on the hosting APIs, such as those created using the [worker services](https://learn.microsoft.com/en-us/dotnet/core/extensions/workers) template. The simplest way to enable the agent and its instrumentations requires a reference to the [`Elastic.Apm.NetCoreAll`](https://www.nuget.org/packages/Elastic.Apm.NetCoreAll) package. @@ -95,7 +95,7 @@ namespace WorkerServiceSample 1. The `CaptureTransaction` method creates a transaction named *UnitOfWork* and type *App*. The lambda passed to it represents the unit of work that should be captured within the context of the transaction. -When this application runs, a new transaction will be captured and sent for each while loop iteration. A span named *HTTP GET* within the transaction will be created for the HTTP request to `https://www.elastic.co`. The HTTP span is captured because the NetCoreAll package enables this instrumentation automatically. +When this application runs, a new transaction will be captured and sent for each while loop iteration. A span named *HTTP GET* within the transaction will be created for the HTTP request to `https://www.elastic.co`. The HTTP span is captured because the `NetCoreAll` package enables this instrumentation automatically. ## Manual instrumentation using OpenTelemetry [_manual_instrumentation_using_opentelemetry] @@ -164,9 +164,9 @@ host.Run(); -## Zero code change setup on .NET Core and .NET 5+ ([1.7]) [zero-code-change-setup] +## Zero code change setup on .NET 8+ ([1.7]) [zero-code-change-setup] -If you can’t or don’t want to reference NuGet packages in your application, you can use the startup hook feature to inject the agent during startup, if your application runs on .NET Core 3.0, .NET Core 3.1 or .NET 5 or newer. +If you can’t or don’t want to reference NuGet packages in your application, you can use the startup hook feature to inject the agent during startup, if your application runs on .NET 8 or newer. To configure startup hooks @@ -180,7 +180,7 @@ To configure startup hooks 1. `` is the unzipped directory from step 2. -4. Start your .NET Core application in a context where the `DOTNET_STARTUP_HOOKS` environment variable is visible. +4. Start your .NET application in a context where the `DOTNET_STARTUP_HOOKS` environment variable is visible. With this setup, the agent will be injected into the application during startup, enabling every instrumentation feature. Incoming requests will be automatically captured on ASP.NET Core (including gRPC). @@ -188,5 +188,3 @@ With this setup, the agent will be injected into the application during startup, Agent configuration can be controlled through environment variables when using the startup hook feature. :::: - - diff --git a/docs/reference/setup-ef-core.md b/docs/reference/setup-ef-core.md index 27bd3fdbd..134ad9418 100644 --- a/docs/reference/setup-ef-core.md +++ b/docs/reference/setup-ef-core.md @@ -14,7 +14,7 @@ applies_to: ## Quick start [_quick_start_5] -Instrumentation can be enabled for Entity Framework Core by referencing [`Elastic.Apm.EntityFrameworkCore`](https://www.nuget.org/packages/Elastic.Apm.EntityFrameworkCore) package and passing `EfCoreDiagnosticsSubscriber` to the `AddElasticApm` method in case of ASP.NET Core as following +Instrumentation can be enabled for Entity Framework Core by referencing [`Elastic.Apm.EntityFrameworkCore`](https://www.nuget.org/packages/Elastic.Apm.EntityFrameworkCore) package and passing `EfCoreDiagnosticsSubscriber` to the `AddElasticApm` method in case of ASP.NET Core, as follows: ```csharp app.Services.AddElasticApm(new EfCoreDiagnosticsSubscriber()); @@ -26,5 +26,4 @@ or passing `EfCoreDiagnosticsSubscriber` to the `Subscribe` method Agent.Subscribe(new EfCoreDiagnosticsSubscriber()); ``` -Instrumentation listens for diagnostic events raised by `Microsoft.EntityFrameworkCore` 2.x+, creating database spans for executed commands. - +Instrumentation listens for diagnostic events raised by `Microsoft.EntityFrameworkCore`, creating database spans for executed commands. diff --git a/docs/reference/setup-ef6.md b/docs/reference/setup-ef6.md index 9a250c44f..063bd5f5b 100644 --- a/docs/reference/setup-ef6.md +++ b/docs/reference/setup-ef6.md @@ -40,5 +40,3 @@ Instrumentation works with EntityFramework 6.2+ NuGet packages. ::::{note} Be careful not to execute `DbInterception.Add` for the same interceptor type more than once, as this will register multiple instances, causing multiple database spans to be captured for every SQL command. :::: - - diff --git a/docs/reference/setup-elasticsearch.md b/docs/reference/setup-elasticsearch.md index da967890a..a50b48e1e 100644 --- a/docs/reference/setup-elasticsearch.md +++ b/docs/reference/setup-elasticsearch.md @@ -14,6 +14,12 @@ applies_to: ## Quick start [_quick_start_7] +### Current client + +The currently supported Elasticsearch client for .NET ships in the [Elastic.Clients.Elasticsearch](https://www.nuget.org/packages/Elastic.Clients.Elasticsearch) NuGet package. This package and the underlying transport are instrumented with OpenTelemetry native APIs built into .NET. These will be picked up automatically when the [OpenTelemetry Bridge](/reference/config-core.md#config-opentelemetry-bridge-enabled) feature is enabled. + +### Legacy clients + Instrumentation can be enabled for Elasticsearch when using the official Elasticsearch clients, Elasticsearch.Net and Nest, by referencing [`Elastic.Apm.Elasticsearch`](https://www.nuget.org/packages/Elastic.Apm.Elasticsearch) package and passing `ElasticsearchDiagnosticsSubscriber` to the `AddElasticApm` method in case of ASP.NET Core as following ```csharp @@ -26,11 +32,8 @@ or passing `ElasticsearchDiagnosticsSubscriber` to the `Subscribe` method Agent.Subscribe(new ElasticsearchDiagnosticsSubscriber()); ``` -Instrumentation listens for activities raised by `Elasticsearch.Net` and `Nest` 7.6.0+, creating spans for executed requests. +Instrumentation listens for activities raised by `Elasticsearch.Net` and `Nest`, creating spans for executed requests. ::::{important} If you’re using `Elasticsearch.Net` and `Nest` 7.10.1 or 7.11.0, upgrade to at least 7.11.1 which fixes a bug in span capturing. - :::: - - diff --git a/docs/reference/setup-general.md b/docs/reference/setup-general.md index a14e3d335..6af51fd2b 100644 --- a/docs/reference/setup-general.md +++ b/docs/reference/setup-general.md @@ -13,5 +13,10 @@ applies_to: If you have a .NET application that is not covered in this section, you can still use the agent and instrument your application manually. -To do this, add the [Elastic.Apm](https://www.nuget.org/packages/Elastic.Apm) package to your application and use the [*Public API*](/reference/public-api.md) to manually create spans and transactions. +To do this, add the [Elastic.Apm](https://www.nuget.org/packages/Elastic.Apm) package to your application and use the [*Public API*](/reference/public-api.md) +or .NET [Activity](https://learn.microsoft.com/dotnet/core/diagnostics/distributed-tracing-instrumentation-walkthroughs) APIs to manually create spans and transactions. +::::{important} +For best flexibility and reduced vendor lock-in, we recommend preferring that custom instrumentation uses the [System.Diagnostics.Activity](https://learn.microsoft.com/dotnet/api/system.diagnostics.activity) API. Code instrumented with this API will be picked up by the OpenTelemetry Bridge and is also natively +compatible OpenTelemetry. +:::: diff --git a/docs/reference/setup-mongo-db.md b/docs/reference/setup-mongo-db.md index a4e2b65ac..b9c051bc1 100644 --- a/docs/reference/setup-mongo-db.md +++ b/docs/reference/setup-mongo-db.md @@ -14,7 +14,7 @@ applies_to: ## Quick start [_quick_start_14] -Instrumentation for MongoDB works with the official MongoDb.Driver 3.0.0+ driver packages. A prerequisite for auto instrumentation is to configure the `MongoClient` with `MongoDbEventSubscriber`: +Instrumentation for MongoDB works with the official MongoDb.Driver driver packages. A prerequisite for auto instrumentation is to configure the `MongoClient` with `MongoDbEventSubscriber`: ```csharp var settings = MongoClientSettings.FromConnectionString(mongoConnectionString); @@ -33,8 +33,5 @@ Agent.Subscribe(new MongoDbDiagnosticsSubscriber()); ``` ::::{important} -MongoDB integration is currently supported on .NET Core and newer. Due to MongoDb.Driver assemblies not being strongly named, they cannot be used with Elastic APM’s strongly named assemblies on .NET Framework. - +MongoDB integration is currently supported on .NET runtimes. Due to MongoDb.Driver assemblies not being strongly named, they cannot be used with Elastic APM’s strongly named assemblies on .NET Framework. :::: - - diff --git a/docs/reference/setup-sqlclient.md b/docs/reference/setup-sqlclient.md index 88b420961..9ee4aefb1 100644 --- a/docs/reference/setup-sqlclient.md +++ b/docs/reference/setup-sqlclient.md @@ -29,12 +29,9 @@ Agent.Subscribe(new SqlClientDiagnosticSubscriber()); ``` ::::{note} -Auto instrumentation for `System.Data.SqlClient` is available for both .NET Core and .NET Framework applications, however, support of .NET Framework has one limitation: command text cannot be captured. +Auto instrumentation for `System.Data.SqlClient` is available for both .NET and .NET Framework applications, however, support of .NET Framework has one limitation: command text cannot be captured. -Auto instrumentation for `Microsoft.Data.SqlClient` is available only for .NET Core at the moment. +Auto instrumentation for `Microsoft.Data.SqlClient` is available only for .NET at the moment. As an alternative to using the `Elastic.Apm.SqlClient` package to instrument database calls, see [Profiler Auto instrumentation](/reference/setup-auto-instrumentation.md). - :::: - - diff --git a/docs/reference/supported-technologies.md b/docs/reference/supported-technologies.md index 7a949b94c..0808bdf8e 100644 --- a/docs/reference/supported-technologies.md +++ b/docs/reference/supported-technologies.md @@ -11,31 +11,18 @@ applies_to: # Supported technologies [supported-technologies] -If your favorite technology is not supported yet, you can vote for it by participating in our [survey](https://docs.google.com/forms/d/18SgsVo9asGNFMjRqwdrk3wTHNwPhtHv4jE35hZRCL6A/). We will use the results to add support for the most requested technologies. - -Another option is to add a dependency to the agent’s [public API](/reference/public-api.md) in order to programmatically create custom transactions and spans. - -If you want to extend the auto-instrumentation capabilities of the agent, the [contributing guide](https://github.com/elastic/apm-agent-dotnet/blob/main/CONTRIBUTING.md) should get you started. - -::::{note} -If, for example, the HTTP client library of your choice is not listed, it means that there won’t be spans for those outgoing HTTP requests. If the web framework you are using is not supported, the agent will not capture transactions. -:::: - - ## .NET versions [supported-dotnet-flavors] -The agent works on every .NET flavor and version that supports .NET Standard 2.0. This means .NET Core 2.0 or newer, and .NET Framework 4.6.2* or newer. +The APM Agent for .NET targets every .NET flavor and version that supports .NET Standard 2.0 or .NET Standard 2.1. -** Due to binding issues introduced by Microsoft, we recommend at least .NET Framework 4.7.2 for best compatibility.* - -::::{important} -While this library **should** work on .NET Core 2.0+, we limit our support to only those versions currently supported by Microsoft - .NET 6.0 and newer. +However, we only test and support .NET runtimes that are also supported per the [Microsoft .NET support policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core). Therefore, we always recommend you upgrade to a supported runtime before raising issues. +::::{note} +On .NET Framework, due to binding issues introduced by Microsoft, we recommend at least .NET Framework 4.7.2 for best compatibility. :::: - ## Web frameworks [supported-web-frameworks] Automatic instrumentation for a web framework means a transaction is automatically created for each incoming request and it is named after the registered route. @@ -44,20 +31,25 @@ Automatic instrumentation is supported for the following web frameworks | Framework | Supported versions | Integration | | --- | --- | --- | -| ASP.NET Core {applies_to}`apm_agent_dotnet: ga 1.0` | 2.1+ | [NuGet package](/reference/setup-asp-net-core.md) | -| ASP.NET (.NET Framework) in IIS {applies_to}`apm_agent_dotnet: ga 1.1` | 4.6.2+ (IIS 7.0 or newer) | [Profiler auto instrumentation](/reference/setup-auto-instrumentation.md)
*or*
[NuGet package](/reference/setup-asp-dot-net.md) | +| ASP.NET Core {applies_to}`apm_agent_dotnet: ga 1.0` | ≥8.0.0 and <10.0.0 | [NuGet package](/reference/setup-asp-net-core.md) | +| ASP.NET (.NET Framework) in IIS {applies_to}`apm_agent_dotnet: ga 1.1` | 4.6.2-4.8.1 (IIS 10) | [Profiler auto instrumentation](/reference/setup-auto-instrumentation.md)
*or*
[NuGet package](/reference/setup-asp-dot-net.md) | + +::::{note} +We support ASP.NET on IIS 10 versions supported by Microsoft per their [IIS support policy](https://learn.microsoft.com/lifecycle/products/internet-information-services-iis). +IIS must be installed on a [supported](https://learn.microsoft.com/windows/release-health/windows-server-release-info#windows-server-major-versions-by-servicing-option--) Windows operating system version. +:::: ## RPC Frameworks [supported-rpc-frameworks] -The agent supports gRPC on .NET Core both on the client and the server side. Every gRPC call is automatically captured by the agent. +The agent supports gRPC on .NET both on the client and the server side. Every gRPC call is automatically captured by the agent. Streaming is not supported; for streaming use-cases, the agent does not create transactions and spans automatically. | Framework | Supported versions | Integration | | --- | --- | --- | -| gRPC {applies_to}`apm_agent_dotnet: ga 1.7` | Grpc.Net.Client 2.23.2+ *(client side)* | [NuGet package](/reference/setup-grpc.md) | -| ASP.NET Core 2.1+ *(server side)* | [NuGet package](/reference/setup-asp-net-core.md) | +| gRPC {applies_to}`apm_agent_dotnet: ga 1.7` | Grpc.Net.Client 2.23.2-2.71.0 *(client side)* | [NuGet package](/reference/setup-grpc.md) | +| ASP.NET Core 8 or 9 *(server side)* | [NuGet package](/reference/setup-asp-net-core.md) | ## Data access technologies [supported-data-access-technologies] @@ -66,22 +58,22 @@ Automatic instrumentation is supported for the following data access technologie | Data access technology | Supported versions | Integration | | --- | --- | --- | -| Azure CosmosDB {applies_to}`apm_agent_dotnet: ga 1.11` | Microsoft.Azure.Cosmos 3.0.0+ | [NuGet package](/reference/setup-azure-cosmosdb.md) | -| Microsoft.Azure.DocumentDB.Core 2.4.1+ | -| Microsoft.Azure.DocumentDB 2.4.1+ | -| Entity Framework Core {applies_to}`apm_agent_dotnet: ga 1.0` | Microsoft.EntityFrameworkCore 2.x+ | [NuGet package](/reference/setup-ef-core.md) | -| Entity Framework 6 {applies_to}`apm_agent_dotnet: ga 1.2` | EntityFramework 6.2+ | [NuGet package](/reference/setup-ef6.md) | -| Elasticsearch {applies_to}`apm_agent_dotnet: ga 1.6` | Elasticsearch.Net 7.6.0+ | [NuGet package](/reference/setup-elasticsearch.md) | -| NEST 7.6.0+ | +| Azure CosmosDB {applies_to}`apm_agent_dotnet: ga 1.11` | Microsoft.Azure.Cosmos 3.0.0-3.54.0 | [NuGet package](/reference/setup-azure-cosmosdb.md) | +| Azure DocumentDb\* | Microsoft.Azure.DocumentDB.Core 2.4.1-2.22.0 | [NuGet package](/reference/setup-azure-cosmosdb.md) | +| | Microsoft.Azure.DocumentDB 2.4.1-2.22.0 | [NuGet package](/reference/setup-azure-cosmosdb.md) | +| Entity Framework Core {applies_to}`apm_agent_dotnet: ga 1.0` | Microsoft.EntityFrameworkCore 8.0.0-9.0.10 | [NuGet package](/reference/setup-ef-core.md) | +| Entity Framework 6 {applies_to}`apm_agent_dotnet: ga 1.2` | EntityFramework 6.2-6.5.1 | [NuGet package](/reference/setup-ef6.md) | +| Elasticsearch | Elastic.Clients.Elasticsearch 8.0.0-9.1.11 | via OpenTelemetry Bridge | | MySQL {applies_to}`apm_agent_dotnet: ga 1.12` | See profiler documentation | [Profiler auto instrumentation](/reference/setup-auto-instrumentation.md) | -| MongoDB | MongoDB.Driver 3.0.0+ | [NuGet package](/reference/setup-mongo-db.md) | +| MongoDB | MongoDB.Driver 3.0.0-3.5.0 | [NuGet package](/reference/setup-mongo-db.md) | | Oracle {applies_to}`apm_agent_dotnet: ga 1.12` | See profiler documentation | [Profiler auto instrumentation](/reference/setup-auto-instrumentation.md) | | PostgreSQL {applies_to}`apm_agent_dotnet: ga 1.12` | See profiler documentation | [Profiler auto instrumentation](/reference/setup-auto-instrumentation.md) | -| Redis {applies_to}`apm_agent_dotnet: ga 1.8` | StackExchange.Redis 2.0.495+ | [NuGet package](/reference/setup-stackexchange-redis.md) | -| SqlClient | System.Data.SqlClient 2.0.495+ {applies_to}`apm_agent_dotnet: ga 1.8` | [NuGet package](/reference/setup-sqlclient.md) | +| Redis {applies_to}`apm_agent_dotnet: ga 1.8` | StackExchange.Redis 2.0.495-2.9.32 | [NuGet package](/reference/setup-stackexchange-redis.md) | +| SqlClient | System.Data.SqlClient 2.0.495-4.9.0 {applies_to}`apm_agent_dotnet: ga 1.8` | [NuGet package](/reference/setup-sqlclient.md) | | See profiler documentation {applies_to}`apm_agent_dotnet: ga 1.12` | [Profiler auto instrumentation](/reference/setup-auto-instrumentation.md) | | SQLite {applies_to}`apm_agent_dotnet: ga 1.12` | See profiler documentation | [Profiler auto instrumentation](/reference/setup-auto-instrumentation.md) | +\* `Microsoft.Azure.DocumentDB.Core` and `Microsoft.Azure.DocumentDB` are deprecated. The recommended replacement is the `Microsoft.Azure.Cosmos` package. ## Messaging systems [supported-messaging-systems] @@ -89,9 +81,9 @@ We support automatic instrumentation for the following messaging systems | Messaging system | Supported versions | Integration | | --- | --- | --- | -| Azure Service Bus {applies_to}`apm_agent_dotnet: ga 1.10` | Microsoft.Azure.ServiceBus 3.0.0+ | [NuGet package](/reference/setup-azure-servicebus.md) | -| Azure.Messaging.ServiceBus 7.0.0+ | -| Azure Queue Storage {applies_to}`apm_agent_dotnet: ga 1.10` | Azure.Storage.Queues 12.6.0+ | [NuGet package](/reference/setup-azure-storage.md) | +| Azure Service Bus {applies_to}`apm_agent_dotnet: ga 1.10` | Microsoft.Azure.ServiceBus 3.0.0-5.2.0 | [NuGet package](/reference/setup-azure-servicebus.md) | +| Azure.Messaging.ServiceBus 7.0.0-7.20.1 | +| Azure Queue Storage {applies_to}`apm_agent_dotnet: ga 1.10` | Azure.Storage.Queues 12.6.0-12.24.0 | [NuGet package](/reference/setup-azure-storage.md) | | Kafka {applies_to}`apm_agent_dotnet: ga 1.12` | See profiler documentation | [Profiler auto instrumentation](/reference/setup-auto-instrumentation.md) | | Kafka | Confluent.Kafka 2.11.1 | [NuGet package](/reference/setup-kafka.md) | | RabbitMQ {applies_to}`apm_agent_dotnet: ga 1.12` | See profiler documentation | [Profiler auto instrumentation](/reference/setup-auto-instrumentation.md) | @@ -113,12 +105,11 @@ Automatic instrumentation for the following cloud services | Cloud service | Supported versions | Integration | | --- | --- | --- | -| Azure CosmosDB {applies_to}`apm_agent_dotnet: ga 1.11` | Microsoft.Azure.Cosmos 3.0.0+ | [NuGet package](/reference/setup-azure-cosmosdb.md) | -| Microsoft.Azure.DocumentDB.Core 2.4.1+ | -| Microsoft.Azure.DocumentDB 2.4.1+ | -| Azure Service Bus {applies_to}`apm_agent_dotnet: ga 1.10` | Microsoft.Azure.ServiceBus 3.0.0+ | [NuGet package](/reference/setup-azure-servicebus.md) | -| Azure.Messaging.ServiceBus 7.0.0+ | -| Azure Storage {applies_to}`apm_agent_dotnet: ga 1.10` | Azure.Storage.Blobs 12.8.0+ | [NuGet package](/reference/setup-azure-storage.md) | -| Azure.Storage.Queues 12.6.0+ | -| Azure.Storage.Files.Shares 12.6.0+ | - +| Azure CosmosDB {applies_to}`apm_agent_dotnet: ga 1.11` | Microsoft.Azure.Cosmos 3.0.0-3.54.0 | [NuGet package](/reference/setup-azure-cosmosdb.md) | +| Microsoft.Azure.DocumentDB.Core 2.4.1-2.22.0 | +| Microsoft.Azure.DocumentDB 2.4.1-2.22.0 | +| Azure Service Bus {applies_to}`apm_agent_dotnet: ga 1.10` | Microsoft.Azure.ServiceBus 3.0.0-5.2.0 | [NuGet package](/reference/setup-azure-servicebus.md) | +| Azure.Messaging.ServiceBus 7.0.0-7.20.1 | +| Azure Storage {applies_to}`apm_agent_dotnet: ga 1.10` | Azure.Storage.Blobs 12.8.0-12.26.0 | [NuGet package](/reference/setup-azure-storage.md) | +| Azure.Storage.Queues 12.6.0-12.24.0 | +| Azure.Storage.Files.Shares 12.6.0-12.24.0 | diff --git a/src/startuphook/ElasticApmAgentStartupHook/README.md b/src/startuphook/ElasticApmAgentStartupHook/README.md index 248d81f14..2e3a4807e 100644 --- a/src/startuphook/ElasticApmAgentStartupHook/README.md +++ b/src/startuphook/ElasticApmAgentStartupHook/README.md @@ -8,7 +8,7 @@ It utilizes the startup hook mechanism described [in the dotnet runtime reposito ### Prerequisites -- **.NET Core 2.2 or newer** +- **.NET 6 or newer** ### How to use it @@ -48,17 +48,25 @@ The layout in the zip file is as follows ``` ElasticApmAgent_.zip/ -├── 4.0.0/ -│ └── APM agent assemblies compiled against System.Diagnostics.DiagnosticSource 4.0.0 +├── 6.0.0/ +│ └── APM agent assemblies compiled against System.Diagnostics.DiagnosticSource 6.0.0 │ -├── 5.0.0/ -│ └── APM agent assemblies compiled against System.Diagnostics.DiagnosticSource 5.0.0 +├── 8.0.0/ +│ └── APM agent assemblies compiled against System.Diagnostics.DiagnosticSource 8.0.0 │ └── ElasticApmAgentStartupHook.dll ``` It contains numbered directories that each contain APM agent assemblies compiled against -a specific version System.Diagnostics.DiagnosticSource. +a specific version `System.Diagnostics.DiagnosticSource`. + +We maintain the 6.0.0 folder (for now) to not break those using older, unsupported .NET runtimes. We +offer no support gauruntees and may remove this folder in a future release. + +For supported runtimes, the 8.0.0 folder is used and our general dependency on +`System.Diagnostics.DiagnosticSource` is fox 8.x or newer. + +On .NET Framework targets, we continue to depend on 5.0.0 of `System.Diagnostics.DiagnosticSource`. ### Troubleshooting diff --git a/test/startuphook/Elastic.Apm.StartupHook.Sample/README.md b/test/startuphook/Elastic.Apm.StartupHook.Sample/README.md index 6d97f0c46..4c5692a92 100644 --- a/test/startuphook/Elastic.Apm.StartupHook.Sample/README.md +++ b/test/startuphook/Elastic.Apm.StartupHook.Sample/README.md @@ -3,8 +3,8 @@ This sample application is a default ASP.NET (Core) application configured to run with -- `net6.0` - `net8.0` +- `net9.0` target frameworks that can be used to try out the [Elastic APM startup hooks implementation](../../src/ElasticApmAgentStartupHook).