Custom JMX YAML examples

This is an example of a custom JMX YAML file for New Relic's Java agent, including value and definition, MBean, attributes, type, and names for metrics, objects, and attributes. For more information, including a video, see Custom JMX monitoring by YAML.

YAML example

Here is an example of a custom JMX YAML file. YAML files are space senstive.

name: TomcatCustom
version: 1.0
enabled: true
jmx:
  - object_name: Catalina:type=Cache,host=localhost,path=/examples
    metrics:
      - attributes: accessCount, cacheSize, hitsCount
        type: simple
  - object_name: Catalina:type=Connector,port=8009
    metrics:
      - attributes: bufferSize, maxHeaderCount
  - object_name: java.nio:type=BufferPool,name=*
    metrics:
      - attributes: Count
        type: monotonically_increasing

Example explanation

Properties
Value Definition
name A descriptive name identifying your YAML custom instrumentation file, using one space before the property name. In the above example, the name is TomcatCustom.
version The version of the extension file. Use a double. If two extensions have the same name, only the extension with the highest version will be used. Use one space before the property version. In the above example, the version is 1.0.
enabled If true, the Java agent will read the extension. If false, the Java agent will ignore the extension. Use one space before the property enabled. The above example is enabled.
MBeans

Each line in the YAML starting with - object_name represents an MBean. For example, the following lines describe the information to be pulled from the first MBean:

 - object_name: Catalina:type=Cache,host=localhost,path=/examples
    metrics:
      - attributes: accessCount, cacheSize, hitsCount
        type: simple

The object_name property itself can match one or more MBeans. For example, the line below only matches one MBean:

  - object_name: Catalina:type=Cache,host=localhost,path=/examples

The following line could match multiple MBeans:

  - object_name: java.nio:type=BufferPool,name=*

The asterisk (*) wildcard can only be used with JDK 1.6 and higher.

The three MBeans listed in the above example have the following object names:

Catalina:type=Cache,host=localhost,path=/examples
Catalina:type=Connector,port=8009
java.nio:type=BufferPool,name=*
Attributes

The JMX example retrieves six different attributes from the three MBeans. New Relic's Java agent pulls these attributes from the first MBean:

  • accessCount
  • cacheSize
  • hitsCount

The agent pulls these attributes from the second MBean:

  • bufferSize
  • maxHeaderCount

The agent pulls one attribute (Count) from third MBean.

Type

For type, use simple or monotonically_increasing. When type is not specified in the JMX YAML file, it defaults to monotonically_increasing.

Value Definition
simple The exact value of the attribute will be reported to New Relic each minute.
monotonically_increasing The positive difference will be reported to New Relic each minute.

In the example above, the attributes accessCount, cacheSize, and hitsCount will be reported as simple. The attributes bufferSize, maxHeaderCount, and Count will be reported as monotonically_increasing.

  • If the hitsCount attribute value is always 5, then New Relic will report a 5 each minute.
  • If the Count attribute value is always 5, then New Relic will report a 0 for the value each minute.
  • If the Count attribute value changes from 5 to 7, then New Relic will report a 2 for that minute.
Metric names

When selecting custom dashboard metrics and not using the property root_metric_name, use the following format for all custom JMX metrics:

JMX/beginning_of_object_name/type/any_properties_in_object_name/attribute_name

Some object names do not include a type. In that case, a null will be present in the metric name.

The configuration file does not use root_metric_name, so the following metrics will be created:

JMX/Catalina/Cache/localhost/examples/accessCount
JMX/Catalina/Cache/localhost/examples/cacheSize
JMX/Catalina/Cache/localhost/examples/hitsCount
JMX/Catalina/Connector/8009/bufferSize
JMX/Catalina/Connector/8009/maxHeaderCount
JMX/java.nio/BufferPool/direct/Count
JMX/java.nio/BufferPool/mapped/Count

If you are using the property root_metric_name, then the metric will be your root metric name prefixed with JMX and followed by the attribute's name. You can use object name values by specifying the object name key in the root_metric_name between brackets {}. For example:

Part of a configuration file:

  - object_name: Catalina:type=Cache,host=localhost,path=/examples
    root_metric_name: Tomcat/{host}
    metrics:
      - attributes: accessCount, cacheSize, hitsCount
        type: simple
- object_name: mbean:type=Sample,host=localhost,path=*
    root_metric_name: SampleMBean
    metrics:
      - attributes: attOne, attTwo
        type: simple

Metric names:

  JMX/Tomcat/localhost/accessCount
  JMX/Tomcat/localhost/cacheSize
  JMX/Tomcat/localhost/hitsCount
  JMX/SampleMBean/attOne
  JMX/SampleMBean/attTwo

If an attribute does not actually exist on the MBean, then the metric will never appear in New Relic.

Finding object and attribute names

The easiest way to find available MBeans and its associated attributes is to use the JConsole instructions for JDK 1.6.

For more help

Additional documentation resources include:

Recommendations for learning more: