Custom JMX instrumentation by YAML

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.

Requirements

In order to view custom JMX metrics, use the Insights Metric Explorer to search and create customized charts.

Access to this feature depends on your subscription level.

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.

Video

To learn more about importing JMX data into New Relic, watch this video (approximately seven minutes).


[video link] To learn more about importing JMX data into New Relic, watch this video (approximately 7 minutes). View more videos and tutorials at learn.newrelic.com.

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 stanza of the file must use the same level of indentation. Indent any sub-stanzas by an additional two spaces.
  • You must restart your JVM host process for changes to take effect.

Available properties

Here is a summary of each property in the JMX file. For more information, see Custom JMX YAML examples.

Value Definition
name The primary descriptive name identifying your YAML custom instrumentation file. Include one space before the name property.
version 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 name. Include one space before the version property.
enabled If true, the Java agent will read the extension. If false, the Java agent will ignore the extension. Include one space before the enabled property.
jmx No value follows the property jmx. Use zero spaces before the property.
object_name Matches the specific MBean's object. If you are using JDK version 1.6 or higher, the object_name can include asterisks (*). Include two spaces before the dash and one space between the dash and object_name.
root_metric_name 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 object_name property values, specify the property key in brackets({}). New Relic will automatically prefix the root_metric_name specified with JMX and append the attribute name to the end of the metric. Include four spaces before root_metric_name.
metrics There is no value on the metrics line. Include four spaces before metrics.
attributes 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 attributes keyword.
type
  • If simple, each value will be reported to the New Relic collector each minute.
  • If monotonically_increasing (default), the positive difference will be reported to the New Relic collector each minute.

YAML file location

The Java agent reads the YAML file on process startup. There are two ways to specify the YAML file location:

Create an extensions directory
  1. In the directory where the newrelic.jar and newrelic.yml are located, create a directory named extensions.
  2. Put the YAML file in this directory with a .yml extension.
  3. In newrelic.yml, check that the property extensions.dir is not set.
Specify an existing extensions directory
  1. In the newrelic.yml configuration file under the common section, use the property extensions.dir to specify the directory where the YAML file is located.
  2. Make sure the file is in the specified directory and that the file has a .yml extension.

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:

  1. Open the newrelic.yml configuration file.
  2. Change the log level property to log_level: finer.
  3. Start up the application.
  4. Verify that the logs/newrelic_agent.log file includes a statement indicating that the file was read in:

      Reading custom extension file /path/to/file/file.yml
  5. If you cannot find this statement, check the location of the YAML file. Also make sure the process has read access to the file.
  6. Verify that the file includes this statement:

      Adding extension with name NAME_FROM_YAML and version VERSION_FROM_YAML
  7. 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.

For more help

Additional documentation resources include:

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 support.newrelic.com.