Code

Fix compilation error with plugin_register_shutdown
[collectd.git] / src / collectd-java.pod
1 =head1 NAME
3 collectd-java - Documentation of collectd's "java plugin"
5 =head1 SYNOPSIS
7  LoadPlugin "java"
8  <Plugin "java">
9    JVMArg "-verbose:jni"
10    JVMArg "-Djava.class.path=/opt/collectd/lib/collectd/bindings/java"
11    
12    LoadPlugin "org.collectd.java.Foobar"
13    <Plugin "org.collectd.java.Foobar">
14      # To be parsed by the plugin
15    </Plugin>
16  </Plugin>
18 =head1 DESCRIPTION
20 The I<Java> plugin embeds a I<Java Virtual Machine> (JVM) into I<collectd> and
21 provides a Java interface to part of collectd's API. This makes it possible to
22 write additions to the daemon in Java.
24 This plugin is similar in nature to, but shares no code with, the I<Perl>
25 plugin by Sebastian Harl, see L<collectd-perl(5)> for details.
27 =head1 CONFIGURATION
29 A short outline of this plugin's configuration can be seen in L<"SYNOPSIS">
30 above. For a complete list of all configuration options and their semantics
31 please read L<collectd.conf(5)/Plugin C<java>>.
33 =head1 OVERVIEW
35 When writing additions for collectd in Java, the underlying C base is mostly
36 hidden from you. All complex data types are converted to their Java counterparts
37 before they're passed to your functions. These Java classes reside in the
38 I<org.collectd.api> namespace.
40 The I<Java> plugin will create one object of each class configured with the
41 B<LoadPlugin> option. The constructor of this class can then register "callback
42 methods", i.E<nbsp>e. methods that will be called by the daemon when
43 appropriate.
45 The available classes are:
47 =over 4
49 =item B<org.collectd.api.Collectd>
51 All API functions exported to Java are implemented as static functions of this
52 class. See L<"EXPORTED API FUNCTIONS"> below.
54 =item B<org.collectd.api.OConfigValue>
56 Corresponds to C<oconfig_value_t>, defined in F<src/liboconfig/oconfig.h>.
58 =item B<org.collectd.api.OConfigItem>
60 Corresponds to C<oconfig_item_t>, defined in F<src/liboconfig/oconfig.h>.
62 =item B<org.collectd.api.DataSource>
64 Corresponds to C<data_source_t>, defined in F<src/plugin.h>.
66 =item B<org.collectd.api.DataSet>
68 Corresponds to C<data_set_t>, defined in F<src/plugin.h>.
70 =item B<org.collectd.api.ValueList>
72 Corresponds to C<value_list_t>, defined in F<src/plugin.h>.
74 =item B<org.collectd.api.Notification>
76 Corresponds to C<notification_t>, defined in F<src/plugin.h>.
78 =back
80 In the remainder of this document, we'll use the short form of these names, for
81 example B<ValueList>. In order to be able to use these abbreviated names, you
82 need to B<import> the classes.
84 =head1 EXPORTED API FUNCTIONS
86 All collectd API functions that are available to Java plugins are implemented
87 as I<publicE<nbsp>static> functions of the B<Collectd> class. This makes
88 calling these functions pretty straight forward. For example, to send an error
89 message to the daemon, you'd do something like this:
91   Collectd.logError ("That wasn't chicken!");
93 The following are the currently exported functions.
95 =head2 registerConfig
97 Signature: I<int> B<registerConfig> (I<String> name,
98 I<CollectdConfigInterface> object);
100 Registers the B<config> function of I<object> with the daemon.
102 Returns zero upon success and non-zero when an error occurred.
104 See L<"config callback"> below.
106 =head2 registerInit
108 Signature: I<int> B<registerInit> (I<String> name,
109 I<CollectdInitInterface> object);
111 Registers the B<init> function of I<object> with the daemon.
113 Returns zero upon success and non-zero when an error occurred.
115 See L<"init callback"> below.
117 =head2 registerRead
119 Signature: I<int> B<registerRead> (I<String> name,
120 I<CollectdReadInterface> object)
122 Registers the B<read> function of I<object> with the daemon.
124 Returns zero upon success and non-zero when an error occurred.
126 See L<"read callback"> below.
128 =head2 registerWrite
130 Signature: I<int> B<registerWrite> (I<String> name,
131 I<CollectdWriteInterface> object)
133 Registers the B<write> function of I<object> with the daemon.
135 Returns zero upon success and non-zero when an error occurred.
137 See L<"write callback"> below.
139 =head2 registerFlush
141 Signature: I<int> B<registerFlush> (I<String> name,
142 I<CollectdFlushInterface> object)
144 Registers the B<flush> function of I<object> with the daemon.
146 Returns zero upon success and non-zero when an error occurred.
148 See L<"flush callback"> below.
150 =head2 registerShutdown
152 Signature: I<int> B<registerShutdown> (I<String> name,
153 I<CollectdShutdownInterface> object);
155 Registers the B<shutdown> function of I<object> with the daemon.
157 Returns zero upon success and non-zero when an error occurred.
159 See L<"shutdown callback"> below.
161 =head2 registerLog
163 Signature: I<int> B<registerLog> (I<String> name,
164 I<CollectdLogInterface> object);
166 Registers the B<log> function of I<object> with the daemon.
168 Returns zero upon success and non-zero when an error occurred.
170 See L<"log callback"> below.
172 =head2 registerNotification
174 Signature: I<int> B<registerNotification> (I<String> name,
175 I<CollectdNotificationInterface> object);
177 Registers the B<notification> function of I<object> with the daemon.
179 Returns zero upon success and non-zero when an error occurred.
181 See L<"notification callback"> below.
183 =head2 registerMatch
185 Signature: I<int> B<registerMatch> (I<String> name,
186 I<CollectdMatchFactoryInterface> object);
188 Registers the B<createMatch> function of I<object> with the daemon.
190 Returns zero upon success and non-zero when an error occurred.
192 See L<"match callback"> below.
194 =head2 registerTarget
196 Signature: I<int> B<registerTarget> (I<String> name,
197 I<CollectdTargetFactoryInterface> object);
199 Registers the B<createTarget> function of I<object> with the daemon.
201 Returns zero upon success and non-zero when an error occurred.
203 See L<"target callback"> below.
205 =head2 dispatchValues
207 Signature: I<int> B<dispatchValues> (I<ValueList>)
209 Passes the values represented by the B<ValueList> object to the
210 C<plugin_dispatch_values> function of the daemon. The "data set" (or list of
211 "data sources") associated with the object are ignored, because
212 C<plugin_dispatch_values> will automatically lookup the required data set. It
213 is therefore absolutely okay to leave this blank.
215 Returns zero upon success or non-zero upon failure.
217 =head2 getDS
219 Signature: I<DataSet> B<getDS> (I<String>)
221 Returns the appropriate I<type> or B<null> if the type is not defined.
223 =head2 logError
225 Signature: I<void> B<logError> (I<String>)
227 Sends a log message with severity B<ERROR> to the daemon.
229 =head2 logWarning
231 Signature: I<void> B<logWarning> (I<String>)
233 Sends a log message with severity B<WARNING> to the daemon.
235 =head2 logNotice
237 Signature: I<void> B<logNotice> (I<String>)
239 Sends a log message with severity B<NOTICE> to the daemon.
241 =head2 logInfo
243 Signature: I<void> B<logInfo> (I<String>)
245 Sends a log message with severity B<INFO> to the daemon.
247 =head2 logDebug
249 Signature: I<void> B<logDebug> (I<String>)
251 Sends a log message with severity B<DEBUG> to the daemon.
253 =head1 REGISTERING CALLBACKS
255 When starting up, collectd creates an object of each configured class. The
256 constructor of this class should then register "callbacks" with the daemon,
257 using the appropriate static functions in B<Collectd>,
258 see L<"EXPORTED API FUNCTIONS"> above. To register a callback, the object being
259 passed to one of the register functions must implement an appropriate
260 interface, which are all in the B<org.collectd.api> namespace.
262 A constructor may register any number of these callbacks, even none. An object
263 without callback methods is never actively called by collectd, but may still
264 call the exported API functions. One could, for example, start a new thread in
265 the constructor and dispatch (submit to the daemon) values asynchronously,
266 whenever one is available.
268 Each callback method is now explained in more detail:
270 =head2 config callback
272 Interface: B<org.collectd.api.CollectdConfigInterface>
274 Signature: I<int> B<config> (I<OConfigItem> ci)
276 This method is passed a B<OConfigItem> object, if both, method and
277 configuration, are available. B<OConfigItem> is the root of a tree representing
278 the configuration for this plugin. The root itself is the representation of the
279 B<E<lt>PluginE<nbsp>/E<gt>> block, so in next to all cases the children of the
280 root are the first interesting objects.
282 To signal success, this method has to return zero. Anything else will be
283 considered an error condition and the plugin will be disabled entirely.
285 See L<"registerConfig"> above.
287 =head2 init callback
289 Interface: B<org.collectd.api.CollectdInitInterface>
291 Signature: I<int> B<init> ()
293 This method is called after the configuration has been handled. It is
294 supposed to set up the plugin. e.E<nbsp>g. start threads, open connections, or
295 check if can do anything useful at all.
297 To signal success, this method has to return zero. Anything else will be
298 considered an error condition and the plugin will be disabled entirely.
300 See L<"registerInit"> above.
302 =head2 read callback
304 Interface: B<org.collectd.api.CollectdReadInterface>
306 Signature: I<int> B<read> ()
308 This method is called periodically and is supposed to gather statistics in
309 whatever fashion. These statistics are represented as a B<ValueList> object and
310 sent to the daemon using L<dispatchValues|"dispatchValues">.
312 To signal success, this method has to return zero. Anything else will be
313 considered an error condition and cause an appropriate message to be logged.
314 Currently, returning non-zero does not have any other effects. In particular,
315 Java "read"-methods are not suspended for increasing intervals like C
316 "read"-functions.
318 See L<"registerRead"> above.
320 =head2 write callback
322 Interface: B<org.collectd.api.CollectdWriteInterface>
324 Signature: I<int> B<write> (I<ValueList> vl)
326 This method is called whenever a value is dispatched to the daemon. The
327 corresponding C "write"-functions are passed a C<data_set_t>, so they can
328 decide which values are absolute values (gauge) and which are counter values.
329 To get the corresponding C<ListE<lt>DataSourceE<gt>>, call the B<getDataSource>
330 method of the B<ValueList> object.
332 To signal success, this method has to return zero. Anything else will be
333 considered an error condition and cause an appropriate message to be logged.
335 See L<"registerWrite"> above.
337 =head2 flush callback
339 Interface: B<org.collectd.api.CollectdFlushInterface>
341 Signature: I<int> B<flush> (I<int> timeout, I<String> identifier)
343 This method is called when the daemon received a flush command. This can either
344 be done using the C<USR1> signal (see L<collectd(1)>) or using the I<unixsock>
345 plugin (see L<collectd-unixsock(5)>).
347 If I<timeout> is greater than zero, only values older than this number of
348 seconds should be flushed. To signal that all values should be flushed
349 regardless of age, this argument is set to a negative number.
351 The I<identifier> specifies which value should be flushed. If it is not
352 possible to flush one specific value, flush all values. To signal that all
353 values should be flushed, this argument is set to I<null>.
355 To signal success, this method has to return zero. Anything else will be
356 considered an error condition and cause an appropriate message to be logged.
358 See L<"registerFlush"> above.
360 =head2 shutdown callback
362 Interface: B<org.collectd.api.CollectdShutdownInterface>
364 Signature: I<int> B<shutdown> ()
366 This method is called when the daemon is shutting down. You should not rely on
367 the destructor to clean up behind the object but use this function instead.
369 To signal success, this method has to return zero. Anything else will be
370 considered an error condition and cause an appropriate message to be logged.
372 See L<"registerShutdown"> above.
374 =head2 log callback
376 Interface: B<org.collectd.api.CollectdLogInterface>
378 Signature: I<void> B<log> (I<int> severity, I<String> message)
380 This callback can be used to receive log messages from the daemon.
382 The argument I<severity> is one of:
384 =over 4
386 =item *
388 org.collectd.api.Collectd.LOG_ERR
390 =item *
392 org.collectd.api.Collectd.LOG_WARNING
394 =item *
396 org.collectd.api.Collectd.LOG_NOTICE
398 =item *
400 org.collectd.api.Collectd.LOG_INFO
402 =item *
404 org.collectd.api.Collectd.LOG_DEBUG
406 =back
408 The function does not return any value.
410 See L<"registerLog"> above.
412 =head2 notification callback
414 Interface: B<org.collectd.api.CollectdNotificationInterface>
416 Signature: I<int> B<notification> (I<Notification> n)
418 This callback can be used to receive notifications from the daemon.
420 To signal success, this method has to return zero. Anything else will be
421 considered an error condition and cause an appropriate message to be logged.
423 See L<"registerNotification"> above.
425 =head2 match callback
427 The match (and target, see L<"target callback"> below) callbacks work a bit
428 different from the other callbacks above: You don't register a match callback
429 with the daemon directly, but you register a function which, when called,
430 creates an appropriate object. The object creating the "match" objects is
431 called "match factory".
433 See L<"registerMatch"> above.
435 =head3 Factory object
437 Interface: B<org.collectd.api.CollectdMatchFactoryInterface>
439 Signature: I<CollectdMatchInterface> B<createMatch>
440 (I<OConfigItem> ci);
442 Called by the daemon to create "match" objects.
444 Returns: A new object which implements the B<CollectdMatchInterface> interface.
446 =head3 Match object
448 Interface: B<org.collectd.api.CollectdMatchInterface>
450 Signature: I<int> B<match> (I<DataSet> ds, I<ValueList> vl);
452 Called when processing a chain to determine whether or not a I<ValueList>
453 matches. How values are matches is up to the implementing class.
455 Has to return one of:
457 =over 4
459 =item *
461 B<Collectd.FC_MATCH_NO_MATCH>
463 =item *
465 B<Collectd.FC_MATCH_MATCHES>
467 =back
469 =head2 target callback
471 The target (and match, see L<"match callback"> above) callbacks work a bit
472 different from the other callbacks above: You don't register a target callback
473 with the daemon directly, but you register a function which, when called,
474 creates an appropriate object. The object creating the "target" objects is
475 called "target factory".
477 See L<"registerTarget"> above.
479 =head3 Factory object
481 Interface: B<org.collectd.api.CollectdTargetFactoryInterface>
483 Signature: I<CollectdTargetInterface> B<createTarget>
484 (I<OConfigItem> ci);
486 Called by the daemon to create "target" objects.
488 Returns: A new object which implements the B<CollectdTargetInterface>
489 interface.
491 =head3 Target object
493 Interface: B<org.collectd.api.CollectdTargetInterface>
495 Signature: I<int> B<invoke> (I<DataSet> ds, I<ValueList> vl);
497 Called when processing a chain to perform some action. The action performed is
498 up to the implementing class.
500 Has to return one of:
502 =over 4
504 =item *
506 B<Collectd.FC_TARGET_CONTINUE>
508 =item *
510 B<Collectd.FC_TARGET_STOP>
512 =item *
514 B<Collectd.FC_TARGET_RETURN>
516 =back
518 =head1 EXAMPLE
520 This short example demonstrates how to register a read callback with the
521 daemon:
523   import org.collectd.api.Collectd;
524   import org.collectd.api.ValueList;
525   
526   import org.collectd.api.CollectdReadInterface;
527   
528   public class Foobar implements CollectdReadInterface
529   {
530     public Foobar ()
531     {
532       Collectd.registerRead ("Foobar", this);
533     }
534     
535     public int read ()
536     {
537       ValueList vl;
538       
539       /* Do something... */
540       
541       Collectd.dispatchValues (vl);
542     }
543   }
545 =head1 PLUGINS
547 The following plugins are implemented in I<Java>. Both, the B<LoadPlugin>
548 option and the B<Plugin> block must be inside the
549 B<E<lt>PluginE<nbsp>javaE<gt>> block (see above).
551 =head2 GenericJMX plugin
553 The GenericJMX plugin reads I<Managed Beans> (MBeans) from an I<MBeanServer>
554 using JMX. JMX is a generic framework to provide and query various management
555 information. The interface is used by Java processes to provide internal
556 statistics as well as by the I<Java Virtual Machine> (JVM) to provide
557 information about the memory used, threads and so on. 
559 The configuration of the I<GenericJMX plugin> consists of two blocks: I<MBean>
560 blocks that define a mapping of MBean attributes to the “types” used by
561 I<collectd>, and I<Connection> blocks which define the parameters needed to
562 connect to an I<MBeanServer> and what data to collect. The configuration of the
563 I<SNMP plugin> is similar in nature, in case you know it.
565 =head3   MBean blocks
567 I<MBean> blocks specify what data is retrieved from I<MBeans> and how that data
568 is mapped on the I<collectd> data types. The block requires one string
569 argument, a name. This name is used in the I<Connection> blocks (see below) to
570 refer to a specific I<MBean> block. Therefore, the names must be unique.
572 The following options are recognized within I<MBean> blocks: 
574 =over 4
576 =item B<ObjectName> I<pattern>
578 Sets the pattern which is used to retrieve I<MBeans> from the I<MBeanServer>.
579 If more than one MBean is returned you should use the B<InstanceFrom> option
580 (see below) to make the identifiers unique.
582 See also:
583 L<http://java.sun.com/javase/6/docs/api/javax/management/ObjectName.html>
585 =item B<InstancePrefix> I<prefix>
587 Prefixes the generated I<plugin instance> with I<prefix>. I<(optional)>
589 =item B<InstanceFrom> I<property>
591 The I<object names> used by JMX to identify I<MBeans> include so called
592 I<“properties”> which are basically key-value-pairs. If the given object name
593 is not unique and multiple MBeans are returned, the values of those properties
594 usually differ. You can use this option to build the I<plugin instance> from
595 the appropriate property values. This option is optional and may be repeated to
596 generate the I<plugin instance> from multiple property values. 
598 =item B<E<lt>value /E<gt>> blocks
600 The I<value> blocks map one or more attributes of an I<MBean> to a value list
601 in I<collectd>. There must be at least one Value block within each I<MBean>
602 block.
604 =over 4
606 =item B<Type> type
608 Sets the data set used within I<collectd> to handle the values of the I<MBean>
609 attribute.
611 =item B<InstancePrefix> I<prefix>
613 Works like the option of the same name directly beneath the I<MBean> block, but
614 sets the type instance instead. I<(optional)>
616 =item B<InstanceFrom> I<prefix>
618 Works like the option of the same name directly beneath the I<MBean> block, but
619 sets the type instance instead. I<(optional)>
621 =item B<Table> B<true>|B<false>
623 Set this to true if the returned attribute is a I<composite type>. If set to
624 true, the keys within the I<composite type> is appended to the
625 I<type instance>.
627 =item B<Attribute> I<path>
629 Sets the name of the attribute from which to read the value. You can access the
630 keys of composite types by using a dot to concatenate the key name to the
631 attribute name. For example: “attrib0.key42”. If B<Table> is set to B<true>
632 I<path> must point to a I<composite type>, otherwise it must point to a numeric
633 type. 
635 =back
637 =back
639 =head3 Connection blocks
641 Connection blocks specify I<how> to connect to an I<MBeanServer> and what data
642 to retrieve. The following configuration options are available:
644 =over 4
646 =item B<Host> I<name>
648 Host name used when dispatching the values to I<collectd>. The option sets this
649 field only, it is I<not> used to connect to anything and doesn't need to be a
650 real, resolvable name.
652 =item B<ServiceURL> I<URL>
654 Specifies how the I<MBeanServer> can be reached. Any string accepted by the
655 I<JMXServiceURL> is valid.
657 See also:
658 L<http://java.sun.com/javase/6/docs/api/javax/management/remote/JMXServiceURL.html>
660 =item B<User> I<name>
662 Use I<name> to authenticate to the server. If not configured, “monitorRole”
663 will be used.
665 =item B<Password> I<password>
667 Use I<password> to authenticate to the server. If not given, unauthenticated
668 access is used.
670 =item B<Collect> I<mbean_block_name>
672 Configures which of the I<MBean> blocks to use with this connection. May be
673 repeated to collect multiple I<MBeans> from this server. 
675 =back
677 =head1 SEE ALSO
679 L<collectd(1)>,
680 L<collectd.conf(5)>,
681 L<collectd-perl(5)>,
682 L<types.db(5)>
684 =head1 AUTHOR
686 Florian Forster E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt>