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 available classes are:
  41
  42 =over 4
  43
  44 =item B<org.collectd.api.OConfigValue>
  45
  46 Corresponds to C<oconfig_value_t>, defined in F<src/liboconfig/oconfig.h>.
  47
  48 =item B<org.collectd.api.OConfigItem>
  49
  50 Corresponds to C<oconfig_item_t>, defined in F<src/liboconfig/oconfig.h>.
  51
  52 =item B<org.collectd.api.DataSource>
  53
  54 Corresponds to C<data_source_t>, defined in F<src/plugin.h>.
  55
  56 =item B<org.collectd.api.DataSet>
  57
  58 Corresponds to C<data_set_t>, defined in F<src/plugin.h>.
  59
  60 =item B<org.collectd.api.ValueList>
  61
  62 Corresponds to C<value_list_t>, defined in F<src/plugin.h>.
  63
  64 =item B<org.collectd.api.Notification>
  65
  66 Corresponds to C<notification_t>, defined in F<src/plugin.h>.
  67
  68 =back
  69
  70 In the remainder of this document, we'll use the short form of these names, for
  71 example B<ValueList>. In order to be able to use these abbreviated names, you
  72 need to B<import> the classes.
  73
  74 The API functions that are available from Java are implemented as I<static>
  75 functions of the B<org.collectd.api.Collectd> class.
  76 See L<"CALLING API FUNCTIONS"> below for details.
  77
  78 =head1 REGISTERING CALLBACKS
  79
  80 When starting up, collectd creates an object of each configured class. The
  81 constructor of this class should then register "callbacks" with the daemon,
  82 using the appropriate static functions in B<Collectd>,
  83 see L<"CALLING API FUNCTIONS"> below. To register a callback, the object being
  84 passed to one of the register functions must implement an appropriate
  85 interface, which are all in the B<org.collectd.api> namespace.
  86
  87 A constructor may register any number of these callbacks, even none. An object
  88 without callback methods is never actively called by collectd, but may still
  89 call the exported API functions. One could, for example, start a new thread in
  90 the constructor and dispatch (submit to the daemon) values asynchronously,
  91 whenever one is available.
  92
  93 Each callback method is now explained in more detail:
  94
  95 =head2 config callback
  96
  97 Interface: B<org.collectd.api.CollectdConfigInterface>
  98
  99 Signature: I<int> B<config> (I<OConfigItem> ci)
 100
 101 This method is passed a B<OConfigItem> object, if both, method and
 102 configuration, are available. B<OConfigItem> is the root of a tree representing
 103 the configuration for this plugin. The root itself is the representation of the
 104 B<E<lt>PluginE<nbsp>/E<gt>> block, so in next to all cases the children of the
 105 root are the first interesting objects.
 106
 107 To signal success, this method has to return zero. Anything else will be
 108 considered an error condition and the plugin will be disabled entirely.
 109
 110 =head2 init callback
 111
 112 Interface: B<org.collectd.api.CollectdInitInterface>
 113
 114 Signature: I<int> B<init> ()
 115
 116 This method is called after the configuration has been handled. It is
 117 supposed to set up the plugin. e.E<nbsp>g. start threads, open connections, or
 118 check if can do anything useful at all.
 119
 120 To signal success, this method has to return zero. Anything else will be
 121 considered an error condition and the plugin will be disabled entirely.
 122
 123 =head2 read callback
 124
 125 Interface: B<org.collectd.api.CollectdReadInterface>
 126
 127 Signature: I<int> B<read> ()
 128
 129 This method is called periodically and is supposed to gather statistics in
 130 whatever fashion. These statistics are represented as a B<ValueList> object and
 131 sent to the daemon using B<dispatchValues>, see L<"CALLING API FUNCTIONS">
 132 below.
 133
 134 To signal success, this method has to return zero. Anything else will be
 135 considered an error condition and cause an appropriate message to be logged.
 136 Currently, returning non-zero does not have any other effects. In particular,
 137 Java "read"-methods are not suspended for increasing intervals like C
 138 "read"-functions.
 139
 140 =head2 write callback
 141
 142 Interface: B<org.collectd.api.CollectdWriteInterface>
 143
 144 Signature: I<int> B<write> (I<ValueList> vl)
 145
 146 This method is called whenever a value is dispatched to the daemon. The
 147 corresponding C "write"-functions are passed a C<data_set_t>, so they can
 148 decide which values are absolute values (gauge) and which are counter values.
 149 To get the corresponding C<ListE<lt>DataSourceE<gt>>, call the B<getDataSource>
 150 method of the B<ValueList> object.
 151
 152 To signal success, this method has to return zero. Anything else will be
 153 considered an error condition and cause an appropriate message to be logged.
 154
 155 =head2 flush callback
 156
 157 Interface: B<org.collectd.api.CollectdFlushInterface>
 158
 159 Signature: I<int> B<flush> (I<int> timeout, I<String> identifier)
 160
 161 This method is called when the daemon received a flush command. This can either
 162 be done using the C<USR1> signal (see L<collectd(1)>) or using the I<unixsock>
 163 plugin (see L<collectd-unixsock(5)>).
 164
 165 If I<timeout> is greater than zero, only values older than this number of
 166 seconds should be flushed. To signal that all values should be flushed
 167 regardless of age, this argument is set to a negative number.
 168
 169 The I<identifier> specifies which value should be flushed. If it is not
 170 possible to flush one specific value, flush all values. To signal that all
 171 values should be flushed, this argument is set to I<null>.
 172
 173 To signal success, this method has to return zero. Anything else will be
 174 considered an error condition and cause an appropriate message to be logged.
 175
 176 =head2 shutdown callback
 177
 178 Interface: B<org.collectd.api.CollectdShutdownInterface>
 179
 180 Signature: I<int> B<shutdown> ()
 181
 182 This method is called when the daemon is shutting down. You should not rely on
 183 the destructor to clean up behind the object but use this function instead.
 184
 185 To signal success, this method has to return zero. Anything else will be
 186 considered an error condition and cause an appropriate message to be logged.
 187
 188 =head2 log callback
 189
 190 Interface: B<org.collectd.api.CollectdLogInterface>
 191
 192 Signature: I<void> B<log> (I<int> severity, I<String> message)
 193
 194 This callback can be used to receive log messages from the daemon.
 195
 196 The argument I<severity> is one of:
 197
 198 =over 4
 199
 200 =item *
 201
 202 org.collectd.api.Collectd.LOG_ERR
 203
 204 =item *
 205
 206 org.collectd.api.Collectd.LOG_WARNING
 207
 208 =item *
 209
 210 org.collectd.api.Collectd.LOG_NOTICE
 211
 212 =item *
 213
 214 org.collectd.api.Collectd.LOG_INFO
 215
 216 =item *
 217
 218 org.collectd.api.Collectd.LOG_DEBUG
 219
 220 =back
 221
 222 The function does not return any value.
 223
 224 =head2 notification callback
 225
 226 Interface: B<org.collectd.api.CollectdNotificationInterface>
 227
 228 Signature: I<int> B<notification> (I<Notification> n)
 229
 230 This callback can be used to receive notifications from the daemon.
 231
 232 To signal success, this method has to return zero. Anything else will be
 233 considered an error condition and cause an appropriate message to be logged.
 234
 235 =head2 match callback
 236
 237 The match (and target, see L<"target callback"> below) callbacks work a bit
 238 different from the other callbacks above: You don't register a match callback
 239 with the daemon directly, but you register a function which, when called,
 240 creates an appropriate object. The object creating the "match" objects is
 241 called "match factory".
 242
 243 =head3 Factory object
 244
 245 Interface: B<org.collectd.api.CollectdMatchFactoryInterface>
 246
 247 Signature: I<CollectdMatchInterface> B<createMatch>
 248 (I<OConfigItem> ci);
 249
 250 Called by the daemon to create "match" objects.
 251
 252 Returns: A new object which implements the B<CollectdMatchInterface> interface.
 253
 254 =head3 Match object
 255
 256 Interface: B<org.collectd.api.CollectdMatchInterface>
 257
 258 Signature: I<int> B<match> (I<DataSet> ds, I<ValueList> vl);
 259
 260 Called when processing a chain to determine whether or not a I<ValueList>
 261 matches. How values are matches is up to the implementing class.
 262
 263 Has to return one of:
 264
 265 =over 4
 266
 267 =item *
 268
 269 B<Collectd.FC_MATCH_NO_MATCH>
 270
 271 =item *
 272
 273 B<Collectd.FC_MATCH_MATCHES>
 274
 275 =back
 276
 277 =head2 target callback
 278
 279 The target (and match, see L<"match callback"> above) callbacks work a bit
 280 different from the other callbacks above: You don't register a target callback
 281 with the daemon directly, but you register a function which, when called,
 282 creates an appropriate object. The object creating the "target" objects is
 283 called "target factory".
 284
 285 =head3 Factory object
 286
 287 Interface: B<org.collectd.api.CollectdTargetFactoryInterface>
 288
 289 Signature: I<CollectdTargetInterface> B<createTarget>
 290 (I<OConfigItem> ci);
 291
 292 Called by the daemon to create "target" objects.
 293
 294 Returns: A new object which implements the B<CollectdTargetInterface>
 295 interface.
 296
 297 =head3 Target object
 298
 299 Interface: B<org.collectd.api.CollectdTargetInterface>
 300
 301 Signature: I<int> B<invoke> (I<DataSet> ds, I<ValueList> vl);
 302
 303 Called when processing a chain to perform some action. The action performed is
 304 up to the implementing class.
 305
 306 Has to return one of:
 307
 308 =over 4
 309
 310 =item *
 311
 312 B<Collectd.FC_TARGET_CONTINUE>
 313
 314 =item *
 315
 316 B<Collectd.FC_TARGET_STOP>
 317
 318 =item *
 319
 320 B<Collectd.FC_TARGET_RETURN>
 321
 322 =back
 323
 324 =head2 Example
 325
 326 This short example demonstrates how to register a read callback with the
 327 daemon:
 328
 329   import org.collectd.api.Collectd;
 330   import org.collectd.api.ValueList;
 331
 332   import org.collectd.api.CollectdReadInterface;
 333
 334   public class Foobar implements CollectdReadInterface
 335   {
 336     public Foobar ()
 337     {
 338       Collectd.registerRead ("Foobar", this);
 339     }
 340
 341     public int read ()
 342     {
 343       ValueList vl;
 344
 345       /* Do something... */
 346
 347       Collectd.dispatchValues (vl);
 348     }
 349   }
 350
 351 =head1 CALLING API FUNCTIONS
 352
 353 All collectd API functions that are available to Java plugins are implemented
 354 as I<publicE<nbsp>static> functions of the B<org.collectd.api.Collectd> class.
 355 This makes calling these functions pretty straight forward.
 356
 357 The following are the currently exported functions. For information on the
 358 interfaces used, please see L<"REGISTERING CALLBACKS"> above.
 359
 360 =head2 registerConfig
 361
 362 Signature: I<int> B<registerConfig> (I<String> name,
 363 I<CollectdConfigInterface> object);
 364
 365 Registers the B<config> function of I<object> with the daemon.
 366
 367 Returns zero upon success and non-zero when an error occurred.
 368
 369 =head2 registerInit
 370
 371 Signature: I<int> B<registerInit> (I<String> name,
 372 I<CollectdInitInterface> object);
 373
 374 Registers the B<init> function of I<object> with the daemon.
 375
 376 Returns zero upon success and non-zero when an error occurred.
 377
 378 =head2 registerRead
 379
 380 Signature: I<int> B<registerRead> (I<String> name,
 381 I<CollectdReadInterface> object)
 382
 383 Registers the B<read> function of I<object> with the daemon.
 384
 385 Returns zero upon success and non-zero when an error occurred.
 386
 387 =head2 registerWrite
 388
 389 Signature: I<int> B<registerWrite> (I<String> name,
 390 I<CollectdWriteInterface> object)
 391
 392 Registers the B<write> function of I<object> with the daemon.
 393
 394 Returns zero upon success and non-zero when an error occurred.
 395
 396 =head2 registerFlush
 397
 398 Signature: I<int> B<registerFlush> (I<String> name,
 399 I<CollectdFlushInterface> object)
 400
 401 Registers the B<flush> function of I<object> with the daemon.
 402
 403 Returns zero upon success and non-zero when an error occurred.
 404
 405 =head2 registerShutdown
 406
 407 Signature: I<int> B<registerShutdown> (I<String> name,
 408 I<CollectdShutdownInterface> object);
 409
 410 Registers the B<shutdown> function of I<object> with the daemon.
 411
 412 Returns zero upon success and non-zero when an error occurred.
 413
 414 =head2 registerLog
 415
 416 Signature: I<int> B<registerLog> (I<String> name,
 417 I<CollectdLogInterface> object);
 418
 419 Registers the B<log> function of I<object> with the daemon.
 420
 421 Returns zero upon success and non-zero when an error occurred.
 422
 423 =head2 registerNotification
 424
 425 Signature: I<int> B<registerNotification> (I<String> name,
 426 I<CollectdNotificationInterface> object);
 427
 428 Registers the B<notification> function of I<object> with the daemon.
 429
 430 Returns zero upon success and non-zero when an error occurred.
 431
 432 =head2 registerMatch
 433
 434 Signature: I<int> B<registerMatch> (I<String> name,
 435 I<CollectdMatchFactoryInterface> object);
 436
 437 Registers the B<createMatch> function of I<object> with the daemon.
 438
 439 Returns zero upon success and non-zero when an error occurred.
 440
 441 See L<"match callback"> above.
 442
 443 =head2 registerTarget
 444
 445 Signature: I<int> B<registerTarget> (I<String> name,
 446 I<CollectdTargetFactoryInterface> object);
 447
 448 Registers the B<createTarget> function of I<object> with the daemon.
 449
 450 Returns zero upon success and non-zero when an error occurred.
 451
 452 See L<"target callback"> above.
 453
 454 =head2 dispatchValues
 455
 456 Signature: I<int> B<dispatchValues> (I<ValueList>)
 457
 458 Passes the values represented by the B<ValueList> object to the
 459 C<plugin_dispatch_values> function of the daemon. The "data set" (or list of
 460 "data sources") associated with the object are ignored, because
 461 C<plugin_dispatch_values> will automatically lookup the required data set. It
 462 is therefore absolutely okay to leave this blank.
 463
 464 Returns zero upon success or non-zero upon failure.
 465
 466 =head2 getDS
 467
 468 Signature: I<DataSet> B<getDS> (I<String>)
 469
 470 Returns the appropriate I<type> or B<null> if the type is not defined.
 471
 472 =head2 logError
 473
 474 Signature: I<void> B<logError> (I<String>)
 475
 476 Sends a log message with severity B<ERROR> to the daemon.
 477
 478 =head2 logWarning
 479
 480 Signature: I<void> B<logWarning> (I<String>)
 481
 482 Sends a log message with severity B<WARNING> to the daemon.
 483
 484 =head2 logNotice
 485
 486 Signature: I<void> B<logNotice> (I<String>)
 487
 488 Sends a log message with severity B<NOTICE> to the daemon.
 489
 490 =head2 logInfo
 491
 492 Signature: I<void> B<logInfo> (I<String>)
 493
 494 Sends a log message with severity B<INFO> to the daemon.
 495
 496 =head2 logDebug
 497
 498 Signature: I<void> B<logDebug> (I<String>)
 499
 500 Sends a log message with severity B<DEBUG> to the daemon.
 501
 502 =head1 SEE ALSO
 503
 504 L<collectd(1)>,
 505 L<collectd.conf(5)>,
 506 L<collectd-perl(5)>,
 507 L<types.db(5)>
 508
 509 =head1 AUTHOR
 510
 511 Florian Forster E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt>
 512