APM for Java will typically produce useful performance data automatically. 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.
Custom instrumentation allows you to track interactions that aren't captured by New Relic's automatic instrumentation, and lets you add detail to your transaction traces, to help you identify key issues.
New Relic collects metrics and events from many frameworks automatically. If you are using a supported framework or component, you may see some transaction information out of the box, and custom instrumentation can be used to supplement the information the agent reports by default.
When to choose custom instrumentation
Choose custom instrumentation in these situations:
- New Relic does not support your framework and transactions do not appear in the UI
- You would like to add detail to your transaction traces
- Transaction traces include large blocks of
application codetime without sufficient detail
Implement custom instrumentation
You can implement custom instrumentation with one of these methods:
The New Relic 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.
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.
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 (JMX) 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.