• EnglishEspañol日本語한국어Português
  • Log inStart now

Guide to using the .NET agent API

New Relic's .NET agent includes an API that allows you to extend the agent's standard functionality. For example, you can use the .NET agent API for:

  • Customizing your app name
  • Creating custom transaction parameters
  • Reporting custom errors and metrics

You can also customize some of the .NET agent's default behavior by adjusting configuration settings or using custom instrumentation.



As of September 2021, a small subset of APIs, configuration options, and installation options for .NET will be replaced by new methods. For more details, including how you can easily prepare for this transition, see our Support Forum post.

To use the .NET agent API:

  1. Make sure you have the latest .NET agent release.

  2. Add a reference to the agent in your project:

    • Add a reference to NewRelic.Api.Agent.dll to your project.


    • View and download the API package from the NuGet Package Library.

Instrument missing sections of your code with transactions

To instrument your app, New Relic separates each path through your code into its own transaction. New Relic times (or "instruments") the parent method in these transactions to measure your app's overall performance, and collects transaction traces from long-running transactions for additional detail.

Use these methods when New Relic is not instrumenting a particular part of your code at all:

If you want to...

Do this...

Prevent a transaction from reporting to New Relic

Use IgnoreTransaction() or an XML file to ignore the transaction.

Create a transaction where none exists

Use attributes or an XML file to create a new transaction.

Time specific methods using segments

If a transaction is already visible in the New Relic UI, but you don't have enough data about a particular method that was called during that transaction, you can create segments to time those individual methods in greater detail. For example, you might want to time a particularly critical method with complex logic.

When you want to instrument a method within an existing transaction, see Custom instrumentation via attributes or Add detail to transactions via XML.

Enhance the metadata of a transaction

Sometimes the code you are targeting is visible in the New Relic UI, but some details of the method are not useful. For example:

Use these methods when you want to change how New Relic instruments a transaction that's already visible in the New Relic UI:

If you want to...

Do this...

Change the name of a transaction

Use SetTransactionName() or an XML file.

Prevent a transaction from affecting your Apdex score

Use IgnoreApdex().

Add metadata (such as your customer's account name or subscription level) to your transactions

Use custom attributes. See AddCustomAttribute().

See related logs

To see logs directly within the context of your application's errors and traces, use these API calls to annotate your logs:

For more information about correlating log data with other telemetry data, see our logs in context documentation.

Instrument asynchronous work

For supported frameworks, the .NET agent usually detects async work and instruments it correctly. However, if your app uses another framework, or the default async instrumentation is inaccurate, you can explicitly connect async work.

If you want to...

Do this...

Trace an async method that New Relic is already instrumenting

Use an XML file to instrument async methods in IIS apps. For troubleshooting tips, see missing async metrics.

Trace an async method that New Relic is not instrumenting

Use an XML file to instrument async methods in IIS apps. For troubleshooting tips, see missing async metrics.

View calls to external services

For .NET agent version 8.9 or higher, you can use the following distributed tracing payload APIs to manually pass distributed tracing context between New Relic-monitored services that don't automatically connect to one another in a distributed trace.

If you want to...

Do this...

Instrument an outgoing request to an external application or database

Add a distributed trace payload to an outgoing request using InsertDistributedTraceHeaders().

Connect incoming requests with the originator of the request to complete a span of the trace

Receive a payload on an incoming request using AcceptDistributedTraceHeaders().

For .NET agent versions lower than 8.9, use cross application tracing.

Collect or ignore errors

Usually the .NET agent detects errors automatically. However, you can manually mark an error with the agent. You can also ignore errors .

If you want to...

Do this...

Report an error the .NET agent does not report automatically

Use NoticeError().

Capture errors or prevent the .NET agent from reporting an error at all

Use your .NET agent configuration file.

Send custom event and metric data from your app

APM includes a number of ways to record arbitrary custom data. For an explanation of New Relic data types, see Data collection.

If you want to...

Do this...

Send data about an event so you can analyze it in dashboards

Create a custom event. See RecordCustomEvent().

Tag your events with metadata to filter and facet them in dashboards or error analytics

Add custom attributes. See .NET agent attributes and Enable and disable attributes.

Report custom performance data

Use RecordMetric() to create a custom metric. To view the data, use the query builder.

Control the browser monitoring agent

Usually the agent is added automatically to your pages or deployed by copy/pasting the JavaScript snippet. For more information about these recommended methods, see Add apps to browser monitoring.

However, you can also control the browser agent via APM agent API calls. For more information, see Browser monitoring and the .NET agent.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.