.NET Core
edit.NET Core
editQuick start
editOn .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 background tasks. In this case, you need to reference the Elastic.Apm.NetCoreAll
package.
using Elastic.Apm.NetCoreAll; namespace MyApplication { public class Program { public static IHostBuilder CreateHostBuilder(string[] args) => Host.CreateDefaultBuilder(args) .ConfigureWebHostDefaults(webBuilder => { webBuilder.UseStartup<Startup>(); }) .UseAllElasticApm(); public static void Main(string[] args) => CreateHostBuilder(args).Build().Run(); } }
With the UseAllElasticApm()
, the agent with all its components is turned on. On ASP.NET Core, it217;ll automatically capture incoming requests, database calls through supported technologies, outgoing HTTP requests, and so on.
Manual instrumentation
editThe 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
using Elastic.Apm.Api; namespace WebApplication.Controllers { public class HomeController : Controller { private readonly ITracer _tracer; //ITracer injected through Dependency Injection public HomeController(ITracer tracer) => _tracer = tracer; public IActionResult Index() { //use ITracer var span = _tracer.CurrentTransaction?.StartSpan("MySampleSpan", "Sample"); try { //your code here } catch (Exception e) { span?.CaptureException(e); throw; } finally { span?.End(); } return View(); } } }
Similarly to this ASP.NET Core controller, you can use the same approach with IHostedService
implementations.
Instrumentation modules
editThe 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.
The following example only turns on outgoing HTTP monitoring (so, for instance, database or Elasticsearch calls won217;t be automatically captured):
public static IHostBuilder CreateHostBuilder(string[] args) => Host.CreateDefaultBuilder(args) .ConfigureWebHostDefaults(webBuilder => { webBuilder.UseStartup<Startup>(); }) .UseElasticApm(new HttpDiagnosticsSubscriber());
Zero code change setup on .NET Core and .NET 5+ ( [1.7] Added in 1.7. )
editIf you can217;t or don217;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.
To configure startup hooks
-
Download the
ElasticApmAgent_<version>.zip
file from the Releases page of the .NET APM Agent GitHub repository. You can find the file under Assets. - Unzip the zip file into a folder.
-
Set the
DOTNET_STARTUP_HOOKS
environment variable to point to theElasticApmAgentStartupHook.dll
file in the unzipped folder -
Start your .NET Core 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 and it will start every auto instrumentation feature. On ASP.NET Core (including gRPC), incoming requests will be automatically captured.
Agent configuration can be controlled through environment variables with the startup hook feature.