| title | tags | metaDescription | redirects | freshnessValidatedDate | ||||||
|---|---|---|---|---|---|---|---|---|---|---|
Custom JMX YAML examples |
|
Example of a custom JMX YAML file for New Relic's Java agent: value and definition, MBean, attributes, type, and names for metrics, objects, and attributes. |
|
never |
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.
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 <th>
<DoNotTranslate>**Definition**</DoNotTranslate>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
`name`
</td>
<td>
A descriptive name identifying your YAML custom instrumentation file, using one space before the property name. In the above example, the name is `TomcatCustom`.
</td>
</tr>
<tr>
<td>
`version`
</td>
<td>
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`.
</td>
</tr>
<tr>
<td>
`enabled`
</td>
<td>
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.
</td>
</tr>
</tbody>
</table>
<Collapser id="example_mbeans" title="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:
```yml
- 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:
```yml
- object_name: Catalina:type=Cache,host=localhost,path=/examples
```
The following line could match multiple MBeans:
```yml
- 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=*
```
<Collapser id="example_attributes" title="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.
<Collapser id="example_type" title="Type"
For `type`, use `simple` or `monotonically_increasing`. When `type` is not specified in the JMX YAML file, it defaults to `monotonically_increasing`.
<table>
<thead>
<tr>
<th width={200}>
Value
</th>
<th>
Definition
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
`simple`
</td>
<td>
The exact value of the attribute will be reported to New Relic each minute.
</td>
</tr>
<tr>
<td>
`monotonically_increasing`
</td>
<td>
The positive difference will be reported to New Relic each minute.
</td>
</tr>
</tbody>
</table>
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.
<Collapser id="metric_names" title="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
```
<Callout variant="tip">
Some object names do not include a type. In that case, a null will be present in the metric name.
</Callout>
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:
```yml
- 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.
The easiest way to find available MBeans and its associated attributes is to use the JConsole instructions for JDK 1.6.
| **Value** |
|---|