1COLLECTD-JAVA(5)                   collectd                   COLLECTD-JAVA(5)
2
3
4

NAME

6       collectd-java - Documentation of collectd's "java plugin"
7

SYNOPSIS

9        LoadPlugin "java"
10        <Plugin "java">
11          JVMArg "-verbose:jni"
12          JVMArg "-Djava.class.path=/opt/collectd/lib/collectd/bindings/java"
13
14          LoadPlugin "org.collectd.java.Foobar"
15          <Plugin "org.collectd.java.Foobar">
16            # To be parsed by the plugin
17          </Plugin>
18        </Plugin>
19

DESCRIPTION

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

CONFIGURATION

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

OVERVIEW

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
39       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
44       The available classes are:
45
46       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
50       org.collectd.api.OConfigValue
51           Corresponds to "oconfig_value_t", defined in
52           src/liboconfig/oconfig.h.
53
54       org.collectd.api.OConfigItem
55           Corresponds to "oconfig_item_t", defined in
56           src/liboconfig/oconfig.h.
57
58       org.collectd.api.DataSource
59           Corresponds to "data_source_t", defined in src/plugin.h.
60
61       org.collectd.api.DataSet
62           Corresponds to "data_set_t", defined in src/plugin.h.
63
64       org.collectd.api.ValueList
65           Corresponds to "value_list_t", defined in src/plugin.h.
66
67       org.collectd.api.Notification
68           Corresponds to "notification_t", defined in src/plugin.h.
69
70       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

EXPORTED API FUNCTIONS

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
80         Collectd.logError ("That wasn't chicken!");
81
82       The following are the currently exported functions.
83
84   registerConfig
85       Signature: int registerConfig (String name, CollectdConfigInterface
86       object);
87
88       Registers the config function of object with the daemon.
89
90       Returns zero upon success and non-zero when an error occurred.
91
92       See "config callback" below.
93
94   registerInit
95       Signature: int registerInit (String name, CollectdInitInterface
96       object);
97
98       Registers the init function of object with the daemon.
99
100       Returns zero upon success and non-zero when an error occurred.
101
102       See "init callback" below.
103
104   registerRead
105       Signature: int registerRead (String name, CollectdReadInterface object)
106
107       Registers the read function of object with the daemon.
108
109       Returns zero upon success and non-zero when an error occurred.
110
111       See "read callback" below.
112
113   registerWrite
114       Signature: int registerWrite (String name, CollectdWriteInterface
115       object)
116
117       Registers the write function of object with the daemon.
118
119       Returns zero upon success and non-zero when an error occurred.
120
121       See "write callback" below.
122
123   registerFlush
124       Signature: int registerFlush (String name, CollectdFlushInterface
125       object)
126
127       Registers the flush function of object with the daemon.
128
129       Returns zero upon success and non-zero when an error occurred.
130
131       See "flush callback" below.
132
133   registerShutdown
134       Signature: int registerShutdown (String name, CollectdShutdownInterface
135       object);
136
137       Registers the shutdown function of object with the daemon.
138
139       Returns zero upon success and non-zero when an error occurred.
140
141       See "shutdown callback" below.
142
143   registerLog
144       Signature: int registerLog (String name, CollectdLogInterface object);
145
146       Registers the log function of object with the daemon.
147
148       Returns zero upon success and non-zero when an error occurred.
149
150       See "log callback" below.
151
152   registerNotification
153       Signature: int registerNotification (String name,
154       CollectdNotificationInterface object);
155
156       Registers the notification function of object with the daemon.
157
158       Returns zero upon success and non-zero when an error occurred.
159
160       See "notification callback" below.
161
162   registerMatch
163       Signature: int registerMatch (String name,
164       CollectdMatchFactoryInterface object);
165
166       Registers the createMatch function of object with the daemon.
167
168       Returns zero upon success and non-zero when an error occurred.
169
170       See "match callback" below.
171
172   registerTarget
173       Signature: int registerTarget (String name,
174       CollectdTargetFactoryInterface object);
175
176       Registers the createTarget function of object with the daemon.
177
178       Returns zero upon success and non-zero when an error occurred.
179
180       See "target callback" below.
181
182   dispatchValues
183       Signature: int dispatchValues (ValueList)
184
185       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
191       Returns zero upon success or non-zero upon failure.
192
193   getDS
194       Signature: DataSet getDS (String)
195
196       Returns the appropriate type or null if the type is not defined.
197
198   logError
199       Signature: void logError (String)
200
201       Sends a log message with severity ERROR to the daemon.
202
203   logWarning
204       Signature: void logWarning (String)
205
206       Sends a log message with severity WARNING to the daemon.
207
208   logNotice
209       Signature: void logNotice (String)
210
211       Sends a log message with severity NOTICE to the daemon.
212
213   logInfo
214       Signature: void logInfo (String)
215
216       Sends a log message with severity INFO to the daemon.
217
218   logDebug
219       Signature: void logDebug (String)
220
221       Sends a log message with severity DEBUG to the daemon.
222

