1COLLECTD-JAVA(5) collectd COLLECTD-JAVA(5)
2
6 collectd-java - Documentation of collectd's "java plugin"
7
9 LoadPlugin "java"
10 <Plugin "java">
11 JVMArg "-verbose:jni"
12 JVMArg "-Djava.class.path=/opt/collectd/lib/collectd/bindings/java"
13 LoadPlugin "org.collectd.java.Foobar"
15 <Plugin "org.collectd.java.Foobar">
16 # To be parsed by the plugin
17 </Plugin>
18 </Plugin>
19
21 The Java plugin embeds a Java Virtual Machine (JVM) into collectd and
22 provides a Java interface to part of collectd's API. This makes it
23 possible to write additions to the daemon in Java.
24 This plugin is similar in nature to, but shares no code with, the Perl
26 plugin by Sebastian Harl, see collectd-perl(5) for details.
27
29 A short outline of this plugin's configuration can be seen in
30 "SYNOPSIS" above. For a complete list of all configuration options and
31 their semantics please read "Plugin "java"" in collectd.conf(5).
32
34 When writing additions for collectd in Java, the underlying C base is
35 mostly hidden from you. All complex data types are converted to their
36 Java counterparts before they're passed to your functions. These Java
37 classes reside in the org.collectd.api namespace.
38 The Java plugin will create one object of each class configured with
40 the LoadPlugin option. The constructor of this class can then register
41 "callback methods", i. e. methods that will be called by the daemon
42 when appropriate.
43 The available classes are:
45 org.collectd.api.Collectd
47 All API functions exported to Java are implemented as static
48 functions of this class. See "EXPORTED API FUNCTIONS" below.
49 org.collectd.api.OConfigValue
51 Corresponds to "oconfig_value_t", defined in
52 src/liboconfig/oconfig.h.
53 org.collectd.api.OConfigItem
55 Corresponds to "oconfig_item_t", defined in
56 src/liboconfig/oconfig.h.
57 org.collectd.api.DataSource
59 Corresponds to "data_source_t", defined in src/plugin.h.
60 org.collectd.api.DataSet
62 Corresponds to "data_set_t", defined in src/plugin.h.
63 org.collectd.api.ValueList
65 Corresponds to "value_list_t", defined in src/plugin.h.
66 org.collectd.api.Notification
68 Corresponds to "notification_t", defined in src/plugin.h.
69 In the remainder of this document, we'll use the short form of these
71 names, for example ValueList. In order to be able to use these
72 abbreviated names, you need to import the classes.
73
75 All collectd API functions that are available to Java plugins are
76 implemented as public static functions of the Collectd class. This
77 makes calling these functions pretty straight forward. For example, to
78 send an error message to the daemon, you'd do something like this:
79 Collectd.logError ("That wasn't chicken!");
81 The following are the currently exported functions.
83 registerConfig
85 Signature: int registerConfig (String name, CollectdConfigInterface
86 object);
87 Registers the config function of object with the daemon.
89 Returns zero upon success and non-zero when an error occurred.
91 See "config callback" below.
93 registerInit
95 Signature: int registerInit (String name, CollectdInitInterface
96 object);
97 Registers the init function of object with the daemon.
99 Returns zero upon success and non-zero when an error occurred.
101 See "init callback" below.
103 registerRead
105 Signature: int registerRead (String name, CollectdReadInterface object)
106 Registers the read function of object with the daemon.
108 Returns zero upon success and non-zero when an error occurred.
110 See "read callback" below.
112 registerWrite
114 Signature: int registerWrite (String name, CollectdWriteInterface
115 object)
116 Registers the write function of object with the daemon.
118 Returns zero upon success and non-zero when an error occurred.
120 See "write callback" below.
122 registerFlush
124 Signature: int registerFlush (String name, CollectdFlushInterface
125 object)
126 Registers the flush function of object with the daemon.
128 Returns zero upon success and non-zero when an error occurred.
130 See "flush callback" below.
132 registerShutdown
134 Signature: int registerShutdown (String name, CollectdShutdownInterface
135 object);
136 Registers the shutdown function of object with the daemon.
138 Returns zero upon success and non-zero when an error occurred.
140 See "shutdown callback" below.
142 registerLog
144 Signature: int registerLog (String name, CollectdLogInterface object);
145 Registers the log function of object with the daemon.
147 Returns zero upon success and non-zero when an error occurred.
149 See "log callback" below.
151 registerNotification
153 Signature: int registerNotification (String name,
154 CollectdNotificationInterface object);
155 Registers the notification function of object with the daemon.
157 Returns zero upon success and non-zero when an error occurred.
159 See "notification callback" below.
161 registerMatch
163 Signature: int registerMatch (String name,
164 CollectdMatchFactoryInterface object);
165 Registers the createMatch function of object with the daemon.
167 Returns zero upon success and non-zero when an error occurred.
169 See "match callback" below.
171 registerTarget
173 Signature: int registerTarget (String name,
174 CollectdTargetFactoryInterface object);
175 Registers the createTarget function of object with the daemon.
177 Returns zero upon success and non-zero when an error occurred.
179 See "target callback" below.
181 dispatchValues
183 Signature: int dispatchValues (ValueList)
184 Passes the values represented by the ValueList object to the
186 "plugin_dispatch_values" function of the daemon. The "data set" (or
187 list of "data sources") associated with the object are ignored, because
188 "plugin_dispatch_values" will automatically lookup the required data
189 set. It is therefore absolutely okay to leave this blank.
190 Returns zero upon success or non-zero upon failure.
192 getDS
194 Signature: DataSet getDS (String)
195 Returns the appropriate type or null if the type is not defined.
197 logError
199 Signature: void logError (String)
200 Sends a log message with severity ERROR to the daemon.
202 logWarning
204 Signature: void logWarning (String)
205 Sends a log message with severity WARNING to the daemon.
207 logNotice
209 Signature: void logNotice (String)
210 Sends a log message with severity NOTICE to the daemon.
212 logInfo
214 Signature: void logInfo (String)
215 Sends a log message with severity INFO to the daemon.
217 logDebug
219 Signature: void logDebug (String)
220 Sends a log message with severity DEBUG to the daemon.
222
224 When starting up, collectd creates an object of each configured class.
225 The constructor of this class should then register "callbacks" with the
226 daemon, using the appropriate static functions in Collectd, see
227 "EXPORTED API FUNCTIONS" above. To register a callback, the object
228 being passed to one of the register functions must implement an
229 appropriate interface, which are all in the org.collectd.api namespace.
230 A constructor may register any number of these callbacks, even none. An
232 object without callback methods is never actively called by collectd,
233 but may still call the exported API functions. One could, for example,
234 start a new thread in the constructor and dispatch (submit to the
235 daemon) values asynchronously, whenever one is available.
236 Each callback method is now explained in more detail:
238 config callback
240 Interface: org.collectd.api.CollectdConfigInterface
241 Signature: int config (OConfigItem ci)
243 This method is passed a OConfigItem object, if both, method and
245 configuration, are available. OConfigItem is the root of a tree
246 representing the configuration for this plugin. The root itself is the
247 representation of the <Plugin /> block, so in next to all cases the
248 children of the root are the first interesting objects.
249 To signal success, this method has to return zero. Anything else will
251 be considered an error condition and the plugin will be disabled
252 entirely.
253 See "registerConfig" above.
255 init callback
257 Interface: org.collectd.api.CollectdInitInterface
258 Signature: int init ()
260 This method is called after the configuration has been handled. It is
262 supposed to set up the plugin. e. g. start threads, open connections,
263 or check if can do anything useful at all.
264 To signal success, this method has to return zero. Anything else will
266 be considered an error condition and the plugin will be disabled
267 entirely.
268 See "registerInit" above.
270 read callback
272 Interface: org.collectd.api.CollectdReadInterface
273 Signature: int read ()
275 This method is called periodically and is supposed to gather statistics
277 in whatever fashion. These statistics are represented as a ValueList
278 object and sent to the daemon using dispatchValues.
279 To signal success, this method has to return zero. Anything else will
281 be considered an error condition and cause an appropriate message to be
282 logged. Currently, returning non-zero does not have any other effects.
283 In particular, Java "read"-methods are not suspended for increasing
284 intervals like C "read"-functions.
285 See "registerRead" above.
287 write callback
289 Interface: org.collectd.api.CollectdWriteInterface
290 Signature: int write (ValueList vl)
292 This method is called whenever a value is dispatched to the daemon. The
294 corresponding C "write"-functions are passed a "data_set_t", so they
295 can decide which values are absolute values (gauge) and which are
296 counter values. To get the corresponding "List<DataSource>", call the
297 getDataSource method of the ValueList object.
298 To signal success, this method has to return zero. Anything else will
300 be considered an error condition and cause an appropriate message to be
301 logged.
302 See "registerWrite" above.
304 flush callback
306 Interface: org.collectd.api.CollectdFlushInterface
307 Signature: int flush (int timeout, String identifier)
309 This method is called when the daemon received a flush command. This
311 can either be done using the "USR1" signal (see collectd(1)) or using
312 the unixsock plugin (see collectd-unixsock(5)).
313 If timeout is greater than zero, only values older than this number of
315 seconds should be flushed. To signal that all values should be flushed
316 regardless of age, this argument is set to a negative number.
317 The identifier specifies which value should be flushed. If it is not
319 possible to flush one specific value, flush all values. To signal that
320 all values should be flushed, this argument is set to null.
321 To signal success, this method has to return zero. Anything else will
323 be considered an error condition and cause an appropriate message to be
324 logged.
325 See "registerFlush" above.
327 shutdown callback
329 Interface: org.collectd.api.CollectdShutdownInterface
330 Signature: int shutdown ()
332 This method is called when the daemon is shutting down. You should not
334 rely on the destructor to clean up behind the object but use this
335 function instead.
336 To signal success, this method has to return zero. Anything else will
338 be considered an error condition and cause an appropriate message to be
339 logged.
340 See "registerShutdown" above.
342 log callback
344 Interface: org.collectd.api.CollectdLogInterface
345 Signature: void log (int severity, String message)
347 This callback can be used to receive log messages from the daemon.
349 The argument severity is one of:
351 · org.collectd.api.Collectd.LOG_ERR
353 · org.collectd.api.Collectd.LOG_WARNING
355 · org.collectd.api.Collectd.LOG_NOTICE
357 · org.collectd.api.Collectd.LOG_INFO
359 · org.collectd.api.Collectd.LOG_DEBUG
361 The function does not return any value.
363 See "registerLog" above.
365 notification callback
367 Interface: org.collectd.api.CollectdNotificationInterface
368 Signature: int notification (Notification n)
370 This callback can be used to receive notifications from the daemon.
372 To signal success, this method has to return zero. Anything else will
374 be considered an error condition and cause an appropriate message to be
375 logged.
376 See "registerNotification" above.
378 match callback
380 The match (and target, see "target callback" below) callbacks work a
381 bit different from the other callbacks above: You don't register a
382 match callback with the daemon directly, but you register a function
383 which, when called, creates an appropriate object. The object creating
384 the "match" objects is called "match factory".
385 See "registerMatch" above.
387 Factory object
389 Interface: org.collectd.api.CollectdMatchFactoryInterface
391 Signature: CollectdMatchInterface createMatch (OConfigItem ci);
393 Called by the daemon to create "match" objects.
395 Returns: A new object which implements the CollectdMatchInterface
397 interface.
398 Match object
400 Interface: org.collectd.api.CollectdMatchInterface
402 Signature: int match (DataSet ds, ValueList vl);
404 Called when processing a chain to determine whether or not a ValueList
406 matches. How values are matches is up to the implementing class.
407 Has to return one of:
409 · Collectd.FC_MATCH_NO_MATCH
411 · Collectd.FC_MATCH_MATCHES
413 target callback
415 The target (and match, see "match callback" above) callbacks work a bit
416 different from the other callbacks above: You don't register a target
417 callback with the daemon directly, but you register a function which,
418 when called, creates an appropriate object. The object creating the
419 "target" objects is called "target factory".
420 See "registerTarget" above.
422 Factory object
424 Interface: org.collectd.api.CollectdTargetFactoryInterface
426 Signature: CollectdTargetInterface createTarget (OConfigItem ci);
428 Called by the daemon to create "target" objects.
430 Returns: A new object which implements the CollectdTargetInterface
432 interface.
433 Target object
435 Interface: org.collectd.api.CollectdTargetInterface
437 Signature: int invoke (DataSet ds, ValueList vl);
439 Called when processing a chain to perform some action. The action
441 performed is up to the implementing class.
442 Has to return one of:
444 · Collectd.FC_TARGET_CONTINUE
446 · Collectd.FC_TARGET_STOP
448 · Collectd.FC_TARGET_RETURN
450
452 This short example demonstrates how to register a read callback with
453 the daemon:
454 import org.collectd.api.Collectd;
456 import org.collectd.api.ValueList;
457 import org.collectd.api.CollectdReadInterface;
459 public class Foobar implements CollectdReadInterface
461 {
462 public Foobar ()
463 {
464 Collectd.registerRead ("Foobar", this);
465 }
466 public int read ()
468 {
469 ValueList vl;
470 /* Do something... */
472 Collectd.dispatchValues (vl);
474 }
475 }
476
478 The following plugins are implemented in Java. Both, the LoadPlugin
479 option and the Plugin block must be inside the <Plugin java> block (see
480 above).
481 GenericJMX plugin
483 The GenericJMX plugin reads Managed Beans (MBeans) from an MBeanServer
484 using JMX. JMX is a generic framework to provide and query various
485 management information. The interface is used by Java processes to
486 provide internal statistics as well as by the Java Virtual Machine
487 (JVM) to provide information about the memory used, threads and so on.
488 The configuration of the GenericJMX plugin consists of two blocks:
490 MBean blocks that define a mapping of MBean attributes to the XtypesX
491 used by collectd, and Connection blocks which define the parameters
492 needed to connect to an MBeanServer and what data to collect. The
493 configuration of the SNMP plugin is similar in nature, in case you know
494 it.
495 MBean blocks
497 MBean blocks specify what data is retrieved from MBeans and how that
499 data is mapped on the collectd data types. The block requires one
500 string argument, a name. This name is used in the Connection blocks
501 (see below) to refer to a specific MBean block. Therefore, the names
502 must be unique.
503 The following options are recognized within MBean blocks:
505 ObjectName pattern
507 Sets the pattern which is used to retrieve MBeans from the
508 MBeanServer. If more than one MBean is returned you should use the
509 InstanceFrom option (see below) to make the identifiers unique.
510 See also:
512 <http://java.sun.com/javase/6/docs/api/javax/management/ObjectName.html>
513 InstancePrefix prefix
515 Prefixes the generated plugin instance with prefix. (optional)
516 InstanceFrom property
518 The object names used by JMX to identify MBeans include so called
519 XpropertiesX which are basically key-value-pairs. If the given
520 object name is not unique and multiple MBeans are returned, the
521 values of those properties usually differ. You can use this option
522 to build the plugin instance from the appropriate property values.
523 This option is optional and may be repeated to generate the plugin
524 instance from multiple property values.
525 <value /> blocks
527 The value blocks map one or more attributes of an MBean to a value
528 list in collectd. There must be at least one Value block within
529 each MBean block.
530 Type type
532 Sets the data set used within collectd to handle the values of
533 the MBean attribute.
534 InstancePrefix prefix
536 Works like the option of the same name directly beneath the
537 MBean block, but sets the type instance instead. (optional)
538 InstanceFrom prefix
540 Works like the option of the same name directly beneath the
541 MBean block, but sets the type instance instead. (optional)
542 PluginName name
544 When set, overrides the default setting for the plugin field
545 ("GenericJMX").
546 Table true|false
548 Set this to true if the returned attribute is a composite type.
549 If set to true, the keys within the composite type is appended
550 to the type instance.
551 Attribute path
553 Sets the name of the attribute from which to read the value.
554 You can access the keys of composite types by using a dot to
555 concatenate the key name to the attribute name. For example:
556 Xattrib0.key42X. If Table is set to true path must point to a
557 composite type, otherwise it must point to a numeric type.
558 Connection blocks
560 Connection blocks specify how to connect to an MBeanServer and what
562 data to retrieve. The following configuration options are available:
563 Host name
565 Host name used when dispatching the values to collectd. The option
566 sets this field only, it is not used to connect to anything and
567 doesn't need to be a real, resolvable name.
568 ServiceURL URL
570 Specifies how the MBeanServer can be reached. Any string accepted
571 by the JMXServiceURL is valid.
572 See also:
574 <http://java.sun.com/javase/6/docs/api/javax/management/remote/JMXServiceURL.html>
575 User name
577 Use name to authenticate to the server. If not configured,
578 XmonitorRoleX will be used.
579 Password password
581 Use password to authenticate to the server. If not given,
582 unauthenticated access is used.
583 InstancePrefix prefix
585 Prefixes the generated plugin instance with prefix. If a second
586 InstancePrefix is specified in a referenced MBean block, the prefix
587 specified in the Connection block will appear at the beginning of
588 the plugin instance, the prefix specified in the MBean block will
589 be appended to it.
590 Collect mbean_block_name
592 Configures which of the MBean blocks to use with this connection.
593 May be repeated to collect multiple MBeans from this server.
594
596 collectd(1), collectd.conf(5), collectd-perl(5), types.db(5)
597
599 Florian Forster <octo at collectd.org>
6005.9.2 2019-09-16 COLLECTD-JAVA(5)