.NET Coreedit

Quick startedit

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 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, it’ll automatically capture incoming requests, database calls through supported technologies, outgoing HTTP requests, and so on.

Manual instrumentationedit

The UseAllElasticApm will add an ITracer to the Dependency Injection system. This means you can use the Public API in your code to manually instrument your application:

using Elastic.Apm.Api;

namespace WebApplication.Controllers
{
    public class HomeController : Controller
    {
        private readonly ITracer _tracer;
        public HomeController(ITracer tracer) //inject ITracer
        => _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 modulesedit

The Elastic.Apm.NetCoreAll will reference every agent component. This is usually not a problem, but if you want to keep dependencies minimal, you can also reference the Elastic.Apm.Extensions.Hosting and use the UseElasticApm method instead of UseAllElasticApm. With this 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 won’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 ( [1.7] Added in 1.7. )edit

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. This feature is supported on .NET Core 2.2 and newer versions.

Steps:

  1. Download the ElasticApmAgent_[version].zip file from the Releases page of the .NET APM Agent GitHub repository. You can find the file under Assets.
  2. Unzip the zip file into a folder.
  3. Set the DOTNET_STARTUP_HOOKS environment variable to point to the ElasticApmAgentStartupHook.dll file in the unzipped folder
set DOTNET_STARTUP_HOOKS=[pathToAgent]\ElasticApmAgentStartupHook.dll
  1. 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.