Provided by: collectd-core_4.10.1-2_i386 bug

NAME

       collectd-java - Documentation of collectd's "java plugin"

SYNOPSIS

        LoadPlugin "java"
        <Plugin "java">
          JVMArg "-verbose:jni"
          JVMArg "-Djava.class.path=/opt/collectd/lib/collectd/bindings/java"

          LoadPlugin "org.collectd.java.Foobar"
          <Plugin "org.collectd.java.Foobar">
            # To be parsed by the plugin
          </Plugin>
        </Plugin>

DESCRIPTION

       The Java plugin embeds a Java Virtual Machine (JVM) into collectd and
       provides a Java interface to part of collectd's API. This makes it
       possible to write additions to the daemon in Java.

       This plugin is similar in nature to, but shares no code with, the Perl
       plugin by Sebastian Harl, see collectd-perl(5) for details.

CONFIGURATION

       A short outline of this plugin's configuration can be seen in
       "SYNOPSIS" above. For a complete list of all configuration options and
       their semantics please read "Plugin "java"" in collectd.conf(5).

OVERVIEW

       When writing additions for collectd in Java, the underlying C base is
       mostly hidden from you. All complex data types are converted to their
       Java counterparts before they're passed to your functions. These Java
       classes reside in the org.collectd.api namespace.

       The Java plugin will create one object of each class configured with
       the LoadPlugin option. The constructor of this class can then register
       "callback methods", i. e. methods that will be called by the daemon
       when appropriate.

       The available classes are:

       org.collectd.api.Collectd
           All API functions exported to Java are implemented as static
           functions of this class. See "EXPORTED API FUNCTIONS" below.

       org.collectd.api.OConfigValue
           Corresponds to "oconfig_value_t", defined in
           src/liboconfig/oconfig.h.

       org.collectd.api.OConfigItem
           Corresponds to "oconfig_item_t", defined in
           src/liboconfig/oconfig.h.

       org.collectd.api.DataSource
           Corresponds to "data_source_t", defined in src/plugin.h.

       org.collectd.api.DataSet
           Corresponds to "data_set_t", defined in src/plugin.h.

       org.collectd.api.ValueList
           Corresponds to "value_list_t", defined in src/plugin.h.

       org.collectd.api.Notification
           Corresponds to "notification_t", defined in src/plugin.h.

       In the remainder of this document, we'll use the short form of these
       names, for example ValueList. In order to be able to use these
       abbreviated names, you need to import the classes.

EXPORTED API FUNCTIONS

       All collectd API functions that are available to Java plugins are
       implemented as public static functions of the Collectd class. This
       makes calling these functions pretty straight forward. For example, to
       send an error message to the daemon, you'd do something like this:

         Collectd.logError ("That wasn't chicken!");

       The following are the currently exported functions.

   registerConfig
       Signature: int registerConfig (String name, CollectdConfigInterface
       object);

       Registers the config function of object with the daemon.

       Returns zero upon success and non-zero when an error occurred.

       See "config callback" below.

   registerInit
       Signature: int registerInit (String name, CollectdInitInterface
       object);

       Registers the init function of object with the daemon.

       Returns zero upon success and non-zero when an error occurred.

       See "init callback" below.

   registerRead
       Signature: int registerRead (String name, CollectdReadInterface object)

       Registers the read function of object with the daemon.

       Returns zero upon success and non-zero when an error occurred.

       See "read callback" below.

   registerWrite
       Signature: int registerWrite (String name, CollectdWriteInterface
       object)

       Registers the write function of object with the daemon.

       Returns zero upon success and non-zero when an error occurred.

       See "write callback" below.

   registerFlush
       Signature: int registerFlush (String name, CollectdFlushInterface
       object)

       Registers the flush function of object with the daemon.

       Returns zero upon success and non-zero when an error occurred.

       See "flush callback" below.

   registerShutdown
       Signature: int registerShutdown (String name, CollectdShutdownInterface
       object);

       Registers the shutdown function of object with the daemon.

       Returns zero upon success and non-zero when an error occurred.

       See "shutdown callback" below.

   registerLog
       Signature: int registerLog (String name, CollectdLogInterface object);

       Registers the log function of object with the daemon.

       Returns zero upon success and non-zero when an error occurred.

       See "log callback" below.

   registerNotification
       Signature: int registerNotification (String name,
       CollectdNotificationInterface object);

       Registers the notification function of object with the daemon.

       Returns zero upon success and non-zero when an error occurred.

       See "notification callback" below.

   registerMatch
       Signature: int registerMatch (String name,
       CollectdMatchFactoryInterface object);

       Registers the createMatch function of object with the daemon.

       Returns zero upon success and non-zero when an error occurred.

       See "match callback" below.

   registerTarget
       Signature: int registerTarget (String name,
       CollectdTargetFactoryInterface object);

       Registers the createTarget function of object with the daemon.

       Returns zero upon success and non-zero when an error occurred.

       See "target callback" below.

   dispatchValues
       Signature: int dispatchValues (ValueList)

       Passes the values represented by the ValueList object to the
       "plugin_dispatch_values" function of the daemon. The "data set" (or
       list of "data sources") associated with the object are ignored, because
       "plugin_dispatch_values" will automatically lookup the required data
       set. It is therefore absolutely okay to leave this blank.

       Returns zero upon success or non-zero upon failure.

   getDS
       Signature: DataSet getDS (String)

       Returns the appropriate type or null if the type is not defined.

   logError
       Signature: void logError (String)

       Sends a log message with severity ERROR to the daemon.

   logWarning
       Signature: void logWarning (String)

       Sends a log message with severity WARNING to the daemon.

   logNotice
       Signature: void logNotice (String)

       Sends a log message with severity NOTICE to the daemon.

   logInfo
       Signature: void logInfo (String)

       Sends a log message with severity INFO to the daemon.

   logDebug
       Signature: void logDebug (String)

       Sends a log message with severity DEBUG to the daemon.

