Name jmxetric - jvm instrumentation to ganglia

Version jmxetric 0.0.5

The latest version of this software and document will always be found at 
http://code.google.com/p/jmxetric/

Synopsis JMXetric is a 100% java, configurable JVM agent that periodically polls MBean attributes and reports their values to Ganglia.

Project goals are that JMXetric should be
    * configurable (xml)
    * lightweight (small memory and cpu footprint)
    * standalone (not depend on third party libraries)

The gmetric protocol implementation uses classes generated by the LGPL 
remotetea project (http://remotetea.sf.net).

Installation

Unzip the archive
Add the following to your JVM
java -javaagent:<path>/jmxetric.jar=host="",port="",config="",process="" usual.java.main.class

Demo / Quickstart

1) Ensure you have a gmond running on localhost:8649
2) Unzip archive
3) cd into the directory
2) In bash do:
    $ export config="host=localhost,port=8649,wireformat31x=true,config=etc/jmxetric.xml"
    $ java  -Djava.util.logging.config.file=etc/logging.properties \
        -javaagent:jmxetric-0.0.5.jar=$config jmxetric.JMXetricAgent

Configuration The configuration of JMXetric is loaded from an xml file in the working directory of the shell, or specified as an argument to the JVM agent ("config"). The JVM agent arguments can also be used to specify the following:

host, port    The multicast address that is used to publish metrics to the
              ganglia gmond process

config        The full path to the config file (jmxetric.xml)

mode          The UDP addressing mode, either multicast or unicast (default multicast)

wireformat31x True if the ganglia v3.1.x wire format should be used (default false)

process       A name that is prefixed to the metric name before publication 
              (so that metrics from different JVMs on the same host can be 
              determined)

XML Configuation File

JMXetric schedules a number of "samples", that queries a list of "mbeans", 
that have "attributes".  

Element/Attribute    Description
mbean/name           The name of the mbean to query
mbean/pname          The metric name for this mbean.  This should always be
                     used as ganglia/rrdtool misbehaves if the filename is
                     "unusual".
attribute/nam        The name of the attribute.  This can have two levels
                     for the case of a composite key see below example for 
                     attribute "HeapMemoryUsage", key "used"
attribute/type       The type used for the metric in ganglia
attribute/units      The units used for the metric in ganglia
attribute/pname      The metric name for this attribute

An example file:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE jmxetric-config [
   <!ELEMENT jmxetric-config (sample|ganglia|jvm)*>
   <!ELEMENT sample (mbean)*>
      <!ATTLIST sample delay CDATA #REQUIRED>
      <!ATTLIST sample initialdelay CDATA "0">
   <!ELEMENT mbean (attribute)*>
      <!ATTLIST mbean name CDATA #REQUIRED>
      <!ATTLIST mbean pname CDATA #REQUIRED>
   <!ELEMENT attribute (composite*)>
      <!ATTLIST attribute name CDATA #REQUIRED>
      <!ATTLIST attribute type CDATA "" >
      <!ATTLIST attribute units CDATA "" >
      <!ATTLIST attribute pname CDATA "" >
      <!ATTLIST attribute slope CDATA "both" >
   <!ELEMENT composite EMPTY>
      <!ATTLIST composite name CDATA #REQUIRED>
      <!ATTLIST composite type CDATA "" >
      <!ATTLIST composite units CDATA "" >
      <!ATTLIST composite pname CDATA "" >
      <!ATTLIST composite slope CDATA "both" >
   <!ELEMENT ganglia EMPTY>
      <!ATTLIST ganglia hostname CDATA #REQUIRED>
      <!ATTLIST ganglia port CDATA #REQUIRED>
      <!ATTLIST ganglia mode CDATA #REQUIRED>
      <!ATTLIST ganglia wireformat31x CDATA #REQUIRED>
   <!ELEMENT jvm EMPTY>
      <!ATTLIST jvm process CDATA "">
]>
<jmxetric-config>
    <jvm process="ProcessName"/>
    <sample delay="300">
        <mbean name="java.lang:type=Memory" pname="Memory">
            <attribute name="HeapMemoryUsage">
                <composite name="init" pname="Heap_init" type="int32" units="bytes"/>
                <composite name="committed" pname="Heap_committed" type="int32" units="bytes"/>
                <composite name="used" pname="Heap_used" type="int32" units="bytes" />
                <composite name="max" pname="Heap_max" type="int32" units="bytes" />
            </attribute>
            <attribute name="NonHeapMemoryUsage" >
                <composite name="init" pname="NonHeap_init" type="int32"  units="bytes" />
                <composite name="committed" pname="NonHeap_committed" type="int32" units="bytes" />
                <composite name="used" pname="NonHeap_used" type="int32" units="bytes" />
                <composite name="max" pname="NonHeap_max" type="int32" units="bytes" />
            </attribute>
        </mbean>
        <mbean name="java.lang:type=Threading" pname="Threading" >
            <attribute name="ThreadCount" type="int16" />
            <attribute name="DaemonThreadCount" type="int16" />
        </mbean>
        <mbean name="java.lang:type=OperatingSystem" pname="OS" >
            <attribute name="ProcessCpuTime" type="int32" slope="positive"/>
        </mbean>
    </sample>
    <ganglia hostname="localhost" port="8649" mode="multicast" wireformat31x="true" />
</jmxetric-config>

Support/Queries I'm sure there are bugs and I'm sure there are some mbeans that can't be sampled currently. If you find some, then let me know jasper521 at gmail

If you are using this at all, then I'd love to know!

Copyright Copyright (C) 2008-2011 Jasper Humphrey

Authors Jasper Humphrey jasper521 at gmail Developer