GenericJMX plugin¶

The GenericJMX plugin reads Managed Beans (MBeans) from an MBeanServer using JMX. The plugin is written in Java and requires the Java plugin to function.

The Java Management Extensions (JMX) is a generic framework to provide and query various management information. The interface is used by the Java Virtual Machine (JVM) to provide information about the memory used, threads and so on. These basic performance values can therefore be collected for every Java process without any support in the Java process itself.

Advanced Java processes can use the JMX interface to provide performance information themselves. The Apache Tomcat application server, for example, provides information on the number of requests processed, the number of bytes sent, processing time, and thread counts.

Synopsis¶

- → See: Plugin-GenericJMX-Config

 <Plugin "java">
   # required JVM argument is the classpath
   # JVMArg "-Djava.class.path=/installpath/collectd/share/collectd/java"
   # Since version 4.8.4 (commit c983405) the API and GenericJMX plugin are
   # provided as .jar files.
   JVMARG "-Djava.class.path=/usr/share/collectd/java/collectd-api.jar:/usr/share/collectd/java/generic-jmx.jar"
   LoadPlugin "org.collectd.java.GenericJMX"

   <Plugin "GenericJMX">
     # Memory usage by memory pool.
     <MBean "memory_pool">
       ObjectName "java.lang:type=MemoryPool,*"
       InstancePrefix "memory_pool-"
       InstanceFrom "name"
       <Value>
         Type "memory"
         #InstancePrefix ""
         #InstanceFrom ""
         Table true
         Attribute "Usage"
       </Value>
     </MBean>

     <Connection>
       Host "localhost"
       ServiceURL "service:jmx:rmi:///jndi/rmi://localhost:17264/jmxrmi"
       Collect "memory_pool"
     </Connection>
   </Plugin>
 </Plugin>

Configuration¶

The configuration of the GenericJMX plugin consists of two blocks: MBean blocks that define a mapping of MBean attributes to the “types” used by collectd, and Connection blocks which define the parameters needed to connect to an MBeanServer and what data to collect. The configuration of the SNMP plugin is similar in nature, in case you know it.

MBean blocks¶

MBean blocks specify what data is retrieved from MBeans and how that data is mapped on the collectd data types. The block requires one string argument, a name. This name is used in the Connection blocks (see below) to refer to a specific MBean block. Therefore, the names must be unique.

The following options are recognized within MBean blocks:

• ObjectName pattern Sets the pattern which is used to retrieve MBeans from the MBeanServer. If more than one MBean is returned you should use the InstanceFrom option (see below) to make the identifiers unique. → ''See also: ObjectName.
• InstancePrefix prefix Prefixes the generated plugin instance with prefix. (optional)
• InstanceFrom property The object names used by JMX to identify MBeans include so called “properties” which are basically key-value-pairs. If the given object name is not unique and multiple MBeans are returned, the values of those properties usually differ. You can use this option to build the plugin instance from the appropriate property values. This option is optional and may be repeated to generate the plugin instance from multiple property values.
• \<value /> blocks The value blocks map one or more attributes of an MBean to a value-list in collectd. There must be at least one Value block within each MBean block.
  • Type type Sets the data-set used within collectd to handle the values of the MBean attribute.
  • InstancePrefix prefix Works like the option of the same name directly beneath the MBean block, but sets the type instance instead. (optional)
  • InstanceFrom prefix Works like the option of the same name directly beneath the MBean block, but sets the type instance instead. (optional)
  • Table true|false Set this to true if the returned attribute is a composite type. If set to true, the keys within the composite type is appended to the type instance.
  • Attribute path Sets the name of the attribute from which to read the value. You can access the keys of composite types by using a dot to concatenate the key name to the attribute name. For example: “attrib0.key42”. If Table is set to true path must point to a composite type, otherwise it must point to a numeric type.

Connection blocks¶

Connection blocks specify how to connect to an MBeanServer and what data to retrieve. The following configuration options are available:

• Host name Host name used when dispatching the values to collectd. See naming-schema for details. The option sets this field only, it is not used to connect to anything and doesn't need to be a real, resolvable name.
• ServiceURL URL Specifies how the MBeanServer can be reached. Any string accepted by the JMXServiceURL is valid. - → ''See also: JMXServiceURL
• User name Use name to authenticate to the server. If not configured, “monitorRole” will be used.
• Password password Use password to authenticate to the server. If not given, unauthenticated access is used.
• InstancePrefix prefix Prefixes the generated plugin instance with prefix. If a second InstancePrefix is specified in a referenced MBean block, the prefix specified in the Connection block will appear at the beginning of the plugin instance, the prefix specified in the MBean block will be appended to it. (optional, since version-5.0)
• Collect mbean_block_name Configures which of the MBean blocks to use with this connection. May be repeated to collect multiple MBeans from this server.

Example graphs¶

The following graphs have been collected using the example configuration available from contrib/GenericJMX.conf.

Java memory: Eden space (generation 0)

Java memory: Survivor space (generation 1)

Java memory: Old generation (generation 2)

Dependencies¶

• Java
• Java plugin

See also¶

• Plugin-GenericJMX-Config
• http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement/

Configuration examples¶

This page contains some example configurations for the GenericJMX plugin. This page is meant as a cookbook, so if you have a configuration for an aspect not handled here or a daemon not present, please feel free to add anything that's useful for you.

These definitions are also available in the source code distribution as contrib/GenericJMX.conf.

Generic¶

These values are provided by the Java Virtual Machine (JVM) itself and are therefore available for all Java processes (if enabled at startup).

Classes¶

