Java custom instrumentation

New Relic APM for Java will typically produce useful performance data out of the box. However, if New Relic does not support your framework, or if you want to set up additional monitoring, you will want to implement custom instrumentation.

When to choose 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 metrics from many frameworks automatically. If you are using a supported framework, you should not need custom instrumentation to collect metrics and transactions.

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 sufficient detail.

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

Implement custom instrumentation

If New Relic for Java does not support your framework, or you want to expand the default instrumentation, you can implement custom instrumentation with one of these methods:

  • API annotation: Use the Java agent API to add @Trace annotations to your code to ensure New Relic instruments specific methods.
  • XML: Define the methods you want New Relic to monitor in an XML file.
  • Instrumentation editor: Define an XML instrumentation file via the New Relic UI.

Collecting too many metrics can impact the performance of both your application and New Relic. To avoid potential data problems, try to keep the total number of unique metrics introduced by custom instrumentation under 2000.

Instrument via the UI

New Relic for Java includes an option in the UI for custom instrumentation called the Custom Instrumentation Editor. This option doesn't require any direct modification of your application code, so is a good choice if you don't want to or can't modify your code. The editor is, however, fairly limited in functionality compared to the Java agent API.

Instrument using API annotation

Using the New Relic Java agent API, you can annotate the methods in your application code that you want to monitor. The annotation method is robust and easy to troubleshoot. If you are willing to modify your source code, annotation is the recommended method. If you have many methods you want to instrument, you might prefer XML instrumentation.

For more about the API and its other functions, see Intro to the Java agent API.

Instrument with XML

If you can't modify your code, or if you need to instrument many methods, XML instrumentation is the best custom instrumentation method. With this method, you specify the classes you want to instrument in an external XML file.

While XML instrumentation is powerful, it is also more difficult to use than the other instrumentation methods. For simpler instrumentation needs, New Relic recommends annotation or instrumentation via the UI. For more information, see Java instrumentation by XML.

Instrument JMX

You can also monitor Java Management Extensions (JME) via custom instrumentation. JMX is a way to monitor and manage applications, devices, and services. You can implement JMX monitoring via an external YAML file.

For more help

Join the discussion about Java monitoring 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