Set up ASP.NET instrumentation

For the full compatibility matrix including supported installation methods, refer to Web frameworks.

To enable tracing for ASP.NET (.NET Framework), 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 package.

2. Reference the Elastic.Apm.AspNetFullFramework in your application’s web.config file by adding the ElasticApmModule IIS module:

   <?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>
   		

   Note

   There are two available configuration sources. To learn more, see Configuration on ASP.NET.

   By default, the agent creates transactions for all HTTP requests, including static content: .html pages, images, and so on.

   To create transactions only for HTTP requests with dynamic content, such as .aspx pages, add the managedHandler preCondition to your web.config file:

   <?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>
   		

   Note

   To learn more about adding modules, see the Microsoft docs.

<runtime>
  <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
    <dependentAssembly>
      <assemblyIdentity name="System.Diagnostics.DiagnosticSource" publicKeyToken="cc7b13ffcd2ddd51" culture="neutral" />
      <bindingRedirect oldVersion="0.0.0.0-8.0.0.1" newVersion="8.0.0.1" />
    </dependentAssembly>
    <dependentAssembly>
      <assemblyIdentity name="System.Threading.Tasks.Dataflow" publicKeyToken="b03f5f7f11d50a3a" culture="neutral" />
      <bindingRedirect oldVersion="0.0.0.0-8.0.0.1" newVersion="8.0.0.1" />
    </dependentAssembly>
    <dependentAssembly>
      <assemblyIdentity name="System.Diagnostics.PerformanceCounter" publicKeyToken="cc7b13ffcd2ddd51" culture="neutral" />
      <bindingRedirect oldVersion="0.0.0.0-8.0.0.1" newVersion="8.0.0.1" />
    </dependentAssembly>
    <dependentAssembly>
      <assemblyIdentity name="System.Reflection.Metadata" publicKeyToken="b03f5f7f11d50a3a" culture="neutral" />
      <bindingRedirect oldVersion="0.0.0.0-8.0.0.1" newVersion="8.0.0.1" />
    </dependentAssembly>
    <dependentAssembly>
      <assemblyIdentity name="System.Collections.Immutable" publicKeyToken="b03f5f7f11d50a3a" culture="neutral" />
      <bindingRedirect oldVersion="0.0.0.0-8.0.0.0" newVersion="8.0.0.0" />
    </dependentAssembly>
    <dependentAssembly>
      <assemblyIdentity name="System.Runtime.CompilerServices.Unsafe" publicKeyToken="b03f5f7f11d50a3a" culture="neutral" />
      <bindingRedirect oldVersion="0.0.0.0-6.0.0.0" newVersion="6.0.0.0" />
    </dependentAssembly>
    <dependentAssembly>
      <assemblyIdentity name="System.Threading.Tasks.Extensions" publicKeyToken="cc7b13ffcd2ddd51" culture="neutral" />
      <bindingRedirect oldVersion="0.0.0.0-4.2.0.1" newVersion="4.2.0.1" />
    </dependentAssembly>
    <!-- The next two entries apply only to applications targeting .NET Framework 4.6.2, where the agent brings these two
         packages. Include them only when the corresponding assemblies are present in your bin folder. -->
    <dependentAssembly>
      <assemblyIdentity name="System.ValueTuple" publicKeyToken="cc7b13ffcd2ddd51" culture="neutral" />
      <bindingRedirect oldVersion="0.0.0.0-4.0.5.0" newVersion="4.0.5.0" />
    </dependentAssembly>
    <dependentAssembly>
      <assemblyIdentity name="System.Runtime.InteropServices.RuntimeInformation" publicKeyToken="b03f5f7f11d50a3a" culture="neutral" />
      <bindingRedirect oldVersion="0.0.0.0-4.0.1.0" newVersion="4.0.1.0" />
    </dependentAssembly>
  </assemblyBinding>
</runtime>
		

1. Recompile your application and deploy it.

   The ElasticApmModule instantiates the APM .NET Agent on the first initialization. However, there might be some scenarios where you want to control the agent instantiation, such as configuring filters in the application start.

   To do so, the ElasticApmModule exposes a CreateAgentComponents() method that returns agent components configured to work with ASP.NET Full Framework, which can then instantiate the agent.

   For example, you can add transaction filters to the agent in the application start:

   using Elastic.Apm;
   using Elastic.Apm.Api;
   using Elastic.Apm.AspNetFullFramework;
   
   public class MvcApplication : HttpApplication
   {
       protected void Application_Start()
       {
           // other application startup for example, RouteConfig, and so on.
   
           // set up agent with components
           var agentComponents = ElasticApmModule.CreateAgentComponents();
           Agent.Setup(agentComponents);
   
           // add transaction filter
           Agent.AddFilter((ITransaction t) =>
           {
               t.SetLabel("foo", "bar");
               return t;
           });
       }
   }
   		

   Now, the ElasticApmModule will use the instantiated instance of the APM .NET Agent upon initialization.

After adding the agent, configure it to connect to your APM Server. The fastest way is through environment variables or web.config. See Minimum configuration for the three settings every deployment needs.

For the full list of configuration options available to ASP.NET applications, see Configuration on ASP.NET.