src/collectd-java.pod

   1 =head1 NAME
   2
   3 collectd-java - Documentation of collectd's "java plugin"
   4
   5 =head1 SYNOPSIS
   6
   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>
  17
  18 =head1 DESCRIPTION
  19
  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.
  23
  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.
  26
  27 =head1 CONFIGURATION
  28
  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>>.
  32
  33 =head1 OVERVIEW
  34
  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.
  39
  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.
  44
  45 The available classes are:
  46
  47 =over 4
  48
  49 =item B<org.collectd.api.Collectd>
  50
  51 All API functions exported to Java are implemented as static functions of this
  52 class. See L<"EXPORTED API FUNCTIONS"> below.
  53
  54 =item B<org.collectd.api.OConfigValue>
  55
  56 Corresponds to C<oconfig_value_t>, defined in F<src/liboconfig/oconfig.h>.
  57
  58 =item B<org.collectd.api.OConfigItem>
  59
  60 Corresponds to C<oconfig_item_t>, defined in F<src/liboconfig/oconfig.h>.
  61
  62 =item B<org.collectd.api.DataSource>
  63
  64 Corresponds to C<data_source_t>, defined in F<src/plugin.h>.
  65
  66 =item B<org.collectd.api.DataSet>
  67
  68 Corresponds to C<data_set_t>, defined in F<src/plugin.h>.
  69
  70 =item B<org.collectd.api.ValueList>
  71
  72 Corresponds to C<value_list_t>, defined in F<src/plugin.h>.
  73
  74 =item B<org.collectd.api.Notification>
  75
  76 Corresponds to C<notification_t>, defined in F<src/plugin.h>.
  77
  78 =back
  79
  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.
  83
  84 =head1 EXPORTED API FUNCTIONS
  85
  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:
  90
  91   Collectd.logError ("That wasn't chicken!");
  92
  93 The following are the currently exported functions.
  94
  95 =head2 registerConfig
  96
  97 Signature: I<int> B<registerConfig> (I<String> name,
  98 I<CollectdConfigInterface> object);
  99
 100 Registers the B<config> function of I<object> with the daemon.
 101
 102 Returns zero upon success and non-zero when an error occurred.
 103
 104 See L<"config callback"> below.
 105
 106 =head2 registerInit
 107
 108 Signature: I<int> B<registerInit> (I<String> name,
 109 I<CollectdInitInterface> object);
 110
 111 Registers the B<init> function of I<object> with the daemon.
 112
 113 Returns zero upon success and non-zero when an error occurred.
 114
 115 See L<"init callback"> below.
 116
 117 =head2 registerRead
 118
 119 Signature: I<int> B<registerRead> (I<String> name,
 120 I<CollectdReadInterface> object)
 121
 122 Registers the B<read> function of I<object> with the daemon.
 123
 124 Returns zero upon success and non-zero when an error occurred.
 125
 126 See L<"read callback"> below.
 127
 128 =head2 registerWrite
 129
 130 Signature: I<int> B<registerWrite> (I<String> name,
 131 I<CollectdWriteInterface> object)
 132
 133 Registers the B<write> function of I<object> with the daemon.
 134
 135 Returns zero upon success and non-zero when an error occurred.
 136
 137 See L<"write callback"> below.
 138
 139 =head2 registerFlush
 140
 141 Signature: I<int> B<registerFlush> (I<String> name,
 142 I<CollectdFlushInterface> object)
 143
 144 Registers the B<flush> function of I<object> with the daemon.
 145
 146 Returns zero upon success and non-zero when an error occurred.
 147
 148 See L<"flush callback"> below.
 149
 150 =head2 registerShutdown
 151
 152 Signature: I<int> B<registerShutdown> (I<String> name,
 153 I<CollectdShutdownInterface> object);
 154
 155 Registers the B<shutdown> function of I<object> with the daemon.
 156
 157 Returns zero upon success and non-zero when an error occurred.
 158
 159 See L<"shutdown callback"> below.
 160
 161 =head2 registerLog
 162
 163 Signature: I<int> B<registerLog> (I<String> name,
 164 I<CollectdLogInterface> object);
 165
 166 Registers the B<log> function of I<object> with the daemon.
 167
 168 Returns zero upon success and non-zero when an error occurred.
 169
 170 See L<"log callback"> below.
 171
 172 =head2 registerNotification
 173
 174 Signature: I<int> B<registerNotification> (I<String> name,
 175 I<CollectdNotificationInterface> object);
 176
 177 Registers the B<notification> function of I<object> with the daemon.
 178
 179 Returns zero upon success and non-zero when an error occurred.
 180
 181 See L<"notification callback"> below.
 182
 183 =head2 registerMatch
 184
 185 Signature: I<int> B<registerMatch> (I<String> name,
 186 I<CollectdMatchFactoryInterface> object);
 187
 188 Registers the B<createMatch> function of I<object> with the daemon.
 189
 190 Returns zero upon success and non-zero when an error occurred.
 191
 192 See L<"match callback"> below.
 193
 194 =head2 registerTarget
 195
 196 Signature: I<int> B<registerTarget> (I<String> name,
 197 I<CollectdTargetFactoryInterface> object);
 198
 199 Registers the B<createTarget> function of I<object> with the daemon.
 200
 201 Returns zero upon success and non-zero when an error occurred.
 202
 203 See L<"target callback"> below.
 204
 205 =head2 dispatchValues
 206
 207 Signature: I<int> B<dispatchValues> (I<ValueList>)
 208
 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.
 214
 215 Returns zero upon success or non-zero upon failure.
 216
 217 =head2 getDS
 218
 219 Signature: I<DataSet> B<getDS> (I<String>)
 220
 221 Returns the appropriate I<type> or B<null> if the type is not defined.
 222
 223 =head2 logError
 224
 225 Signature: I<void> B<logError> (I<String>)
 226
 227 Sends a log message with severity B<ERROR> to the daemon.
 228
 229 =head2 logWarning
 230
 231 Signature: I<void> B<logWarning> (I<String>)
 232
 233 Sends a log message with severity B<WARNING> to the daemon.
 234
 235 =head2 logNotice
 236
 237 Signature: I<void> B<logNotice> (I<String>)
 238
 239 Sends a log message with severity B<NOTICE> to the daemon.
 240
 241 =head2 logInfo
 242
 243 Signature: I<void> B<logInfo> (I<String>)
 244
 245 Sends a log message with severity B<INFO> to the daemon.
 246
 247 =head2 logDebug
 248
 249 Signature: I<void> B<logDebug> (I<String>)
 250
 251 Sends a log message with severity B<DEBUG> to the daemon.
 252
 253 =head1 REGISTERING CALLBACKS
 254
 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.
 261
 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.
 267
 268 Each callback method is now explained in more detail:
 269
 270 =head2 config callback
 271
 272 Interface: B<org.collectd.api.CollectdConfigInterface>
 273
 274 Signature: I<int> B<config> (I<OConfigItem> ci)
 275
 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.
 281
 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.
 284
 285 See L<"registerConfig"> above.
 286
 287 =head2 init callback
 288
 289 Interface: B<org.collectd.api.CollectdInitInterface>
 290
 291 Signature: I<int> B<init> ()
 292
 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.
 296
 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.
 299
 300 See L<"registerInit"> above.
 301
 302 =head2 read callback
 303
 304 Interface: B<org.collectd.api.CollectdReadInterface>
 305
 306 Signature: I<int> B<read> ()
 307
 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">.
 311
 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.
 317
 318 See L<"registerRead"> above.
 319
 320 =head2 write callback
 321
 322 Interface: B<org.collectd.api.CollectdWriteInterface>
 323
 324 Signature: I<int> B<write> (I<ValueList> vl)
 325
 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.
 331
 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.
 334
 335 See L<"registerWrite"> above.
 336
 337 =head2 flush callback
 338
 339 Interface: B<org.collectd.api.CollectdFlushInterface>
 340
 341 Signature: I<int> B<flush> (I<int> timeout, I<String> identifier)
 342
 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)>).
 346
 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.
 350
 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>.
 354
 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.
 357
 358 See L<"registerFlush"> above.
 359
 360 =head2 shutdown callback
 361
 362 Interface: B<org.collectd.api.CollectdShutdownInterface>
 363
 364 Signature: I<int> B<shutdown> ()
 365
 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.
 368
 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.
 371
 372 See L<"registerShutdown"> above.
 373
 374 =head2 log callback
 375
 376 Interface: B<org.collectd.api.CollectdLogInterface>
 377
 378 Signature: I<void> B<log> (I<int> severity, I<String> message)
 379
 380 This callback can be used to receive log messages from the daemon.
 381
 382 The argument I<severity> is one of:
 383
 384 =over 4
 385
 386 =item *
 387
 388 org.collectd.api.Collectd.LOG_ERR
 389
 390 =item *
 391
 392 org.collectd.api.Collectd.LOG_WARNING
 393
 394 =item *
 395
 396 org.collectd.api.Collectd.LOG_NOTICE
 397
 398 =item *
 399
 400 org.collectd.api.Collectd.LOG_INFO
 401
 402 =item *
 403
 404 org.collectd.api.Collectd.LOG_DEBUG
 405
 406 =back
 407
 408 The function does not return any value.
 409
 410 See L<"registerLog"> above.
 411
 412 =head2 notification callback
 413
 414 Interface: B<org.collectd.api.CollectdNotificationInterface>
 415
 416 Signature: I<int> B<notification> (I<Notification> n)
 417
 418 This callback can be used to receive notifications from the daemon.
 419
 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.
 422
 423 See L<"registerNotification"> above.
 424
 425 =head2 match callback
 426
 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".
 432
 433 See L<"registerMatch"> above.
 434
 435 =head3 Factory object
 436
 437 Interface: B<org.collectd.api.CollectdMatchFactoryInterface>
 438
 439 Signature: I<CollectdMatchInterface> B<createMatch>
 440 (I<OConfigItem> ci);
 441
 442 Called by the daemon to create "match" objects.
 443
 444 Returns: A new object which implements the B<CollectdMatchInterface> interface.
 445
 446 =head3 Match object
 447
 448 Interface: B<org.collectd.api.CollectdMatchInterface>
 449
 450 Signature: I<int> B<match> (I<DataSet> ds, I<ValueList> vl);
 451
 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.
 454
 455 Has to return one of:
 456
 457 =over 4
 458
 459 =item *
 460
 461 B<Collectd.FC_MATCH_NO_MATCH>
 462
 463 =item *
 464
 465 B<Collectd.FC_MATCH_MATCHES>
 466
 467 =back
 468
 469 =head2 target callback
 470
 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".
 476
 477 See L<"registerTarget"> above.
 478
 479 =head3 Factory object
 480
 481 Interface: B<org.collectd.api.CollectdTargetFactoryInterface>
 482
 483 Signature: I<CollectdTargetInterface> B<createTarget>
 484 (I<OConfigItem> ci);
 485
 486 Called by the daemon to create "target" objects.
 487
 488 Returns: A new object which implements the B<CollectdTargetInterface>
 489 interface.
 490
 491 =head3 Target object
 492
 493 Interface: B<org.collectd.api.CollectdTargetInterface>
 494
 495 Signature: I<int> B<invoke> (I<DataSet> ds, I<ValueList> vl);
 496
 497 Called when processing a chain to perform some action. The action performed is
 498 up to the implementing class.
 499
 500 Has to return one of:
 501
 502 =over 4
 503
 504 =item *
 505
 506 B<Collectd.FC_TARGET_CONTINUE>
 507
 508 =item *
 509
 510 B<Collectd.FC_TARGET_STOP>
 511
 512 =item *
 513
 514 B<Collectd.FC_TARGET_RETURN>
 515
 516 =back
 517
 518 =head1 EXAMPLE
 519
 520 This short example demonstrates how to register a read callback with the
 521 daemon:
 522
 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   }
 544
 545 =head1 PLUGINS
 546
 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).
 550
 551 =head2 GenericJMX plugin
 552
 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.
 558
 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.
 564
 565 =head3   MBean blocks
 566
 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.
 571
 572 The following options are recognized within I<MBean> blocks:
 573
 574 =over 4
 575
 576 =item B<ObjectName> I<pattern>
 577
 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.
 581
 582 See also:
 583 L<http://java.sun.com/javase/6/docs/api/javax/management/ObjectName.html>
 584
 585 =item B<InstancePrefix> I<prefix>
 586
 587 Prefixes the generated I<plugin instance> with I<prefix>. I<(optional)>
 588
 589 =item B<InstanceFrom> I<property>
 590
 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.
 597
 598 =item B<E<lt>value /E<gt>> blocks
 599
 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.
 603
 604 =over 4
 605
 606 =item B<Type> type
 607
 608 Sets the data set used within I<collectd> to handle the values of the I<MBean>
 609 attribute.
 610
 611 =item B<InstancePrefix> I<prefix>
 612
 613 Works like the option of the same name directly beneath the I<MBean> block, but
 614 sets the type instance instead. I<(optional)>
 615
 616 =item B<InstanceFrom> I<prefix>
 617
 618 Works like the option of the same name directly beneath the I<MBean> block, but
 619 sets the type instance instead. I<(optional)>
 620
 621 =item B<Table> B<true>|B<false>
 622
 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>.
 626
 627 =item B<Attribute> I<path>
 628
 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.
 634
 635 =back
 636
 637 =back
 638
 639 =head3 Connection blocks
 640
 641 Connection blocks specify I<how> to connect to an I<MBeanServer> and what data
 642 to retrieve. The following configuration options are available:
 643
 644 =over 4
 645
 646 =item B<Host> I<name>
 647
 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.
 651
 652 =item B<ServiceURL> I<URL>
 653
 654 Specifies how the I<MBeanServer> can be reached. Any string accepted by the
 655 I<JMXServiceURL> is valid.
 656
 657 See also:
 658 L<http://java.sun.com/javase/6/docs/api/javax/management/remote/JMXServiceURL.html>
 659
 660 =item B<User> I<name>
 661
 662 Use I<name> to authenticate to the server. If not configured, “monitorRole”
 663 will be used.
 664
 665 =item B<Password> I<password>
 666
 667 Use I<password> to authenticate to the server. If not given, unauthenticated
 668 access is used.
 669
 670 =item B<InstancePrefix> I<prefix>
 671
 672 Prefixes the generated I<plugin instance> with I<prefix>. If a second
 673 I<InstancePrefix> is specified in a referenced I<MBean> block, the prefix
 674 specified in the I<Connection> block will appear at the beginning of the
 675 I<plugin instance>, the prefix specified in the I<MBean> block will be appended
 676 to it.
 677
 678 =item B<Collect> I<mbean_block_name>
 679
 680 Configures which of the I<MBean> blocks to use with this connection. May be
 681 repeated to collect multiple I<MBeans> from this server.
 682
 683 =back
 684
 685 =head1 SEE ALSO
 686
 687 L<collectd(1)>,
 688 L<collectd.conf(5)>,
 689 L<collectd-perl(5)>,
 690 L<types.db(5)>
 691
 692 =head1 AUTHOR
 693
 694 Florian Forster E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt>
 695