Merge branch 'collectd-5.5'
[collectd.git] / src / collectd-java.pod
1 =encoding UTF-8
2
3 =head1 NAME
4
5 collectd-java - Documentation of collectd's "java plugin"
6
7 =head1 SYNOPSIS
8
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
20 =head1 DESCRIPTION
21
22 The I<Java> plugin embeds a I<Java Virtual Machine> (JVM) into I<collectd> and
23 provides a Java interface to part of collectd's API. This makes it possible to
24 write additions to the daemon in Java.
25
26 This plugin is similar in nature to, but shares no code with, the I<Perl>
27 plugin by Sebastian Harl, see L<collectd-perl(5)> for details.
28
29 =head1 CONFIGURATION
30
31 A short outline of this plugin's configuration can be seen in L<"SYNOPSIS">
32 above. For a complete list of all configuration options and their semantics
33 please read L<collectd.conf(5)/Plugin C<java>>.
34
35 =head1 OVERVIEW
36
37 When writing additions for collectd in Java, the underlying C base is mostly
38 hidden from you. All complex data types are converted to their Java counterparts
39 before they're passed to your functions. These Java classes reside in the
40 I<org.collectd.api> namespace.
41
42 The I<Java> plugin will create one object of each class configured with the
43 B<LoadPlugin> option. The constructor of this class can then register "callback
44 methods", i.E<nbsp>e. methods that will be called by the daemon when
45 appropriate.
46
47 The available classes are:
48
49 =over 4
50
51 =item B<org.collectd.api.Collectd>
52
53 All API functions exported to Java are implemented as static functions of this
54 class. See L<"EXPORTED API FUNCTIONS"> below.
55
56 =item B<org.collectd.api.OConfigValue>
57
58 Corresponds to C<oconfig_value_t>, defined in F<src/liboconfig/oconfig.h>.
59
60 =item B<org.collectd.api.OConfigItem>
61
62 Corresponds to C<oconfig_item_t>, defined in F<src/liboconfig/oconfig.h>.
63
64 =item B<org.collectd.api.DataSource>
65
66 Corresponds to C<data_source_t>, defined in F<src/plugin.h>.
67
68 =item B<org.collectd.api.DataSet>
69
70 Corresponds to C<data_set_t>, defined in F<src/plugin.h>.
71
72 =item B<org.collectd.api.ValueList>
73
74 Corresponds to C<value_list_t>, defined in F<src/plugin.h>.
75
76 =item B<org.collectd.api.Notification>
77
78 Corresponds to C<notification_t>, defined in F<src/plugin.h>.
79
80 =back
81
82 In the remainder of this document, we'll use the short form of these names, for
83 example B<ValueList>. In order to be able to use these abbreviated names, you
84 need to B<import> the classes.
85
86 =head1 EXPORTED API FUNCTIONS
87
88 All collectd API functions that are available to Java plugins are implemented
89 as I<publicE<nbsp>static> functions of the B<Collectd> class. This makes
90 calling these functions pretty straight forward. For example, to send an error
91 message to the daemon, you'd do something like this:
92
93   Collectd.logError ("That wasn't chicken!");
94
95 The following are the currently exported functions.
96
97 =head2 registerConfig
98
99 Signature: I<int> B<registerConfig> (I<String> name,
100 I<CollectdConfigInterface> object);
101
102 Registers the B<config> function of I<object> with the daemon.
103
104 Returns zero upon success and non-zero when an error occurred.
105
106 See L<"config callback"> below.
107
108 =head2 registerInit
109
110 Signature: I<int> B<registerInit> (I<String> name,
111 I<CollectdInitInterface> object);
112
113 Registers the B<init> function of I<object> with the daemon.
114
115 Returns zero upon success and non-zero when an error occurred.
116
117 See L<"init callback"> below.
118
119 =head2 registerRead
120
121 Signature: I<int> B<registerRead> (I<String> name,
122 I<CollectdReadInterface> object)
123
124 Registers the B<read> function of I<object> with the daemon.
125
126 Returns zero upon success and non-zero when an error occurred.
127
128 See L<"read callback"> below.
129
130 =head2 registerWrite
131
132 Signature: I<int> B<registerWrite> (I<String> name,
133 I<CollectdWriteInterface> object)
134
135 Registers the B<write> function of I<object> with the daemon.
136
137 Returns zero upon success and non-zero when an error occurred.
138
139 See L<"write callback"> below.
140
141 =head2 registerFlush
142
143 Signature: I<int> B<registerFlush> (I<String> name,
144 I<CollectdFlushInterface> object)
145
146 Registers the B<flush> function of I<object> with the daemon.
147
148 Returns zero upon success and non-zero when an error occurred.
149
150 See L<"flush callback"> below.
151
152 =head2 registerShutdown
153
154 Signature: I<int> B<registerShutdown> (I<String> name,
155 I<CollectdShutdownInterface> object);
156
157 Registers the B<shutdown> function of I<object> with the daemon.
158
159 Returns zero upon success and non-zero when an error occurred.
160
161 See L<"shutdown callback"> below.
162
163 =head2 registerLog
164
165 Signature: I<int> B<registerLog> (I<String> name,
166 I<CollectdLogInterface> object);
167
168 Registers the B<log> function of I<object> with the daemon.
169
170 Returns zero upon success and non-zero when an error occurred.
171
172 See L<"log callback"> below.
173
174 =head2 registerNotification
175
176 Signature: I<int> B<registerNotification> (I<String> name,
177 I<CollectdNotificationInterface> object);
178
179 Registers the B<notification> function of I<object> with the daemon.
180
181 Returns zero upon success and non-zero when an error occurred.
182
183 See L<"notification callback"> below.
184
185 =head2 registerMatch
186
187 Signature: I<int> B<registerMatch> (I<String> name,
188 I<CollectdMatchFactoryInterface> object);
189
190 Registers the B<createMatch> function of I<object> with the daemon.
191
192 Returns zero upon success and non-zero when an error occurred.
193
194 See L<"match callback"> below.
195
196 =head2 registerTarget
197
198 Signature: I<int> B<registerTarget> (I<String> name,
199 I<CollectdTargetFactoryInterface> object);
200
201 Registers the B<createTarget> function of I<object> with the daemon.
202
203 Returns zero upon success and non-zero when an error occurred.
204
205 See L<"target callback"> below.
206
207 =head2 dispatchValues
208
209 Signature: I<int> B<dispatchValues> (I<ValueList>)
210
211 Passes the values represented by the B<ValueList> object to the
212 C<plugin_dispatch_values> function of the daemon. The "data set" (or list of
213 "data sources") associated with the object are ignored, because
214 C<plugin_dispatch_values> will automatically lookup the required data set. It
215 is therefore absolutely okay to leave this blank.
216
217 Returns zero upon success or non-zero upon failure.
218
219 =head2 getDS
220
221 Signature: I<DataSet> B<getDS> (I<String>)
222
223 Returns the appropriate I<type> or B<null> if the type is not defined.
224
225 =head2 logError
226
227 Signature: I<void> B<logError> (I<String>)
228
229 Sends a log message with severity B<ERROR> to the daemon.
230
231 =head2 logWarning
232
233 Signature: I<void> B<logWarning> (I<String>)
234
235 Sends a log message with severity B<WARNING> to the daemon.
236
237 =head2 logNotice
238
239 Signature: I<void> B<logNotice> (I<String>)
240
241 Sends a log message with severity B<NOTICE> to the daemon.
242
243 =head2 logInfo
244
245 Signature: I<void> B<logInfo> (I<String>)
246
247 Sends a log message with severity B<INFO> to the daemon.
248
249 =head2 logDebug
250
251 Signature: I<void> B<logDebug> (I<String>)
252
253 Sends a log message with severity B<DEBUG> to the daemon.
254
255 =head1 REGISTERING CALLBACKS
256
257 When starting up, collectd creates an object of each configured class. The
258 constructor of this class should then register "callbacks" with the daemon,
259 using the appropriate static functions in B<Collectd>,
260 see L<"EXPORTED API FUNCTIONS"> above. To register a callback, the object being
261 passed to one of the register functions must implement an appropriate
262 interface, which are all in the B<org.collectd.api> namespace.
263
264 A constructor may register any number of these callbacks, even none. An object
265 without callback methods is never actively called by collectd, but may still
266 call the exported API functions. One could, for example, start a new thread in
267 the constructor and dispatch (submit to the daemon) values asynchronously,
268 whenever one is available.
269
270 Each callback method is now explained in more detail:
271
272 =head2 config callback
273
274 Interface: B<org.collectd.api.CollectdConfigInterface>
275
276 Signature: I<int> B<config> (I<OConfigItem> ci)
277
278 This method is passed a B<OConfigItem> object, if both, method and
279 configuration, are available. B<OConfigItem> is the root of a tree representing
280 the configuration for this plugin. The root itself is the representation of the
281 B<E<lt>PluginE<nbsp>/E<gt>> block, so in next to all cases the children of the
282 root are the first interesting objects.
283
284 To signal success, this method has to return zero. Anything else will be
285 considered an error condition and the plugin will be disabled entirely.
286
287 See L<"registerConfig"> above.
288
289 =head2 init callback
290
291 Interface: B<org.collectd.api.CollectdInitInterface>
292
293 Signature: I<int> B<init> ()
294
295 This method is called after the configuration has been handled. It is
296 supposed to set up the plugin. e.E<nbsp>g. start threads, open connections, or
297 check if can do anything useful at all.
298
299 To signal success, this method has to return zero. Anything else will be
300 considered an error condition and the plugin will be disabled entirely.
301
302 See L<"registerInit"> above.
303
304 =head2 read callback
305
306 Interface: B<org.collectd.api.CollectdReadInterface>
307
308 Signature: I<int> B<read> ()
309
310 This method is called periodically and is supposed to gather statistics in
311 whatever fashion. These statistics are represented as a B<ValueList> object and
312 sent to the daemon using L<dispatchValues|"dispatchValues">.
313
314 To signal success, this method has to return zero. Anything else will be
315 considered an error condition and cause an appropriate message to be logged.
316 Currently, returning non-zero does not have any other effects. In particular,
317 Java "read"-methods are not suspended for increasing intervals like C
318 "read"-functions.
319
320 See L<"registerRead"> above.
321
322 =head2 write callback
323
324 Interface: B<org.collectd.api.CollectdWriteInterface>
325
326 Signature: I<int> B<write> (I<ValueList> vl)
327
328 This method is called whenever a value is dispatched to the daemon. The
329 corresponding C "write"-functions are passed a C<data_set_t>, so they can
330 decide which values are absolute values (gauge) and which are counter values.
331 To get the corresponding C<ListE<lt>DataSourceE<gt>>, call the B<getDataSource>
332 method of the B<ValueList> object.
333
334 To signal success, this method has to return zero. Anything else will be
335 considered an error condition and cause an appropriate message to be logged.
336
337 See L<"registerWrite"> above.
338
339 =head2 flush callback
340
341 Interface: B<org.collectd.api.CollectdFlushInterface>
342
343 Signature: I<int> B<flush> (I<int> timeout, I<String> identifier)
344
345 This method is called when the daemon received a flush command. This can either
346 be done using the C<USR1> signal (see L<collectd(1)>) or using the I<unixsock>
347 plugin (see L<collectd-unixsock(5)>).
348
349 If I<timeout> is greater than zero, only values older than this number of
350 seconds should be flushed. To signal that all values should be flushed
351 regardless of age, this argument is set to a negative number.
352
353 The I<identifier> specifies which value should be flushed. If it is not
354 possible to flush one specific value, flush all values. To signal that all
355 values should be flushed, this argument is set to I<null>.
356
357 To signal success, this method has to return zero. Anything else will be
358 considered an error condition and cause an appropriate message to be logged.
359
360 See L<"registerFlush"> above.
361
362 =head2 shutdown callback
363
364 Interface: B<org.collectd.api.CollectdShutdownInterface>
365
366 Signature: I<int> B<shutdown> ()
367
368 This method is called when the daemon is shutting down. You should not rely on
369 the destructor to clean up behind the object but use this function instead.
370
371 To signal success, this method has to return zero. Anything else will be
372 considered an error condition and cause an appropriate message to be logged.
373
374 See L<"registerShutdown"> above.
375
376 =head2 log callback
377
378 Interface: B<org.collectd.api.CollectdLogInterface>
379
380 Signature: I<void> B<log> (I<int> severity, I<String> message)
381
382 This callback can be used to receive log messages from the daemon.
383
384 The argument I<severity> is one of:
385
386 =over 4
387
388 =item *
389
390 org.collectd.api.Collectd.LOG_ERR
391
392 =item *
393
394 org.collectd.api.Collectd.LOG_WARNING
395
396 =item *
397
398 org.collectd.api.Collectd.LOG_NOTICE
399
400 =item *
401
402 org.collectd.api.Collectd.LOG_INFO
403
404 =item *
405
406 org.collectd.api.Collectd.LOG_DEBUG
407
408 =back
409
410 The function does not return any value.
411
412 See L<"registerLog"> above.
413
414 =head2 notification callback
415
416 Interface: B<org.collectd.api.CollectdNotificationInterface>
417
418 Signature: I<int> B<notification> (I<Notification> n)
419
420 This callback can be used to receive notifications from the daemon.
421
422 To signal success, this method has to return zero. Anything else will be
423 considered an error condition and cause an appropriate message to be logged.
424
425 See L<"registerNotification"> above.
426
427 =head2 match callback
428
429 The match (and target, see L<"target callback"> below) callbacks work a bit
430 different from the other callbacks above: You don't register a match callback
431 with the daemon directly, but you register a function which, when called,
432 creates an appropriate object. The object creating the "match" objects is
433 called "match factory".
434
435 See L<"registerMatch"> above.
436
437 =head3 Factory object
438
439 Interface: B<org.collectd.api.CollectdMatchFactoryInterface>
440
441 Signature: I<CollectdMatchInterface> B<createMatch>
442 (I<OConfigItem> ci);
443
444 Called by the daemon to create "match" objects.
445
446 Returns: A new object which implements the B<CollectdMatchInterface> interface.
447
448 =head3 Match object
449
450 Interface: B<org.collectd.api.CollectdMatchInterface>
451
452 Signature: I<int> B<match> (I<DataSet> ds, I<ValueList> vl);
453
454 Called when processing a chain to determine whether or not a I<ValueList>
455 matches. How values are matches is up to the implementing class.
456
457 Has to return one of:
458
459 =over 4
460
461 =item *
462
463 B<Collectd.FC_MATCH_NO_MATCH>
464
465 =item *
466
467 B<Collectd.FC_MATCH_MATCHES>
468
469 =back
470
471 =head2 target callback
472
473 The target (and match, see L<"match callback"> above) callbacks work a bit
474 different from the other callbacks above: You don't register a target callback
475 with the daemon directly, but you register a function which, when called,
476 creates an appropriate object. The object creating the "target" objects is
477 called "target factory".
478
479 See L<"registerTarget"> above.
480
481 =head3 Factory object
482
483 Interface: B<org.collectd.api.CollectdTargetFactoryInterface>
484
485 Signature: I<CollectdTargetInterface> B<createTarget>
486 (I<OConfigItem> ci);
487
488 Called by the daemon to create "target" objects.
489
490 Returns: A new object which implements the B<CollectdTargetInterface>
491 interface.
492
493 =head3 Target object
494
495 Interface: B<org.collectd.api.CollectdTargetInterface>
496
497 Signature: I<int> B<invoke> (I<DataSet> ds, I<ValueList> vl);
498
499 Called when processing a chain to perform some action. The action performed is
500 up to the implementing class.
501
502 Has to return one of:
503
504 =over 4
505
506 =item *
507
508 B<Collectd.FC_TARGET_CONTINUE>
509
510 =item *
511
512 B<Collectd.FC_TARGET_STOP>
513
514 =item *
515
516 B<Collectd.FC_TARGET_RETURN>
517
518 =back
519
520 =head1 EXAMPLE
521
522 This short example demonstrates how to register a read callback with the
523 daemon:
524
525   import org.collectd.api.Collectd;
526   import org.collectd.api.ValueList;
527   
528   import org.collectd.api.CollectdReadInterface;
529   
530   public class Foobar implements CollectdReadInterface
531   {
532     public Foobar ()
533     {
534       Collectd.registerRead ("Foobar", this);
535     }
536     
537     public int read ()
538     {
539       ValueList vl;
540       
541       /* Do something... */
542       
543       Collectd.dispatchValues (vl);
544     }
545   }
546
547 =head1 PLUGINS
548
549 The following plugins are implemented in I<Java>. Both, the B<LoadPlugin>
550 option and the B<Plugin> block must be inside the
551 B<E<lt>PluginE<nbsp>javaE<gt>> block (see above).
552
553 =head2 GenericJMX plugin
554
555 The GenericJMX plugin reads I<Managed Beans> (MBeans) from an I<MBeanServer>
556 using JMX. JMX is a generic framework to provide and query various management
557 information. The interface is used by Java processes to provide internal
558 statistics as well as by the I<Java Virtual Machine> (JVM) to provide
559 information about the memory used, threads and so on. 
560
561 The configuration of the I<GenericJMX plugin> consists of two blocks: I<MBean>
562 blocks that define a mapping of MBean attributes to the “types” used by
563 I<collectd>, and I<Connection> blocks which define the parameters needed to
564 connect to an I<MBeanServer> and what data to collect. The configuration of the
565 I<SNMP plugin> is similar in nature, in case you know it.
566
567 =head3   MBean blocks
568
569 I<MBean> blocks specify what data is retrieved from I<MBeans> and how that data
570 is mapped on the I<collectd> data types. The block requires one string
571 argument, a name. This name is used in the I<Connection> blocks (see below) to
572 refer to a specific I<MBean> block. Therefore, the names must be unique.
573
574 The following options are recognized within I<MBean> blocks: 
575
576 =over 4
577
578 =item B<ObjectName> I<pattern>
579
580 Sets the pattern which is used to retrieve I<MBeans> from the I<MBeanServer>.
581 If more than one MBean is returned you should use the B<InstanceFrom> option
582 (see below) to make the identifiers unique.
583
584 See also:
585 L<http://java.sun.com/javase/6/docs/api/javax/management/ObjectName.html>
586
587 =item B<InstancePrefix> I<prefix>
588
589 Prefixes the generated I<plugin instance> with I<prefix>. I<(optional)>
590
591 =item B<InstanceFrom> I<property>
592
593 The I<object names> used by JMX to identify I<MBeans> include so called
594 I<“properties”> which are basically key-value-pairs. If the given object name
595 is not unique and multiple MBeans are returned, the values of those properties
596 usually differ. You can use this option to build the I<plugin instance> from
597 the appropriate property values. This option is optional and may be repeated to
598 generate the I<plugin instance> from multiple property values. 
599
600 =item B<E<lt>value /E<gt>> blocks
601
602 The I<value> blocks map one or more attributes of an I<MBean> to a value list
603 in I<collectd>. There must be at least one Value block within each I<MBean>
604 block.
605
606 =over 4
607
608 =item B<Type> type
609
610 Sets the data set used within I<collectd> to handle the values of the I<MBean>
611 attribute.
612
613 =item B<InstancePrefix> I<prefix>
614
615 Works like the option of the same name directly beneath the I<MBean> block, but
616 sets the type instance instead. I<(optional)>
617
618 =item B<InstanceFrom> I<prefix>
619
620 Works like the option of the same name directly beneath the I<MBean> block, but
621 sets the type instance instead. I<(optional)>
622
623 =item B<PluginName> I<name>
624
625 When set, overrides the default setting for the I<plugin> field
626 (C<GenericJMX>).
627
628 =item B<Table> B<true>|B<false>
629
630 Set this to true if the returned attribute is a I<composite type>. If set to
631 true, the keys within the I<composite type> is appended to the
632 I<type instance>.
633
634 =item B<Attribute> I<path>
635
636 Sets the name of the attribute from which to read the value. You can access the
637 keys of composite types by using a dot to concatenate the key name to the
638 attribute name. For example: “attrib0.key42”. If B<Table> is set to B<true>
639 I<path> must point to a I<composite type>, otherwise it must point to a numeric
640 type. 
641
642 =back
643
644 =back
645
646 =head3 Connection blocks
647
648 Connection blocks specify I<how> to connect to an I<MBeanServer> and what data
649 to retrieve. The following configuration options are available:
650
651 =over 4
652
653 =item B<Host> I<name>
654
655 Host name used when dispatching the values to I<collectd>. The option sets this
656 field only, it is I<not> used to connect to anything and doesn't need to be a
657 real, resolvable name.
658
659 =item B<ServiceURL> I<URL>
660
661 Specifies how the I<MBeanServer> can be reached. Any string accepted by the
662 I<JMXServiceURL> is valid.
663
664 See also:
665 L<http://java.sun.com/javase/6/docs/api/javax/management/remote/JMXServiceURL.html>
666
667 =item B<User> I<name>
668
669 Use I<name> to authenticate to the server. If not configured, “monitorRole”
670 will be used.
671
672 =item B<Password> I<password>
673
674 Use I<password> to authenticate to the server. If not given, unauthenticated
675 access is used.
676
677 =item B<InstancePrefix> I<prefix>
678
679 Prefixes the generated I<plugin instance> with I<prefix>. If a second
680 I<InstancePrefix> is specified in a referenced I<MBean> block, the prefix
681 specified in the I<Connection> block will appear at the beginning of the
682 I<plugin instance>, the prefix specified in the I<MBean> block will be appended
683 to it.
684
685 =item B<Collect> I<mbean_block_name>
686
687 Configures which of the I<MBean> blocks to use with this connection. May be
688 repeated to collect multiple I<MBeans> from this server. 
689
690 =back
691
692 =head1 SEE ALSO
693
694 L<collectd(1)>,
695 L<collectd.conf(5)>,
696 L<collectd-perl(5)>,
697 L<types.db(5)>
698
699 =head1 AUTHOR
700
701 Florian Forster E<lt>octoE<nbsp>atE<nbsp>collectd.orgE<gt>
702