Custom instrumentation

New Relic collects and reports information on web browser transactions and background tasks. New Relic normally produces complete information right out of the box without any need to modify your application code. However, if New Relic does not support your framework, you may need to add custom instrumentation.

Custom instrumentation is also useful to:

  • Add detail to your transaction traces.
  • Block instrumentation on selected transactions you do not want instrumented.
  • Instrument a part of your code that New Relic simply is not picking up.

Custom instrumentation that creates a new transaction collects both metric timeslice and event data. Custom instrumentation for already instrumented transactions collects only metric timeslice data.

Do not use brackets [suffix] at the end of your transaction name. New Relic automatically strips brackets from the name. Instead, use parentheses (suffix) or other symbols if needed.

Choosing custom instrumentation

Custom instrumentation allows you to track interactions that aren't captured by New Relic's automatic instrumentation. Custom instrumentation can also add detail to your transaction traces, to help you identify key issues.

New Relic collects data from many frameworks automatically. If you are using a supported framework, you should not need custom instrumentation to collect metric timeslices, events, and traces.

If you encounter one of these situations, you may need custom instrumentation:

  • Transactions do not appear in the UI.
  • Transaction traces include large blocks of application code time without full detail.

If you are using a supported framework, but are not seeing transactions, get support at support.newrelic.com to ensure the framework instrumentation is working.

Implementing custom instrumentation

Each agent implements custom instrumentation differently:

Go custom instrumentation

Because Golang apps run from a compiled, native binary file, all New Relic instrumentation must be done manually. See Instrument Go transactions and Instrument Go segments for how to set up instrumentation in your Go app.

Java custom instrumentation

New Relic's Java agent supports two techniques for custom instrumentation:

  • Annotation: Add @Trace annotations to your code to ensure New Relic instruments specific methods. Annotation is easy to implement, if you are instrumenting only a few methods. For more complex instrumentation, or if you are unable to modify your code, use XML.
  • XML: Define the methods you want New Relic to monitor in an XML file. XML instrumentation is flexible and doesn't require editing your code, but is more difficult to troubleshoot than annotation.

For more information, see Java custom instrumentation.

.NET custom instrumentation

New Relic's .NET agent defines custom instrumentation in extension files. You can define the assembly, class, and method names you want to trace by using one or more method tracers (tracerFactory).

New Relic reads every XML file in the extensions directory for custom instrumentation. You can use an XML-aware editor such as Visual Studio, and pair it with the companion file extension.xsd.

For more information, see .NET custom instrumentation.

Node.js custom instrumentation

New Relic's Node.js agent uses API calls for custom instrumentation. For more information, see Node.js custom instrumentation.

PHP custom instrumentation

New Relic's PHP agent uses API calls for custom instrumentation. For more information, see PHP custom instrumentation.

Python custom instrumentation

New Relic's Python agent supports two techniques for custom instrumentation:

  • Configuration file: Use the agent configuration file to specify the functions and methods you want instrumented. The agent configuration file is easy to set up, and it does not require you to modify your code. However, it is less flexible than API calls.
  • API calls: Edit your code to call the New Relic Python API. The API is more flexible than instrumentation via the configuration file, but it requires you to modify your code.

For more information, see Python custom instrumentation.

Ruby custom instrumentation

New Relic's Ruby agent uses API calls to define target methods and add transaction tracers to them. For more information, see Ruby custom instrumentation.

Grouping issues

A metric grouping issue occurs when an account sends too many differently-named metric timeslices to New Relic, and those individual web transactions are not properly aggregated. For example, rather than a single /user/controlpanel/ metric name, you might see /user/controlpanel/alice, /user/controlpanel/bob, and /user/controlpanel/carol.

Custom instrumentation can cause metric grouping issues if you introduce too many uniquely-named metric timeslices that New Relic cannot effectively group. If you send thousands of metrics, New Relic may apply rules to reduce the number of transactions. For more information, see Metric grouping issues.

For more help

In addition to the agent documentation noted above, documentation resources for using custom instrumentation include:

Join the discussion about New Relic APM in the New Relic Online Technical Community! The Technical Community is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at support.newrelic.com.