collectd-java - Documentation of collectd's "java plugin"
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>
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Signature:
DataSet getDS (
String)
Returns the appropriate
type or
null if the type is not defined.
Signature:
void logError (
String)
Sends a log message with severity
ERROR to the daemon.
Signature:
void logWarning (
String)
Sends a log message with severity
WARNING to the daemon.
Signature:
void logNotice (
String)
Sends a log message with severity
NOTICE to the daemon.
Signature:
void logInfo (
String)
Sends a log message with severity
INFO to the daemon.
Signature:
void logDebug (
String)
Sends a log message with severity
DEBUG to the daemon.
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:
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.
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.
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.
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.
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.
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.
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:
- •
- org.collectd.api.Collectd.LOG_ERR
- •
- org.collectd.api.Collectd.LOG_WARNING
- •
- org.collectd.api.Collectd.LOG_NOTICE
- •
- org.collectd.api.Collectd.LOG_INFO
- •
- org.collectd.api.Collectd.LOG_DEBUG
The function does not return any value.
See "registerLog" above.
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.
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:
- •
- Collectd.FC_MATCH_NO_MATCH
- •
- Collectd.FC_MATCH_MATCHES
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:
- •
- Collectd.FC_TARGET_CONTINUE
- •
- Collectd.FC_TARGET_STOP
- •
- Collectd.FC_TARGET_RETURN
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);
}
}
The following plugins are implemented in
Java. Both, the
LoadPlugin option and the
Plugin block must be inside the
<Plugin java> block (see above).
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 XtypesX
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 XpropertiesX 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)
-
PluginName name
- When set, overrides the default setting for the
plugin field ("GenericJMX").
-
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:
Xattrib0.key42X. 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, XmonitorRoleX 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.
-
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.
collectd(1),
collectd.conf(5),
collectd-perl(5),
types.db(5)
Florian Forster <octo at collectd.org>