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 codetime without sufficient detail.
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
@Traceannotations 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.
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.