Plugin:GenericJMX

From collectd Wiki

Jump to: navigation, search
GenericJMX plugin
Type: read
Callbacks: config, read, shutdown
Status: supported
First version: 4.8
Copyright: 2009 Florian octo Forster
License: GPLv2
Manpage: collectd-java(5)
List of Plugins

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.

Contents

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.

Image:Java memory eden space.png
Java memory: Eden space (generation 0)

Image:Java memory survivor space.png
Java memory: Survivor space (generation 1)

Image:Java memory old generation.png
Java memory: Old generation (generation 2)

Dependencies

See also