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<Table> B<true>|B<false>
 624
 625 Set this to true if the returned attribute is a I<composite type>. If set to
 626 true, the keys within the I<composite type> is appended to the
 627 I<type instance>.
 628
 629 =item B<Attribute> I<path>
 630
 631 Sets the name of the attribute from which to read the value. You can access the
 632 keys of composite types by using a dot to concatenate the key name to the
 633 attribute name. For example: “attrib0.key42”. If B<Table> is set to B<true>
 634 I<path> must point to a I<composite type>, otherwise it must point to a numeric
 635 type.
 636
 637 =back
 638
 639 =back
 640
 641 =head3 Connection blocks
 642
 643 Connection blocks specify I<how> to connect to an I<MBeanServer> and what data
 644 to retrieve. The following configuration options are available:
 645
 646 =over 4
 647
 648 =item B<Host> I<name>
 649
 650 Host name used when dispatching the values to I<collectd>. The option sets this
 651 field only, it is I<not> used to connect to anything and doesn't need to be a
 652 real, resolvable name.
 653
 654 =item B<ServiceURL> I<URL>
 655
 656 Specifies how the I<MBeanServer> can be reached. Any string accepted by the
 657 I<JMXServiceURL> is valid.
 658
 659 See also:
 660 L<http://java.sun.com/javase/6/docs/api/javax/management/remote/JMXServiceURL.html>
 661
 662 =item B<User> I<name>
 663
 664 Use I<name> to authenticate to the server. If not configured, “monitorRole”
 665 will be used.
 666
 667 =item B<Password> I<password>
 668
 669 Use I<password> to authenticate to the server. If not given, unauthenticated
 670 access is used.
 671
 672 =item B<InstancePrefix> I<prefix>
 673
 674 Prefixes the generated I<plugin instance> with I<prefix>. If a second
 675 I<InstancePrefix> is specified in a referenced I<MBean> block, the prefix
 676 specified in the I<Connection> block will appear at the beginning of the
 677 I<plugin instance>, the prefix specified in the I<MBean> block will be appended
 678 to it.
 679
 680 =item B<Collect> I<mbean_block_name>
 681
 682 Configures which of the I<MBean> blocks to use with this connection. May be
 683 repeated to collect multiple I<MBeans> from this server.
 684
 685 =back
 686
 687 =head1 SEE ALSO
 688
 689 L<collectd(1)>,
 690 L<collectd.conf(5)>,
 691 L<collectd-perl(5)>,
 692 L<types.db(5)>
 693
 694 =head1 AUTHOR
 695
 696 Florian Forster E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt>
 697