COLLECTD-JAVA(5)

okay so this is collectd-java(5), part 1, and it's literally the manual page for collectd's "java plugin". buckle up bestie, we're getting into it ✨

🌸 NAME 🌸

collectd-java — Documentation of collectd's "java plugin". that's the whole name section, short and iconic 💅

🦋 SYNOPSIS 🦋

here's the config vibe, fr fr:

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 gives you a Java interface to part of collectd's API. that means you can write additions to the daemon in Java, which is lowkey a serve 🫶

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

🎀 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). that's where the full menu lives, bestie.

🌈 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. so you get the Java version, not the raw C chaos 💖

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. cute, right? the daemon calls them when it's their moment.

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. no import, no shortcut, iykyk 💅

👑 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. zero = slay, non-zero = something went wrong.

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. zero = slay, non-zero = something went wrong.

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. zero = slay, non-zero = something went wrong.

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. zero = slay, non-zero = something went wrong.

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. zero = slay, non-zero = something went wrong.

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. zero = slay, non-zero = something went wrong.

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. zero = slay, non-zero = something went wrong.

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. zero = slay, non-zero = something went wrong.

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. zero = slay, non-zero = something went wrong.

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. zero = slay, non-zero = something went wrong.

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. literally fine, bestie, don't stress it.

Returns zero upon success or non-zero upon failure. zero = good, non-zero = not good.

🌈 getDS

Signature: DataSet getDS (String)

Returns the appropriate type or null if the type is not defined. if it's not defined, you get null, periodt.

💅 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 💖

okay bestie, here’s the tea ☕: when collectd starts up, it creates an object of each configured class. The constructor of that class should then register "callbacks" with the daemon, using the appropriate static functions in Collectd — see EXPORTED API FUNCTIONS above, iykyk. To register a callback, the object you pass to one of the register functions has to implement an appropriate interface, and all those interfaces live in the org.collectd.api namespace. No cap.

A constructor may register any number of these callbacks — even none, literally zero. An object without callback methods is never actively called by collectd, but it 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. Main character energy, honestly 💅

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 it 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". Obsessed, honestly 🫶

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 matched 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

---

🌟 EXAMPLE 🌟

This short example demonstrates how to register a read callback with the daemon. Copy-paste responsibly, bestie 😌✨

         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 🧩

These plugins are implemented in Java, bestie. Both the LoadPlugin option and the Plugin block have to be inside the <Plugin java> block (see above) — yes, both, no cap.

🌟 GenericJMX plugin 🌟

The GenericJMX plugin reads Managed Beans (MBeans) from an MBeanServer using JMX. JMX is a generic framework for providing and querying all kinds of management information. Java processes use the interface to hand over their internal stats, and the Java Virtual Machine (JVM) uses it too — for stuff like memory used, threads, and so on.

The configuration of the GenericJMX plugin has two blocks: MBean blocks that define a mapping of MBean attributes to the “types” used by collectd, and Connection blocks that 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 onto 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 — no duplicate names, periodt.

The following options are recognized within MBean blocks:

• ObjectName pattern — sets the pattern 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 — these 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 — that's the rule, fr fr.
  • 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 get 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. This 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, and 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.

---

👀 SEE ALSO 👀

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

✍️ AUTHOR ✍️

Florian Forster <octo at collectd.org>

---

This page is stamped 5.12.0.git and dated 2026-08-22 — that's COLLECTD-JAVA(5), and it's iconic, bye bestie 🫶✨