REGISTERING CALLBACKS

       When starting up, collectd creates an object of each configured class.
       The constructor of this class should then register "callbacks" with the
       daemon, using the appropriate static functions in Collectd, see
       "EXPORTED API FUNCTIONS" above. To register a callback, the object
       being passed to one of the register functions must implement an
       appropriate interface, which are all in the org.collectd.api namespace.

       A constructor may register any number of these callbacks, even none. An
       object without callback methods is never actively called by collectd,
       but may still call the exported API functions. One could, for example,
       start a new thread in the constructor and dispatch (submit to the
       daemon) values asynchronously, whenever one is available.

       Each callback method is now explained in more detail:

   config callback
       Interface: org.collectd.api.CollectdConfigInterface

       Signature: int config (OConfigItem ci)

       This method is passed a OConfigItem object, if both, method and
       configuration, are available. OConfigItem is the root of a tree
       representing the configuration for this plugin. The root itself is the
       representation of the <Plugin /> block, so in next to all cases the
       children of the root are the first interesting objects.

       To signal success, this method has to return zero. Anything else will
       be considered an error condition and the plugin will be disabled
       entirely.

       See "registerConfig" above.

   init callback
       Interface: org.collectd.api.CollectdInitInterface

       Signature: int init ()

       This method is called after the configuration has been handled. It is
       supposed to set up the plugin. e. g. start threads, open connections,
       or check if can do anything useful at all.

       To signal success, this method has to return zero. Anything else will
       be considered an error condition and the plugin will be disabled
       entirely.

       See "registerInit" above.

   read callback
       Interface: org.collectd.api.CollectdReadInterface

       Signature: int read ()

       This method is called periodically and is supposed to gather statistics
       in whatever fashion. These statistics are represented as a ValueList
       object and sent to the daemon using dispatchValues.

       To signal success, this method has to return zero. Anything else will
       be considered an error condition and cause an appropriate message to be
       logged.  Currently, returning non-zero does not have any other effects.
       In particular, Java "read"-methods are not suspended for increasing
       intervals like C "read"-functions.

       See "registerRead" above.

   write callback
       Interface: org.collectd.api.CollectdWriteInterface

       Signature: int write (ValueList vl)

       This method is called whenever a value is dispatched to the daemon. The
       corresponding C "write"-functions are passed a "data_set_t", so they
       can decide which values are absolute values (gauge) and which are
       counter values.  To get the corresponding "List<DataSource>", call the
       getDataSource method of the ValueList object.

       To signal success, this method has to return zero. Anything else will
       be considered an error condition and cause an appropriate message to be
       logged.

       See "registerWrite" above.

   flush callback
       Interface: org.collectd.api.CollectdFlushInterface

       Signature: int flush (int timeout, String identifier)

       This method is called when the daemon received a flush command. This
       can either be done using the "USR1" signal (see collectd(1)) or using
       the unixsock plugin (see collectd-unixsock(5)).

       If timeout is greater than zero, only values older than this number of
       seconds should be flushed. To signal that all values should be flushed
       regardless of age, this argument is set to a negative number.

       The identifier specifies which value should be flushed. If it is not
       possible to flush one specific value, flush all values. To signal that
       all values should be flushed, this argument is set to null.

       To signal success, this method has to return zero. Anything else will
       be considered an error condition and cause an appropriate message to be
       logged.

       See "registerFlush" above.

   shutdown callback
       Interface: org.collectd.api.CollectdShutdownInterface

       Signature: int shutdown ()

       This method is called when the daemon is shutting down. You should not
       rely on the destructor to clean up behind the object but use this
       function instead.

       To signal success, this method has to return zero. Anything else will
       be considered an error condition and cause an appropriate message to be
       logged.

       See "registerShutdown" above.

   log callback
       Interface: org.collectd.api.CollectdLogInterface

       Signature: void log (int severity, String message)

       This callback can be used to receive log messages from the daemon.

       The argument severity is one of:

       o   org.collectd.api.Collectd.LOG_ERR

       o   org.collectd.api.Collectd.LOG_WARNING

       o   org.collectd.api.Collectd.LOG_NOTICE

       o   org.collectd.api.Collectd.LOG_INFO

       o   org.collectd.api.Collectd.LOG_DEBUG

       The function does not return any value.

       See "registerLog" above.

   notification callback
       Interface: org.collectd.api.CollectdNotificationInterface

       Signature: int notification (Notification n)

       This callback can be used to receive notifications from the daemon.

       To signal success, this method has to return zero. Anything else will
       be considered an error condition and cause an appropriate message to be
       logged.

       See "registerNotification" above.

   match callback
       The match (and target, see "target callback" below) callbacks work a
       bit different from the other callbacks above: You don't register a
       match callback with the daemon directly, but you register a function
       which, when called, creates an appropriate object. The object creating
       the "match" objects is called "match factory".

       See "registerMatch" above.

       Factory object

       Interface: org.collectd.api.CollectdMatchFactoryInterface

       Signature: CollectdMatchInterface createMatch (OConfigItem ci);

       Called by the daemon to create "match" objects.

       Returns: A new object which implements the CollectdMatchInterface
       interface.

       Match object

       Interface: org.collectd.api.CollectdMatchInterface

       Signature: int match (DataSet ds, ValueList vl);

       Called when processing a chain to determine whether or not a ValueList
       matches. How values are matches is up to the implementing class.

       Has to return one of:

       o   Collectd.FC_MATCH_NO_MATCH

       o   Collectd.FC_MATCH_MATCHES

   target callback
       The target (and match, see "match callback" above) callbacks work a bit
       different from the other callbacks above: You don't register a target
       callback with the daemon directly, but you register a function which,
       when called, creates an appropriate object. The object creating the
       "target" objects is called "target factory".

       See "registerTarget" above.

       Factory object

       Interface: org.collectd.api.CollectdTargetFactoryInterface

       Signature: CollectdTargetInterface createTarget (OConfigItem ci);

       Called by the daemon to create "target" objects.

       Returns: A new object which implements the CollectdTargetInterface
       interface.

       Target object

       Interface: org.collectd.api.CollectdTargetInterface

       Signature: int invoke (DataSet ds, ValueList vl);

       Called when processing a chain to perform some action. The action
       performed is up to the implementing class.

       Has to return one of:

       o   Collectd.FC_TARGET_CONTINUE

       o   Collectd.FC_TARGET_STOP

       o   Collectd.FC_TARGET_RETURN

EXAMPLE

       This short example demonstrates how to register a read callback with
       the daemon:

         import org.collectd.api.Collectd;
         import org.collectd.api.ValueList;

         import org.collectd.api.CollectdReadInterface;

         public class Foobar implements CollectdReadInterface
         {
           public Foobar ()
           {
             Collectd.registerRead ("Foobar", this);
           }

           public int read ()
           {
             ValueList vl;

             /* Do something... */

             Collectd.dispatchValues (vl);
           }
         }

PLUGINS

       The following plugins are implemented in Java. Both, the LoadPlugin
       option and the Plugin block must be inside the <Plugin java> block (see
       above).

   GenericJMX plugin
       The GenericJMX plugin reads Managed Beans (MBeans) from an MBeanServer
       using JMX. JMX is a generic framework to provide and query various
       management information. The interface is used by Java processes to
       provide internal statistics as well as by the Java Virtual Machine
       (JVM) to provide information about the memory used, threads and so on.

       The configuration of the GenericJMX plugin consists of two blocks:
       MBean blocks that define a mapping of MBean attributes to the
       aXXtypesaXX 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:
           <http://java.sun.com/javase/6/docs/api/javax/management/ObjectName.html>

       InstancePrefix prefix
           Prefixes the generated plugin instance with prefix. (optional)

       InstanceFrom property
           The object names used by JMX to identify MBeans include so called
           aXXpropertiesaXX 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:
               aXXattrib0.key42aXX. 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. 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:
           <http://java.sun.com/javase/6/docs/api/javax/management/remote/JMXServiceURL.html>

       User name
           Use name to authenticate to the server. If not configured,
           aXXmonitorRoleaXX will be used.

       Password password
           Use password to authenticate to the server. If not given,
           unauthenticated access is used.

       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.

SEE ALSO

       collectd(1), collectd.conf(5), collectd-perl(5), types.db(5)

AUTHOR

       Florian Forster <octo at verplant.org>