REGISTERING CALLBACKS

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
231       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
237       Each callback method is now explained in more detail:
238
239   config callback
240       Interface: org.collectd.api.CollectdConfigInterface
241
242       Signature: int config (OConfigItem ci)
243
244       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
250       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
254       See "registerConfig" above.
255
256   init callback
257       Interface: org.collectd.api.CollectdInitInterface
258
259       Signature: int init ()
260
261       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
265       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
269       See "registerInit" above.
270
271   read callback
272       Interface: org.collectd.api.CollectdReadInterface
273
274       Signature: int read ()
275
276       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
280       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
286       See "registerRead" above.
287
288   write callback
289       Interface: org.collectd.api.CollectdWriteInterface
290
291       Signature: int write (ValueList vl)
292
293       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
299       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
303       See "registerWrite" above.
304
305   flush callback
306       Interface: org.collectd.api.CollectdFlushInterface
307
308       Signature: int flush (int timeout, String identifier)
309
310       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
314       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
318       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
322       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
326       See "registerFlush" above.
327
328   shutdown callback
329       Interface: org.collectd.api.CollectdShutdownInterface
330
331       Signature: int shutdown ()
332
333       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
337       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
341       See "registerShutdown" above.
342
343   log callback
344       Interface: org.collectd.api.CollectdLogInterface
345
346       Signature: void log (int severity, String message)
347
348       This callback can be used to receive log messages from the daemon.
349
350       The argument severity is one of:
351
352       ·   org.collectd.api.Collectd.LOG_ERR
353
354       ·   org.collectd.api.Collectd.LOG_WARNING
355
356       ·   org.collectd.api.Collectd.LOG_NOTICE
357
358       ·   org.collectd.api.Collectd.LOG_INFO
359
360       ·   org.collectd.api.Collectd.LOG_DEBUG
361
362       The function does not return any value.
363
364       See "registerLog" above.
365
366   notification callback
367       Interface: org.collectd.api.CollectdNotificationInterface
368
369       Signature: int notification (Notification n)
370
371       This callback can be used to receive notifications from the daemon.
372
373       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
377       See "registerNotification" above.
378
379   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
386       See "registerMatch" above.
387
388       Factory object
389
390       Interface: org.collectd.api.CollectdMatchFactoryInterface
391
392       Signature: CollectdMatchInterface createMatch (OConfigItem ci);
393
394       Called by the daemon to create "match" objects.
395
396       Returns: A new object which implements the CollectdMatchInterface
397       interface.
398
399       Match object
400
401       Interface: org.collectd.api.CollectdMatchInterface
402
403       Signature: int match (DataSet ds, ValueList vl);
404
405       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
408       Has to return one of:
409
410       ·   Collectd.FC_MATCH_NO_MATCH
411
412       ·   Collectd.FC_MATCH_MATCHES
413
414   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
421       See "registerTarget" above.
422
423       Factory object
424
425       Interface: org.collectd.api.CollectdTargetFactoryInterface
426
427       Signature: CollectdTargetInterface createTarget (OConfigItem ci);
428
429       Called by the daemon to create "target" objects.
430
431       Returns: A new object which implements the CollectdTargetInterface
432       interface.
433
434       Target object
435
436       Interface: org.collectd.api.CollectdTargetInterface
437
438       Signature: int invoke (DataSet ds, ValueList vl);
439
440       Called when processing a chain to perform some action. The action
441       performed is up to the implementing class.
442
443       Has to return one of:
444
445       ·   Collectd.FC_TARGET_CONTINUE
446
447       ·   Collectd.FC_TARGET_STOP
448
449       ·   Collectd.FC_TARGET_RETURN
450

EXAMPLE

452       This short example demonstrates how to register a read callback with
453       the daemon:
454
455         import org.collectd.api.Collectd;
456         import org.collectd.api.ValueList;
457
458         import org.collectd.api.CollectdReadInterface;
459
460         public class Foobar implements CollectdReadInterface
461         {
462           public Foobar ()
463           {
464             Collectd.registerRead ("Foobar", this);
465           }
466
467           public int read ()
468           {
469             ValueList vl;
470
471             /* Do something... */
472
473             Collectd.dispatchValues (vl);
474           }
475         }
476

PLUGINS

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
482   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
489       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
496       MBean blocks
497
498       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
504       The following options are recognized within MBean blocks:
505
506       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
511           See also:
512           <http://java.sun.com/javase/6/docs/api/javax/management/ObjectName.html>
513
514       InstancePrefix prefix
515           Prefixes the generated plugin instance with prefix. (optional)
516
517       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
526       <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
531           Type type
532               Sets the data set used within collectd to handle the values of
533               the MBean attribute.
534
535           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
539           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
543           PluginName name
544               When set, overrides the default setting for the plugin field
545               ("GenericJMX").
546
547           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
552           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
559       Connection blocks
560
561       Connection blocks specify how to connect to an MBeanServer and what
562       data to retrieve. The following configuration options are available:
563
564       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
569       ServiceURL URL
570           Specifies how the MBeanServer can be reached. Any string accepted
571           by the JMXServiceURL is valid.
572
573           See also:
574           <http://java.sun.com/javase/6/docs/api/javax/management/remote/JMXServiceURL.html>
575
576       User name
577           Use name to authenticate to the server. If not configured,
578           XmonitorRoleX will be used.
579
580       Password password
581           Use password to authenticate to the server. If not given,
582           unauthenticated access is used.
583
584       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
591       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

SEE ALSO

596       collectd(1), collectd.conf(5), collectd-perl(5), types.db(5)
597

AUTHOR

599       Florian Forster <octo at collectd.org>
600
601
602
6035.9.1.599.gbb5cfbc                2020-03-08                  COLLECTD-JAVA(5)
Impressum