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 how to instrument your app by decorating the methods in your app code with attributes.
- Use the
Transaction
attribute to create a custom transaction. You can also mark the custom transaction as a web transaction with the attribute'sWeb
property. - Use the
Trace
attribute to add custom instrumentation to methods that are invoked within a preexisting transaction.
Requirements and recommendations
Requirements include:
- .NET agent version 6.16.178.0 or higher.
- You must be willing to modify your source code. If you can't or don't want to modify your source code, use custom instrumentation via XML.
- Your project must have a reference to
NewRelic.Api.Agent.dll
(for example, installing the package and placingusing NewRelic.Api.Agent;
in your code). This package is in the NuGet gallery. - The
Transaction
andTrace
attributes must be applied to concrete implementations of methods. They cannot be applied on interfaces or super class method definitions.
Transactions called within transactions
Methods decorated with the [Transaction]
attribute will only create a new transaction when one doesn't already exist. When a method decorated with [Transaction]
is called from within a previously started transaction, it will be treated as the [Trace]
attribute instead, and will provide more information about the existing transaction.
Create a new non-web transaction
To start a non-web transaction (also known as a background request) with the Transaction
attribute:
[Transaction]public void Run(){ // your background task}
For details about why to use either web or non-web, see Classify as web or non-web.
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 theTransaction
attribute totrue
. - Set the transaction's URI with
SetTransactionUri()
.
[Transaction(Web = true)]public void Run(){ var uri = new Uri("https://www.mydomain.com/path"); NewRelic.Api.Agent.NewRelic.SetTransactionUri(uri);
// your web task}
When used inside a previously started transaction, this will be treated as a [Trace]
attribute.
For details about why to use either web or non-web, see Classify as web or non-web.
Add detail to existing transactions with Trace
If your transaction traces show large blocks of un-instrumented time and you want to include additional methods within the trace, you can use the Trace
attribute:
[Trace]protected void MethodWithinTransaction(){ // your app code}
Important
If some of your methods don't show up in traces after adding the [Trace]
attribute, disable method inlining for those methods with [MethodImpl(MethodImplOptions.NoInlining)]
.
Important
Running your application from Visual Studio in debug mode may prevent some methods from appearing in New Relic traces. To ensure methods appear in New Relic, run the application in release mode via the command line.
Properties for Transaction
The Transaction
attribute supports the following properties:
Example: Instrument four methods
Read forum posts about instrumentation
For more specific recommendations, check out these posts in our Support Forum community:
- Troubleshoot attribute-based custom instrumentation issues
- Build custom instrumentation tracer factories from .NET agent log files
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.