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.

For all available New Relic APIs, see Intro to APIs.

Requirements

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.

      OR

    • 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 AddCustomParameter().

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. Also see the New Relic's troubleshooting tips for missing async metrics.
Trace an async method that New Relic is not instrumenting Use an XML file to instrument async methods in IIS apps. Also see the New Relic's troubleshooting tips for missing async metrics.

View calls to external services (via distributed tracing or cross application tracing)

For .Net agent version 8.9 or higher, distributed tracing payload APIs are available. You can use the distributed tracing API calls below to manually pass distributed tracing context between New Relic-monitored services that don't automatically connect to one another in a distributed trace. For an introduction to distributed tracing, see Intro to distributed tracing.

If you want to... Do this...
Instrument an outgoing request to an external application or database Create a distributed trace payload to attach to an outgoing request using CreateDistributedTracePayload().
Connect incoming requests with the originator of the request to complete a span of the trace Receive a payload on an incoming request using AcceptDistributedTracePayload().

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

New Relic 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 New Relic Insights Create a custom event. See RecordCustomEvent().
Tag your events with metadata to filter and facet them in Insights 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 Metric explorer in New Relic Insights.

Control the New Relic Browser agent

Usually the Browser 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 New Relic Browser.

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

For more help

Recommendations for learning more: