The Java SE Platform includes Java Management Extensions (JMX). JMX is a way to monitor and manage applications, devices, and services. Generally, application servers have built-in JMX metrics that you can monitor.
New Relic's Java agent offers the ability to monitor specific metrics from MBeans and attributes in your application without modifying code by using a custom instrumentation YAML file. The Java agent will read the YAML file on startup and record the specific metrics.
You can also monitor JMX with the Infrastructure JMX integration.
Requirements and access
The Java agent only sees metrics from MBeans in your current JVM. If the MBeans are being accessed remotely, or exist in a separate JVM, they will not be available to the New Relic Java agent.
Custom JMX data won't be displayed in our charts, but you can query the data and create custom charts with it.
This integration reports only simple numeric values. If you want to report other types of values, you may want to use the Infrastructure JMX integration.
File structure rules
The custom instrumentation file must be in the YAML format. Use a YAML validator to ensure the syntax is accurate before using the file with New Relic's Java agent, and follow these rules:
- YAML files are case sensitive.
- All indentations are in increments of two characters. Data in the same sections of the file must use the same level of indentation. Indent any sub-sections with two extra spaces.
- You must restart your JVM host process for changes to take effect.
Here is a summary of each property in the JMX file. For more information, see Custom JMX YAML examples.
The primary descriptive name identifying your YAML custom instrumentation file. Include one space before the
The version of the extension file. If two extensions have the same name, only the extension with the highest version will be used. Be sure the version property is on a separate line from
No value follows the property
Matches the specific MBean's object. If you are using JDK version 1.6 or higher, the
Available with New Relic's Java agent version 3.7.0 or higher. An optional property that provides the ability to name the metric used in New Relic. To use
There is no value on the metrics line. Include four spaces before metrics.
A comma-separated list of the MBean's attributes. The attribute name must match exactly. Include 6 spaces before the dash and one space between the dash and
YAML file location
The Java agent reads the YAML file on process startup. There are two ways to specify the YAML file location:
The custom metric will not work if there is more than one YAML file in the same folder as the agent. Move backups and copies to another folder when customizing.
Verify the file was read
To verify the YAML file was read by the agent:
Change the log level property to
Start up the application.
Verify that the
logs/newrelic_agent.logfile includes a statement indicating that the file was read in:Reading custom extension file /path/to/file/file.yml
If you cannot find this statement, check the location of the YAML file. Also make sure the process has read access to the file.
Verify that the file includes this statement:Adding extension with name NAME_FROM_YAML and version VERSION_FROM_YAML
If you cannot find this statement, verify that the document was parsed correctly. Also verify if there is another extension file with the same name and a higher version number.
Query and chart JMX data
You can run queries of your JMX data and use it to create custom charts. To learn more about querying this kind of data, see Query APM metrics.
Here's how to search for JMX or for the direct path to the counter as set in your YAML file.
For more information about how metrics are named and stored, see Custom JMX YAML examples.