You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
On .NET Core, the agent can be registered on the `IHostBuilder`. This applies to both ASP.NET Core and to other .NET Core applications that depend on `IHostBuilder`, like https://docs.microsoft.com/en-us/aspnet/core/fundamentals/host/hosted-services[background tasks]. In this case, you need to reference the {nuget}/Elastic.Apm.NetCoreAll[`Elastic.Apm.NetCoreAll`] package.
10
+
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 https://learn.microsoft.com/en-us/dotnet/core/extensions/workers[worker services] template.
11
11
12
+
The simplest way to enable the agent and its instrumentations requires a reference to the {nuget}/Elastic.Apm.NetCoreAll[`Elastic.Apm.NetCoreAll`] package.
<1> Replace the `<LATEST>` placeholder with the latest version of the agent available on NuGet.
19
+
20
+
[NOTE]
21
+
--
22
+
The following code sample assumes the instrumentation of a .NET 8 worker service, using https://learn.microsoft.com/en-us/dotnet/csharp/tutorials/top-level-statements[top-level statements].
23
+
--
24
+
25
+
*Program.cs*
26
+
[source,csharp]
27
+
----
28
+
using WorkerServiceSample;
29
+
30
+
var builder = Host.CreateApplicationBuilder(args);
31
+
32
+
builder.Services.AddHttpClient();
33
+
builder.Services.AddAllElasticApm(); <1>
34
+
builder.Services.AddHostedService<Worker>();
35
+
36
+
var host = builder.Build();
37
+
host.Run();
38
+
----
39
+
<1> Register Elastic APM before registering other IHostedServices to ensure its dependencies are initialized first.
40
+
41
+
When registering services with `AddAllElasticApm()`, an APM agent with all instrumentations is enabled. On ASP.NET Core, it'll automatically capture incoming requests, database calls through supported technologies, outgoing HTTP requests, etc.
42
+
43
+
For other application templates, such as worker services, you must manually instrument your `BackgroundService` to identify one or more units of work that should be captured.
44
+
45
+
[float]
46
+
==== Manual instrumentation using `ITracer`
47
+
48
+
`AddAllElasticApm` adds an `ITracer` to the Dependency Injection system, which can be used in your code to manually instrument your application, using the <<public-api>>
49
+
50
+
*Worker.cs*
13
51
[source,csharp]
14
52
----
15
-
using Elastic.Apm.NetCoreAll;
53
+
using Elastic.Apm.Api;
16
54
17
-
namespace MyApplication
55
+
namespace WorkerServiceSample
18
56
{
19
-
public class Program
57
+
public class Worker : BackgroundService
20
58
{
21
-
public static IHostBuilder CreateHostBuilder(string[] args) =>
<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.
30
84
31
-
With the `UseAllElasticApm()`, the agent with all its components is turned on. On ASP.NET Core, it'll automatically capture incoming requests, database calls through supported technologies, outgoing HTTP requests, and so on.
85
+
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.
32
86
33
87
[float]
34
-
==== Manual instrumentation
88
+
==== Manual instrumentation using OpenTelemetry
89
+
90
+
As an alternative to using the Elastic APM API by injecting an `ITracer`, you can use the OpenTelemetry API to manually instrument your application. The Elastic APM agent automatically bridges instrumentations created using the OpenTelemetry API, so you can use it to create spans and transactions. In .NET, the https://learn.microsoft.com/en-us/dotnet/core/diagnostics/distributed-tracing-instrumentation-walkthroughs[`Activity` API] can be used to instrument applications.
35
91
36
-
The `UseAllElasticApm` will add an `ITracer` to the Dependency Injection system, which can be used in your code to manually instrument your application, using the <<public-api>>
92
+
In the case of this sample worker service, we can update the code to prefer the OpenTelemetry API.
Similarly to this ASP.NET Core controller, you can use the same approach with `IHostedService` implementations.
124
+
<1> Defines an `ActivitySource` for this application from which activities can be created.
125
+
<2> Starts an `Activity` with the name `UnitOfWork`. As this is `IDisposable`, it will automatically end when each iteration of the `while` block ends.
75
126
76
127
[float]
77
128
==== Instrumentation modules
78
129
79
-
The `Elastic.Apm.NetCoreAll` package references every agent component that can be automatically configured. This is usually not a problem, but if you want to keep dependencies minimal, you can instead reference the `Elastic.Apm.Extensions.Hosting` package and use the `UseElasticApm` method, instead of `UseAllElasticApm`. With this setup you can control what the agent will listen for.
130
+
The `Elastic.Apm.NetCoreAll` package references every agent component that can be automatically configured. This is usually not a problem, but if you want to keep dependencies minimal, you can instead reference the `Elastic.Apm.Extensions.Hosting` package and register services with `AddElasticApm` method, instead of `AddAllElasticApm`. With this setup you can explicitly control what the agent will listen for.
80
131
81
-
The following example only turns on outgoing HTTP monitoring (so, for instance, database or Elasticsearch calls won't be automatically captured):
132
+
The following example only turns on outgoing HTTP monitoring (so, for instance, database and Elasticsearch calls won't be automatically captured):
82
133
83
134
[source,csharp]
84
135
----
85
-
public static IHostBuilder CreateHostBuilder(string[] args) =>
<1> The `HttpDiagnosticsSubscriber` is a diagnostic listener that captures spans for outgoing HTTP requests.
91
149
92
150
[float]
93
151
[[zero-code-change-setup]]
94
152
==== Zero code change setup on .NET Core and .NET 5+ (added[1.7])
95
153
96
-
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 or .NET 5 or newer.
154
+
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.
97
155
98
156
To configure startup hooks
99
157
@@ -109,9 +167,9 @@ set DOTNET_STARTUP_HOOKS=<path-to-agent>\ElasticApmAgentStartupHook.dll <1>
109
167
110
168
. Start your .NET Core application in a context where the `DOTNET_STARTUP_HOOKS` environment variable is visible.
111
169
112
-
With this setup the agent will be injected into the application during startup and it will start every auto instrumentation feature. On ASP.NET Core (including gRPC), incoming requests will be automatically captured.
170
+
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).
113
171
114
172
[NOTE]
115
173
--
116
-
Agent configuration can be controlled through environment variables with the startup hook feature.
174
+
Agent configuration can be controlled through environment variables when using the startup hook feature.
0 commit comments