Introduction to .NET custom instrumentation

The New Relic for .NET agent automatically collects and reports information on web transactions and browser tasks. For supported frameworks, this automatic instrumentation usually collects the detail you need without any configuration.

However, if you are using a framework that does not have default instrumentation, you may see large blocks of time in the New Relic UI without full detail, or you may not see any transactions at all. In this case, you can use custom instrumentation to fill in those gaps.

This document describes how to instrument work that's not instrumented by default. For other ways of configuring your app's instrumentation, see Guide to using the .NET agent API.

Choose a method of custom instrumentation

The .NET agent supports two methods of custom instrumentation:

Method Description
Attribute custom instrumentation

Instrument your code by decorating your methods with an attribute. Attribute instrumentation is simpler to implement than XML instrumentation, because you only need to add a single decorator, in the same place in your code as the method you want to instrument.

For instructions, see Custom instrumentation via attributes.

XML custom instrumentation

Instrument your code by listing the target methods in an XML file. XML instrumentation is more complex than attribute instrumentation, and it will fail if you change the name of the assembly, class, or method you want to instrument. However, XML instrumentation does not require you to modify your source code.

For instructions, see Create transactions via XML and Add detail to transactions via XML.

Creating transactions vs. adding detail

When you add custom instrumentation via either method, you need to choose between creating a new transaction and adding instrumentation to an existing transaction:

Situation Recommendation
The method you want to instrument does not appear in the New Relic UI at all

Create a new transaction. For details, see:

The transaction appears in the New Relic UI but contains sections of uninstrumented time

Add detail to an existing transaction. For details, see:

Web vs. non-web transactions

New Relic APM separates "web" and "non-web" transactions in the UI. When you add detail to an existing transaction, the category is determined by the category of the parent transaction.

However, when you create a transaction via custom instrumentation, you must categorize it as web or non-web:

Category When to use

Use web for web requests.


Use non-web (also known as background) for other types of requests, such as console apps and services.

For more help

Recommendations for learning more: