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.

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:

• 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.

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:

• Collectd.FC_MATCH_NO_MATCH
• 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:

• Collectd.FC_TARGET_CONTINUE
• Collectd.FC_TARGET_STOP
• Collectd.FC_TARGET_RETURN

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 “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: <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 “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.

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, “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.

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.