Number of classes loaded by the JVM.

 <MBean "classes">
   ObjectName "java.lang:type=ClassLoading"
   #InstancePrefix ""
   #InstanceFrom ""

   <Value>
     Type "gauge"
     InstancePrefix "loaded_classes"
     #InstanceFrom ""
     Table false
     Attribute "LoadedClassCount"
   </Value>
 </MBean>

Compilation¶

Time spent by the JVM compiling or optimizing.

 <MBean "compilation">
   ObjectName "java.lang:type=Compilation"
   #InstancePrefix ""
   #InstanceFrom ""

   <Value>
     Type "total_time_in_ms"
     InstancePrefix "compilation_time"
     #InstanceFrom ""
     Table false
     Attribute "TotalCompilationTime"
   </Value>
 </MBean>

Garbage collector¶

Garbage collector information

 <MBean "garbage_collector">
   ObjectName "java.lang:type=GarbageCollector,*"
   InstancePrefix "gc-"
   InstanceFrom "name"

   <Value>
     Type "invocations"
     #InstancePrefix ""
     #InstanceFrom ""
     Table false
     Attribute "CollectionCount"
   </Value>

   <Value>
     Type "total_time_in_ms"
     InstancePrefix "collection_time"
     #InstanceFrom ""
     Table false
     Attribute "CollectionTime"
   </Value>

 # # Not that useful, therefore commented out.
 # <Value>
 #   Type "threads"
 #   #InstancePrefix ""
 #   #InstanceFrom ""
 #   Table false
 #   # Demonstration how to access composite types
 #   Attribute "LastGcInfo.GcThreadCount"
 # </Value>
 </MBean>

Memory¶

Generic heap / nonheap memory usage.

 # Heap memory usage
 <MBean "memory-heap">
   ObjectName "java.lang:type=Memory"
   #InstanceFrom ""
   InstancePrefix "memory-heap"

   # Creates four values: committed, init, max, used
   <Value>
     Type "jmx_memory"
     #InstancePrefix ""
     #InstanceFrom ""
     Table true
     Attribute "HeapMemoryUsage"
   </Value>
 </MBean>

 # Non-heap memory usage
 <MBean "memory-nonheap">
   ObjectName "java.lang:type=Memory"
   #InstanceFrom ""
   InstancePrefix "memory-nonheap"

   # Creates four values: committed, init, max, used
   <Value>
     Type "jmx_memory"
     #InstancePrefix ""
     #InstanceFrom ""
     Table true
     Attribute "NonHeapMemoryUsage"
   </Value>
 </MBean>

This config uses the jmx_memory data-set which is not defined by the default types.db shipped with collectd. To use this config, add the following to your custom types.db. See types.db(5) for details.

jmx_memory      value:GAUGE:0:U

Memory pools¶

Memory usage by memory pool.

 <MBean "memory_pool">
   ObjectName "java.lang:type=MemoryPool,*"
   InstancePrefix "memory_pool-"
   InstanceFrom "name"

   <Value>
     Type "jmx_memory"
     #InstancePrefix ""
     #InstanceFrom ""
     Table true
     Attribute "Usage"
   </Value>
 </MBean>

This config uses the non-standard data-set jmx_memory. For more details, see the Memory section above.

Tomcat / Catalina¶

The following MBeans are provided by Tomcat, an application server by Apache.

Request processors (global)¶

Traffic, number of requests and time used for each request processor.

 <MBean "catalina/global_request_processor">
   ObjectName "Catalina:type=GlobalRequestProcessor,*"
   InstancePrefix "request_processor-"
   InstanceFrom "name"

   <Value>
     Type "io_octets"
     InstancePrefix "global"
     #InstanceFrom ""
     Table false
     Attribute "bytesReceived"
     Attribute "bytesSent"
   </Value>

   <Value>
     Type "total_requests"
     InstancePrefix "global"
     #InstanceFrom ""
     Table false
     Attribute "requestCount"
   </Value>

   <Value>
     Type "total_time_in_ms"
     InstancePrefix "global-processing"
     #InstanceFrom ""
     Table false
     Attribute "processingTime"
   </Value>
 </MBean>

Request processors (detail)¶

Traffic, number of requests and time used for each request processor. This is more detailed, I think it returns statistics for each thread or something. (Fixme)

 <MBean "catalina/detailed_request_processor">
   ObjectName "Catalina:type=RequestProcessor,*"
   InstancePrefix "request_processor-"
   InstanceFrom "worker"

   <Value>
     Type "io_octets"
     #InstancePrefix ""
     InstanceFrom "name"
     Table false
     Attribute "bytesReceived"
     Attribute "bytesSent"
   </Value>

   <Value>
     Type "total_requests"
     #InstancePrefix ""
     InstanceFrom "name"
     Table false
     Attribute "requestCount"
   </Value>

   <Value>
     Type "total_time_in_ms"
     InstancePrefix "processing-"
     InstanceFrom "name"
     Table false
     Attribute "processingTime"
   </Value>
 </MBean>

Thread pool¶

Total number of threads in each thread pool and the number of threads currently running.

 <MBean "catalina/thread_pool">
   ObjectName "Catalina:type=ThreadPool,*"
   InstancePrefix "request_processor-"
   InstanceFrom "name"

   <Value>
     Type "threads"
     InstancePrefix "total"
     #InstanceFrom ""
     Table false
     Attribute "currentThreadCount"
   </Value>

   <Value>
     Type "threads"
     InstancePrefix "running"
     #InstanceFrom ""
     Table false
     Attribute "currentThreadsBusy"
   </Value>
 </MBean>

See also¶

• GenericJMX plugin

Configuration¶