Standard preamble:
========================================================================
..
.... Set up some character translations and predefined strings. \*(-- will
give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
double quote, and \*(R" will give a right double quote. \*(C+ will
give a nicer C++. Capital omega is used to do unbreakable dashes and
therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
nothing in troff, for use with C<>.
.tr \(*W- . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.
If the F register is >0, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.
Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF
Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} ========================================================================
Title "COLLECTD-JAVA 5"
way too many mistakes in technical documents.
This plugin is similar in nature to, but shares no code with, the Perl plugin by Sebastian Harl, see collectd-perl\|(5) for details.
The Java plugin will create one object of each class configured with the \fBLoadPlugin option. The constructor of this class can then register \*(L"callback methods\*(R", i. e. methods that will be called by the daemon when appropriate.
The available classes are:
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.
.Vb 1 Collectd.logError ("That wasn\*(Aqt chicken!"); .Ve
The following are the currently exported functions.
Registers the config function of object with the daemon.
Returns zero upon success and non-zero when an error occurred.
See \*(L"config callback\*(R" below.
Registers the init function of object with the daemon.
Returns zero upon success and non-zero when an error occurred.
See \*(L"init callback\*(R" below.
Registers the read function of object with the daemon.
Returns zero upon success and non-zero when an error occurred.
See \*(L"read callback\*(R" below.
Registers the write function of object with the daemon.
Returns zero upon success and non-zero when an error occurred.
See \*(L"write callback\*(R" below.
Registers the flush function of object with the daemon.
Returns zero upon success and non-zero when an error occurred.
See \*(L"flush callback\*(R" below.
Registers the shutdown function of object with the daemon.
Returns zero upon success and non-zero when an error occurred.
See \*(L"shutdown callback\*(R" below.
Registers the log function of object with the daemon.
Returns zero upon success and non-zero when an error occurred.
See \*(L"log callback\*(R" below.
Registers the notification function of object with the daemon.
Returns zero upon success and non-zero when an error occurred.
See \*(L"notification callback\*(R" below.
Registers the createMatch function of object with the daemon.
Returns zero upon success and non-zero when an error occurred.
See \*(L"match callback\*(R" below.
Registers the createTarget function of object with the daemon.
Returns zero upon success and non-zero when an error occurred.
See \*(L"target callback\*(R" below.
Passes the values represented by the ValueList object to the \f(CW\*(C`plugin_dispatch_values\*(C' function of the daemon. The \*(L"data set\*(R" (or list of \*(L"data sources\*(R") associated with the object are ignored, because \f(CW\*(C`plugin_dispatch_values\*(C' 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.
Returns the appropriate type or null if the type is not defined.
Sends a log message with severity \s-1ERROR\s0 to the daemon.
Sends a log message with severity \s-1WARNING\s0 to the daemon.
Sends a log message with severity \s-1NOTICE\s0 to the daemon.
Sends a log message with severity \s-1INFO\s0 to the daemon.
Sends a log message with severity \s-1DEBUG\s0 to the daemon.
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 \s-1API\s0 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:
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 \fB<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 \*(L"registerConfig\*(R" above.
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 \*(L"registerInit\*(R" above.
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 \*(L"read\*(R"-methods are not suspended for increasing intervals like C \*(L"read\*(R"-functions.
See \*(L"registerRead\*(R" above.
Signature: int write (ValueList vl)
This method is called whenever a value is dispatched to the daemon. The corresponding C \*(L"write\*(R"-functions are passed a \*(C`data_set_t\*(C', so they can decide which values are absolute values (gauge) and which are counter values. To get the corresponding \*(C`List<DataSource>\*(C', 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 \*(L"registerWrite\*(R" above.
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 \*(C`USR1\*(C' 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 \*(L"registerFlush\*(R" above.
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 \*(L"registerShutdown\*(R" above.
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:
The function does not return any value.
See \*(L"registerLog\*(R" above.
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 \*(L"registerNotification\*(R" above.
See \*(L"registerMatch\*(R" above.
Factory object Subsection "Factory object"
Interface: org.collectd.api.CollectdMatchFactoryInterface
Signature: CollectdMatchInterface createMatch (OConfigItem ci);
Called by the daemon to create \*(L"match\*(R" objects.
Returns: A new object which implements the CollectdMatchInterface interface.
Match object Subsection "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:
See \*(L"registerTarget\*(R" above.
Factory object Subsection "Factory object"
Interface: org.collectd.api.CollectdTargetFactoryInterface
Signature: CollectdTargetInterface createTarget (OConfigItem ci);
Called by the daemon to create \*(L"target\*(R" objects.
Returns: A new object which implements the CollectdTargetInterface interface.
Target object Subsection "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:
.Vb 2 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); } } .Ve
The configuration of the GenericJMX plugin consists of two blocks: MBean blocks that define a mapping of MBean attributes to the XtypesX used by \fIcollectd, and Connection blocks which define the parameters needed to connect to an MBeanServer and what data to collect. The configuration of the \fI\s-1SNMP\s0 plugin is similar in nature, in case you know it.
MBean blocks Subsection "MBean blocks"
\fIMBean 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:
Connection blocks Subsection "Connection blocks"
Connection blocks specify how to connect to an MBeanServer and what data to retrieve. The following configuration options are available: