Custom instrumentation via attributes (.NET)

New Relic's .NET agent provides several options for custom instrumentation. Custom instrumentation allows you to instrument parts of your app that are not instrumented automatically. This document describes decorate the methods in your app code with attributes to instrument your app:

  • Use the Transaction attribute to create a custom transaction. You can also mark the custom transaction as a web transaction with the the attribute's Web property.
  • Use the Trace attribute to add custom instrumentation to methods that are invoked within a preexisting transaction.

Check out this post on Building custom instrumentation tracer factories from .NET agent log files on the New Relic Explorer's Hub.


Requirements include:

  • You must have the .NET agent version or higher.

  • To use attributes for custom instrumentation, you must modify your source code. If you cannot or do not want to modify your source code, use custom instrumentation via XML.

  • Your project must have a reference to NewRelic.Api.Agent.dll. This package is in the NuGet gallery.
  • The Transaction and Trace attributes must be applied to concrete implementations of methods. They cannot be applied on interfaces or super class method definitions.

Create a new non-web transaction

To start a non-web transaction (also known as a background request) with the Transaction attribute:

public void Run()
  // your background task

Create a new web transaction

To tell the agent to mark a non-web task as a web browser transaction, use either of these options:

  • Set the Web property of the Transaction attribute to true.
  • Set the transaction's URI with SetTransactionUri().
[Transaction(Web = true)]
public void Run()
  var uri = new Uri("");
  // your web task

When used inside a previously started transaction, this will be treated as a [Trace] attribute .

Add detail to existing transactions

If your transaction traces show large blocks of uninstrumented time and you want to include additional methods within the trace, you can use the Trace attribute:

protected void MethodWithinTransaction()
  // your app code

Properties for [Transaction]

The Transaction attribute supports the following properties:

Type: Boolean
Default: false

If true, the agent starts a web transaction when it reaches this Transaction attribute. If a transaction is in progress, then that transaction will continue.

If false (default), the agent starts a non-web transaction when it reaches this Transaction attribute. For example:

[Transaction(Web = true)]

Use other API functions

For more about the .NET agent API and its functionality, see New Relic's .NET agent API guide. For custom instrumentation without modifying your source code, see Create transactions via XML and Add detail to transactions via XML.

For more help

Recommendations for learning more: