Skip to content

Latest commit

 

History

History
185 lines (139 loc) · 8.68 KB

setup.asciidoc

File metadata and controls

185 lines (139 loc) · 8.68 KB
Raw

Set up the Agent

The .NET Agent ships as a set of NuGet packages via nuget.org. You can add the Agent to your .NET application by referencing one of these packages.

Packages

The following packages are available:

Elastic.Apm.NetCoreAll

This is a meta package that references every other Elastic APM .NET agent package. If you plan to monitor a typical ASP.NET Core application that depends on the Microsoft.AspNetCore.All package and uses Entity Framework Core then you should reference this package. In order to avoid adding unnecessary dependencies in applications that aren’t depending on the Microsoft.AspNetCore.All package we also offer some other packages - those are all referenced by the Elastic.Apm.NetCoreAll package.

Elastic.Apm

This is the core of the agent, which we didn’t name “Core”, because someone already took that name :) This package also contains the [public-api] and it is a .NET Standard 2.0 package. We also ship every tracing component that traces classes that are part of .NET Standard 2.0 in this package, which includes the monitoring part for HttpClient. Every other Elastic APM package references this package.

Elastic.Apm.AspNetCore

This package contains ASP.NET Core monitoring related code. The main difference between this package and the Elastic.Apm.NetCoreAll package is that this package does not reference the Elastic.Apm.EntityFrameworkCore package, so if you have an ASP.NET Core application that does not use EF Core and you want to avoid adding additional unused references, you should use this package.

Elastic.Apm.EntityFrameworkCore

This package contains EF Core monitoring related code.

Elastic.Apm.AspNetFullFramework

This package contains ASP.NET (Full .NET Framework) monitoring related code.

Elastic.Apm.EntityFramework6

This package contains an interceptor that automatically creates spans for DB operations executed by Entity Framework 6 (EF6) on behalf of the application.

Elastic.Apm.SqlClient

This package contains System.Data.SqlClient and Microsoft.Data.SqlClient monitoring related code.

Quick start

ASP.NET Core

For ASP.NET Core, once you referenced the Elastic.Apm.NetCoreAll package, you can enable auto instrumentation by calling UseAllElasticApm() extension method:

using Elastic.Apm.NetCoreAll;

public class Startup
{
  public void Configure(IApplicationBuilder app, IHostingEnvironment env)
  {
    app.UseAllElasticApm(Configuration);
    //…rest of the method
  }
  //…rest of the class
}

The app.UseAllElasticApm(…​) line must be the first line in the Configure method, otherwise the agent won’t be able to properly measure the timing of your requests, and potentially complete requests may be missed by the agent.

With this you enable every agent component including ASP.NET Core tracing, monitoring of outgoing HTTP request, Entity Framework Core database tracing, etc.

In case you only reference the Elastic.Apm.AspNetCore package, you won’t find the UseAllElasticApm. Instead you need to use the UseElasticApm() method from the Elastic.Apm.AspNetCore namespace. This method turns on ASP.NET Core tracing, and gives you the opportunity to manually turn on other components. By default it will only trace ASP.NET Core requests - No HTTP request tracing, database call tracing or any other tracing component will be turned on.

In case you would like to turn on specific tracing components you can pass those to the UseElasticApm method.

For example:

app.UseElasticApm(Configuration,
	new HttpDiagnosticsSubscriber(),  /* Enable tracing of outgoing HTTP requests */
	new EfCoreDiagnosticsSubscriber()); /* Enable tracing of database calls through EF Core*/

In case you only want to use the [public-api], you don’t need to do any initialization, you can simply start using the API and the agent will send the data to the APM Server.

ASP.NET

For ASP.NET (Full .NET Framework), once you’ve referenced the Elastic.Apm.AspNetFullFramework package, you can enable auto instrumentation by including the ElasticApmModule IIS Module in your application’s web.config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <system.webServer>
        <modules>
            <add name="ElasticApmModule" type="Elastic.Apm.AspNetFullFramework.ElasticApmModule, Elastic.Apm.AspNetFullFramework" />
        </modules>
    </system.webServer>
</configuration>

By default the agent creates transactions for all HTTP requests, including the ones for static content: .html pages, images, etc. If you would like to create transactions only for HTTP requests with dynamic content, such as .aspx pages, you can add managedHandler preCondition (official documentation) as shown in the following example:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <system.webServer>
        <modules>
            <add name="ElasticApmModule" type="Elastic.Apm.AspNetFullFramework.ElasticApmModule, Elastic.Apm.AspNetFullFramework" preCondition="managedHandler" />
        </modules>
    </system.webServer>
</configuration>

You can also configure the agent using web.config as described at [configuration-on-asp-net].

Entity Framework 6

You can enable auto instrumentation for Entity Framework 6 by referencing the Elastic.Apm.EntityFramework6 package and including the Ef6Interceptor interceptor in your application’s web.config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <entityFramework>
        <interceptors>
            <interceptor type="Elastic.Apm.EntityFramework6.Ef6Interceptor, Elastic.Apm.EntityFramework6" />
        </interceptors>
    </entityFramework>
</configuration>

As an alternative to registering the interceptor via the configuration, you can register it in the application code:

DbInterception.Add(new Elastic.Apm.EntityFramework6.Ef6Interceptor());

For example, in an ASP.NET MVC application, you can place the above call in the Application_Start method.

Note
 Be careful not to execute DbInterception.Add for the same interceptor more than once, or you’ll get additional interceptor instances. For example, if you add Ef6Interceptor interceptor twice, you’ll see two spans for every SQL query.

SqlClient

You can enable auto instrumentation for System.Data.SqlClient or Microsoft.Data.SqlClient by referencing Elastic.Apm.SqlClient package and passing SqlClientDiagnosticSubscriber to the UseElasticApm method in case of ASP.NET Core as it shown in example:

app.UseElasticApm(Configuration,
	new SqlClientDiagnosticSubscriber());  /* Enable tracing of outgoing db requests */

or passing SqlClientDiagnosticSubscriber to the Subscribe method and make sure that the code is called only once, otherwise the same database call could be captured multiple times:

// you need add custom code to be sure that Subscribe called only once and in a thread-safe manner
if (Agent.IsConfigured) Agent.Subscribe(new SqlClientDiagnosticSubscriber());  /* Enable tracing of outgoing db requests */
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. In case of auto instrumentation for Microsoft.Data.SqlClient, only .NET Core is supported, at the moment.

Other .NET applications

In case you have a .NET application which is not covered above, you can still use the agent and instrument your application manually.

In those cases, you can add the Elastic.Apm package to your application and use the [public-api].