Troubleshooting

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 you are not using a supported 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.

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.

New Relic's Java agent supports two methods of 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.

XML: Define the methods you want New Relic to instrument in an XML file. XML instrumentation does not require modifying your source code, but is more complicated to create and keep updated than attribute instrumentation.

New Relic's Python agent supports two methods of 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.

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: