Name
    jmxetric - jvm instrumentation to ganglia

Version
    The latest version of this software and document will be found at
    https://github.com/ganglia/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
    Check the matching version of gmetric4j.jar in the pom.xml
    1) Ensure you have a gmond running on localhost:8649
        $ pgrep gmond # should return a valid PID
        $ nc localhost 8649 # dumps some XML to stdout
    2) $ git clone https://github.com/ganglia/jmxetric.git
    3) Download jmxetric.jar, gmetric4j.jar and remotetea-oncrpc.jar
       all into the same directory.
    4) $ cd jmxetric
    5) In bash do:
        $ export config="host=localhost,port=8649,wireformat31x=true,config=etc/jmxetric.xml"
        $ java  -Djava.util.logging.config.file=etc/logging.properties \
            -cp gmetric4j.jar:remotetea-oncrpc.jar:jmxetric.jar \
            -javaagent:jmxetric.jar=$config info.ganglia.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)
	
	spoof         An IP:hostname pair that will be used to spoof the metric host information.
	              (default: no spoofing, i.e., local hostname reported by OS)

    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>
          <!ATTLIST ganglia spoof CDATA #IMPLIED>
       <!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, jasper521@gmail.com
      Copyright (C) 2011-2015 Daniel Pocock, http://danielpocock.com