Creating JMole config files

Overview

JMole uses XML files to get information about which JMX beans that are of interest to monitor for a specific system. These files also contains metadata for presentation purposes.

This page tries to provide an introduction to how to write your own JMole config file. Please investigate the config files provided for various platforms as references.

XML Schema

All config files are validated towards the JMole.xsd XML Schema file located in the jmole-core subproject. Use this file when using your favorite XML Editor to minimize errors.

System Properties

System properties can be specified using ${mySystemProperty} syntax and will be replaced with actual value at configuration time. The syntax ${mySystemProperty:defaultValue} is also supported meaning that if mySystemProperty is not set the provided default value will be used.

Examples

Here are some examples taken from the config file for the JVM monitoring as an introduction.

Example 1

<measurement name="Uptime" category="JVM" level="1">
    <objectNameQueries>
        <objectNameQuery>java.lang:type=Runtime</objectNameQuery>
    </objectNameQueries>
    <unit>ms</unit>
    <description />
    <attributes>
        <attribute name="Uptime" />
    </attributes>
</measurement>

The objectNameQuery is used to query the MBeanServer of matching MBeans (this example will only find one). It only contains one attribute (Uptime) that will be available in JMole under JVM/Uptime.

The level 1 indicate that these measurements are very basic and will always be available.

Example 2

<measurement name="Garbage Collections/min: %s" category="JVM" level="3">
    <objectNameQueries>
        <objectNameQuery>java.lang:type=GarbageCollector,*</objectNameQuery>
    </objectNameQueries>
    <nameExtensions>
        <attributes>
            <attribute>Name</attribute>
        </attributes>
    </nameExtensions>
    <unit>Count</unit>
    <description />
    <attributes>
        <attribute name="CollectionCount">
            <label>Number of GC/min</label>
            <interval>60000</interval>
        </attribute>
    </attributes>
</measurement>

As this objectNameQuery may return several matching MBeans the nameExtensions config is used together with the name to construct a unique name for each MBean found. The nameExtensions here uses the value from the MBean attribute Name.

The attribute that is monitored in this example (CollectionCount) have a label configured so it may be presented with a more human understandable name. In this example we are interested in the increase for each minute (60000 ms), as this value is a counter.

Example 3

<measurement name="Time spent in Garbage Collection/min: %s" category="JVM" level="3">
    <objectNameQueries>
        <objectNameQuery>java.lang:type=GarbageCollector,*</objectNameQuery>
    </objectNameQueries>
    <nameExtensions>
        <attributes>
            <attribute>Name</attribute>
        </attributes>
    </nameExtensions>
    <unit>ms/min</unit>
    <description />
    <attributes>
        <attribute name="CollectionTime">
            <label>Time (ms) spent in GC/min</label>
            <interval>60000</interval>
            <thresholds>
                <common>
                    <warningHighThreshold>60000,0.10,*</warningHighThreshold>
                    <criticalHighThreshold>60000,0.50,*</criticalHighThreshold>
                </common>
            </thresholds>
        </attribute>
    </attributes>
</measurement>

Here we have a warning and critical check as well. If more that 10% of time is used for GC a warning will be triggered and if more than 50% is used the critical level is reached. The syntax is based on reverse polish notation and even if the example uses the constant 60000 it may also reference another JMX attribute from the current MBean.

The common tag indicate that these thresholds should be used for all matching MBeans. It is possible to override this for specific targets. See the XML Schema for more information.