When you develop an ASP.NET Core application, a pipeline is built by connecting the configured middleware components together.
By default (for example, when you re-use the standard template application startup code), you do not have to define how to build the pipeline or the sequence of middleware components in this pipeline. Everything works as defined. For applications with more complex processing demands, you would typically modify the middleware pipeline and consider how the .NET Agent instruments ASP.NET Core applications. See middleware pipeline information from the Microsoft site.
The .NET Agent can instrument this middleware pipeline at different points along the pipeline. Each instrumentation option provides advantages and disadvantages:
- Resource invoker instrumentation
- Endpoint instrumentation
- HTTP instrumentation
- MVC routing instrumentation
Resource Invoker Instrumentation
- Default setting for ASP.NET Core 2.x.
- For ASP.NET Core 3.x and 5.0, set the node property
aspdotnet-core-instrumentation (string) = "ResourceInvoker"to enable it.
This instrumentation occurs at the end of the pipeline just before it calls the controller action or page handler. This applies to Razor Page handlers, and MVC and Web API controller actions.
The advantage is that only actual action code is instrumented, and the .NET Agent instrumentation does not execute for any other web requests such as: static files and not found paths (
Error Code 404).
This is the most lightweight instrumentation option. It is the optimal choice for most ASP.NET Core applications, especially where minimal or no customization was applied to the middleware pipeline from the default application code.
- Default setting for ASP.NET Core 3.x and 5.0 (as of .NET Agent 21.3).
- Not available for ASP.NET Core 2.x.
With the improved endpoint routing introduced in ASP.NET Core 2.2, all routing for Web API, MVC, and Razor Pages was merged into a new architecture enabling the .NET Agent to perform instrumentation just after the
The advantage of using Endpoint instrumentation (instead of Resource Invoker instrumentation) is that the Business Transaction is tracked through the execution of all middleware after the
EndpointRoutingMiddleware. This provides more visibility into operations performed before the controller action is executed. This includes only middleware that participates in the routing process such as authentication and authorization, but excludes middleware such as health checks, serving up static files, and so on.
Endpoint instrumentation balances full pipeline visibility (which may introduce too much noise and overhead) with no visibility (using Resource Invoker instrumentation).
- This setting is available for ASP.NET Core 2.x, 3.x, and 5.0 (as of .NET Agent 21.3).
- Set the node property
aspdotnet-core-instrumentation (string) = "HTTP"to enable it.
This instrumentation option instruments the full middleware pipeline by instrumenting every single web request. It provides the most visibility of all options. However, when enabling this option, you must consider:
- MVC naming is not possible because the request URL has not been decoded by the routing middleware. It may not be an MVC request; if it is, then controller and action names have not been resolved. All business transactions will use the URL path as its name.
- Because the .NET Agent instrumentation runs and inspects every web request (even requests that result with
404 Errors, and so on), it has a greater performance impact on the application. To understand the performance impact, you should test this option either in a pre-production environment, or on a limited node count before you enable the option for the entire tier or application.
MVC Routing Instrumentation
- This is the original instrumentation option introduced for ASP.NET Core 1.x. It is the default setting for ASP.NET Core 1.x, and a configurable option for 2.x.
- Set the node property
aspdotnet-core-instrumentation (string) = "Legacy"to enable this for ASP.NET Core 2.x.
The MVC Routing instrumentation functionality has been deprecated with ASP.NET Core 3.0. It provides full pipeline visibility by instrumenting from the first middleware in the pipeline. However, when attempting to do MVC naming of incoming web requests, it may cause issues. It assumes that you built the middleware pipeline in a specific way, and contains very specific middleware request delegates.
If you are using ASP.NET Core 2.x, and need full pipeline visibility with MVC naming, then this is the only available option for you.