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.
Contents
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. Iffalse
, 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
, usesimple
ormonotonically_increasing
. Whentype
is not specified in the JMX YAML file, it defaults tomonotonically_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
, andhitsCount
will be reported assimple
. The attributesbufferSize
,maxHeaderCount
, andCount
will be reported asmonotonically_increasing
.- If the
hitsCount
attribute value is always5
, then New Relic will report a5
each minute. - If the
Count
attribute value is always5
, then New Relic will report a0
for the value each minute. - If the
Count
attribute value changes from5
to7
, then New Relic will report a2
for that minute.
- If the
- 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 theroot_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:
- Custom instrumentation with the Java agent (method tracers, examples)
- Custom JMX monitoring by YAML (YAML file structure, value and definition)