src/collectd-perl.pod

   1 =head1 NAME
   2
   3 collectd-perl - Documentation of collectd's C<perl plugin>
   4
   5 =head1 SYNOPSIS
   6
   7   LoadPlugin perl
   8   # ...
   9   <Plugin perl>
  10     IncludeDir "/path/to/perl/plugins"
  11     BaseName "Collectd::Plugin"
  12     EnableDebugger ""
  13     LoadPlugin "FooBar"
  14
  15     <Plugin FooBar>
  16       Foo "Bar"
  17     </Plugin>
  18   </Plugin>
  19
  20 =head1 DESCRIPTION
  21
  22 The C<perl plugin> embeds a Perl-interpreter into collectd and provides an
  23 interface to collectd's plugin system. This makes it possible to write plugins
  24 for collectd in Perl. This is a lot more efficient than executing a
  25 Perl-script every time you want to read a value with the C<exec plugin> (see
  26 L<collectd-exec(5)>) and provides a lot more functionality, too.
  27
  28 =head1 CONFIGURATION
  29
  30 =over 4
  31
  32 =item B<LoadPlugin> I<Plugin>
  33
  34 Loads the Perl plugin I<Plugin>. This does basically the same as B<use> would
  35 do in a Perl program. As a side effect, the first occurrence of this option
  36 causes the Perl-interpreter to be initialized.
  37
  38 =item B<BaseName> I<Name>
  39
  40 Prepends I<Name>B<::> to all plugin names loaded after this option. This is
  41 provided for convenience to keep plugin names short.
  42
  43 =item E<lt>B<Plugin> I<Name>E<gt> block
  44
  45 This block may be used to pass on configuration settings to a Perl plugin. The
  46 configuration is converted into a config-item data type which is passed to the
  47 registered configuration callback. See below for details about the config-item
  48 data type and how to register callbacks.
  49
  50 The I<name> identifies the callback. It is used literally and independent of
  51 the B<BaseName> setting.
  52
  53 =item B<EnableDebugger> I<Package>[=I<option>,...]
  54
  55 Run collectd under the control of the Perl source debugger. If I<Package> is
  56 not the empty string, control is passed to the debugging, profiling, or
  57 tracing module installed as Devel::I<Package>. A comma-separated list of
  58 options may be specified after the "=" character. Please note that you may not
  59 leave out the I<Package> option even if you specify B<"">. This is the same as
  60 using the B<-d:Package> command line option.
  61
  62 See L<perldebug> for detailed documentation about debugging Perl.
  63
  64 This option does not prevent collectd from daemonizing, so you should start
  65 collectd with the B<-f> command line option. Else you will not be able to use
  66 the command line driven interface of the debugger.
  67
  68 =item B<IncludeDir> I<Dir>
  69
  70 Adds I<Dir> to the B<@INC> array. This is the same as using the B<-IDir>
  71 command line option or B<use lib Dir> in the source code. Please note that it
  72 only has effect on plugins loaded after this option.
  73
  74 =back
  75
  76 =head1 WRITING YOUR OWN PLUGINS
  77
  78 Writing your own plugins is quite simple. collectd manages plugins by means of
  79 B<dispatch functions> which call the appropriate B<callback functions>
  80 registered by the plugins. Any plugin basically consists of the implementation
  81 of these callback functions and initializing code which registers the
  82 functions with collectd. See the section "EXAMPLES" below for a really basic
  83 example. The following types of B<callback functions> are known to collectd
  84 (all of them are optional):
  85
  86 =over 4
  87
  88 =item configuration functions
  89
  90 This type of functions is called during configuration if an appropriate
  91 B<Plugin> block has been encountered. It is called once for each B<Plugin>
  92 block which matches the name of the callback as provided with the
  93 B<plugin_register> method - see below.
  94
  95 =item init functions
  96
  97 This type of functions is called once after loading the module and before any
  98 calls to the read and write functions. It should be used to initialize the
  99 internal state of the plugin (e.E<nbsp>g. open sockets, ...). If the return
 100 value evaluates to B<false>, the plugin will be disabled.
 101
 102 =item read functions
 103
 104 This type of function is used to collect the actual data. It is called once
 105 per interval (see the B<Interval> configuration option of collectd). Usually
 106 it will call B<plugin_dispatch_values> to dispatch the values to collectd
 107 which will pass them on to all registered B<write functions>. If the return
 108 value evaluates to B<false> the plugin will be skipped for an increasing
 109 amount of time until it returns B<true> again.
 110
 111 =item write functions
 112
 113 This type of function is used to write the dispatched values. It is called
 114 once for each call to B<plugin_dispatch_values>.
 115
 116 =item flush functions
 117
 118 This type of function is used to flush internal caches of plugins. It is
 119 usually triggered by the user only. Any plugin which caches data before
 120 writing it to disk should provide this kind of callback function.
 121
 122 =item log functions
 123
 124 This type of function is used to pass messages of plugins or the daemon itself
 125 to the user.
 126
 127 =item notification function
 128
 129 This type of function is used to act upon notifications. In general, a
 130 notification is a status message that may be associated with a data instance.
 131 Usually, a notification is generated by the daemon if a configured threshold
 132 has been exceeded (see the section "THRESHOLD CONFIGURATION" in
 133 L<collectd.conf(5)> for more details), but any plugin may dispatch
 134 notifications as well.
 135
 136 =item shutdown functions
 137
 138 This type of function is called once before the daemon shuts down. It should
 139 be used to clean up the plugin (e.g. close sockets, ...).
 140
 141 =back
 142
 143 Any function (except log functions) may set the B<$@> variable to describe
 144 errors in more detail. The message will be passed on to the user using
 145 collectd's logging mechanism.
 146
 147 See the documentation of the B<plugin_register> method in the section
 148 "METHODS" below for the number and types of arguments passed to each
 149 B<callback function>. This section also explains how to register B<callback
 150 functions> with collectd.
 151
 152 To enable a plugin, copy it to a place where Perl can find it (i.E<nbsp>e. a
 153 directory listed in the B<@INC> array) just as any other Perl plugin and add
 154 an appropriate B<LoadPlugin> option to the configuration file. After
 155 restarting collectd you're done.
 156
 157 =head1 DATA TYPES
 158
 159 The following complex types are used to pass values between the Perl plugin
 160 and collectd:
 161
 162 =over 4
 163
 164 =item Config-Item
 165
 166 A config-item is one structure which keeps the informations provided in the
 167 configuration file. The array of children keeps one entry for each
 168 configuration option. Each such entry is another config-item structure, which
 169 may nest further if nested blocks are used.
 170
 171   {
 172     key      => key,
 173     values   => [ val1, val2, ... ],
 174     children => [ { ... }, { ... }, ... ]
 175   }
 176
 177 =item Data-Set
 178
 179 A data-set is a list of one or more data-sources. Each data-source defines a
 180 name, type, min- and max-value and the data-set wraps them up into one
 181 structure. The general layout looks like this:
 182
 183   [{
 184     name => 'data_source_name',
 185     type => DS_TYPE_COUNTER || DS_TYPE_GAUGE,
 186     min  => value || undef,
 187     max  => value || undef
 188   }, ...]
 189
 190 =item Value-List
 191
 192 A value-list is one structure which features an array of values and fields to
 193 identify the values, i.E<nbsp>e. time and host, plugin name and
 194 plugin-instance as well as a type and type-instance. Since the "type" is not
 195 included in the value-list but is passed as an extra argument, the general
 196 layout looks like this:
 197
 198   {
 199     values => [123, 0.5],
 200     time   => time (),
 201     interval => $interval_g,
 202     host   => $hostname_g,
 203     plugin => 'myplugin',
 204     type   => 'myplugin',
 205     plugin_instance => '',
 206     type_instance   => ''
 207   }
 208
 209 =item Notification
 210
 211 A notification is one structure defining the severity, time and message of the
 212 status message as well as an identification of a data instance:
 213
 214   {
 215     severity => NOTIF_FAILURE || NOTIF_WARNING || NOTIF_OKAY,
 216     time     => time (),
 217     message  => 'status message',
 218     host     => $hostname_g,
 219     plugin   => 'myplugin',
 220     type     => 'mytype',
 221     plugin_instance => '',
 222     type_instance   => ''
 223   }
 224
 225 =back
 226
 227 =head1 METHODS
 228
 229 The following functions provide the C-interface to Perl-modules. They are
 230 exported by the ":plugin" export tag (see the section "EXPORTS" below).
 231
 232 =over 4
 233
 234 =item B<plugin_register> (I<type>, I<name>, I<data>)
 235
 236 Registers a callback-function or data-set.
 237
 238 I<type> can be one of:
 239
 240 =over 4
 241
 242 =item TYPE_CONFIG
 243
 244 =item TYPE_INIT
 245
 246 =item TYPE_READ
 247
 248 =item TYPE_WRITE
 249
 250 =item TYPE_FLUSH
 251
 252 =item TYPE_LOG
 253
 254 =item TYPE_NOTIF
 255
 256 =item TYPE_SHUTDOWN
 257
 258 =item TYPE_DATASET
 259
 260 =back
 261
 262 I<name> is the name of the callback-function or the type of the data-set,
 263 depending on the value of I<type>. (Please note that the type of the data-set
 264 is the value passed as I<name> here and has nothing to do with the I<type>
 265 argument which simply tells B<plugin_register> what is being registered.)
 266
 267 The last argument, I<data>, is either a function name or an array-reference.
 268 If I<type> is B<TYPE_DATASET>, then the I<data> argument must be an
 269 array-reference which points to an array of hashes. Each hash describes one
 270 data-set. For the exact layout see B<Data-Set> above. Please note that
 271 there is a large number of predefined data-sets available in the B<types.db>
 272 file which are automatically registered with collectd - see L<types.db(5)> for
 273 a description of the format of this file.
 274
 275 If the I<type> argument is any of the other types (B<TYPE_INIT>, B<TYPE_READ>,
 276 ...) then I<data> is expected to be a function name. If the name is not
 277 prefixed with the plugin's package name collectd will add it automatically.
 278 The interface slightly differs from the C interface (which expects a function
 279 pointer instead) because Perl does not support to share references to
 280 subroutines between threads.
 281
 282 These functions are called in the various stages of the daemon (see the
 283 section "WRITING YOUR OWN PLUGINS" above) and are passed the following
 284 arguments:
 285
 286 =over 4
 287
 288 =item TYPE_CONFIG
 289
 290 The only argument passed is I<config-item>. See above for the layout of this
 291 data type.
 292
 293 =item TYPE_INIT
 294
 295 =item TYPE_READ
 296
 297 =item TYPE_SHUTDOWN
 298
 299 No arguments are passed.
 300
 301 =item TYPE_WRITE
 302
 303 The arguments passed are I<type>, I<data-set>, and I<value-list>. I<type> is a
 304 string. For the layout of I<data-set> and I<value-list> see above.
 305
 306 =item TYPE_FLUSH
 307
 308 The arguments passed are I<timeout> and I<identifier>. I<timeout> indicates
 309 that only data older than I<timeout> seconds is to be flushed. I<identifier>
 310 specifies which values are to be flushed.
 311
 312 =item TYPE_LOG
 313
 314 The arguments are I<log-level> and I<message>. The log level is small for
 315 important messages and high for less important messages. The least important
 316 level is B<LOG_DEBUG>, the most important level is B<LOG_ERR>. In between there
 317 are (from least to most important): B<LOG_INFO>, B<LOG_NOTICE>, and
 318 B<LOG_WARNING>. I<message> is simply a string B<without> a newline at the end.
 319
 320 =item TYPE_NOTIF
 321
 322 The only argument passed is I<notification>. See above for the layout of this
 323 data type.
 324
 325 =back
 326
 327 =item B<plugin_unregister> (I<type>, I<plugin>)
 328
 329 Removes a callback or data-set from collectd's internal list of
 330 functionsE<nbsp>/ datasets.
 331
 332 =item B<plugin_dispatch_values> (I<value-list>)
 333
 334 Submits a I<value-list> to the daemon. If the data-set identified by
 335 I<value-list>->{I<type>}
 336 is found (and the number of values matches the number of data-sources) then the
 337 type, data-set and value-list is passed to all write-callbacks that are
 338 registered with the daemon.
 339
 340 B<Note>: Prior to version 4.4 of collectd, the data-set type used to be passed
 341 as the first argument to B<plugin_register>. This syntax is still supported
 342 for backwards compatibility but has been deprecated and will be removed in
 343 some future version of collectd.
 344
 345 =item B<plugin_write> ([B<plugins> => I<...>][, B<datasets> => I<...>],
 346 B<valuelists> => I<...>)
 347
 348 Calls the write function of the given I<plugins> with the provided I<data
 349 sets> and I<value lists>. In contrast to B<plugin_dispatch_values>, it does
 350 not update collectd's internal cache and bypasses the filter mechanism (see
 351 L<collectd.conf(5)> for details). If the B<plugins> argument has been omitted,
 352 the values will be dispatched to all registered write plugins. If the
 353 B<datasets> argument has been omitted, the required data sets are looked up
 354 according to the C<type> member in the appropriate value list. The value of
 355 all three arguments may either be a single scalar or a reference to an array.
 356 If the B<datasets> argument has been specified, the number of data sets has to
 357 equal the number of specified value lists.
 358
 359 =item B<plugin_flush> ([B<timeout> => I<timeout>][, B<plugins> => I<...>][,
 360 B<identifiers> => I<...>])
 361
 362 Flush one or more plugins. I<timeout> and the specified I<identifiers> are
 363 passed on to the registered flush-callbacks. If omitted, the timeout defaults
 364 to C<-1>. The identifier defaults to the undefined value. If the B<plugins>
 365 argument has been specified, only named plugins will be flushed. The value of
 366 the B<plugins> and B<identifiers> arguments may either be a string or a
 367 reference to an array of strings.
 368
 369 =item B<plugin_flush_one> (I<timeout>, I<plugin>)
 370
 371 This is identical to using "plugin_flush (timeout =E<gt> I<timeout>, plugins
 372 =E<gt> I<plugin>".
 373
 374 B<Note>: Starting with version 4.5 of collectd, B<plugin_flush_one> has been
 375 deprecated and will be removed in some future version of collectd. Use
 376 B<plugin_flush> instead.
 377
 378 =item B<plugin_flush_all> (I<timeout>)
 379
 380 This is identical to using "plugin_flush (timeout =E<gt> I<timeout>)".
 381
 382 B<Note>: Starting with version 4.5 of collectd, B<plugin_flush_all> has been
 383 deprecated and will be removed in some future version of collectd. Use
 384 B<plugin_flush> instead.
 385
 386 =item B<plugin_dispatch_notification> (I<notification>)
 387
 388 Submits a I<notification> to the daemon which will then pass it to all
 389 notification-callbacks that are registered.
 390
 391 =item B<plugin_log> (I<log-level>, I<message>)
 392
 393 Submits a I<message> of level I<log-level> to collectd's logging mechanism.
 394 The message is passed to all log-callbacks that are registered with collectd.
 395
 396 =item B<ERROR>, B<WARNING>, B<NOTICE>, B<INFO>, B<DEBUG> (I<message>)
 397
 398 Wrappers around B<plugin_log>, using B<LOG_ERR>, B<LOG_WARNING>,
 399 B<LOG_NOTICE>, B<LOG_INFO> and B<LOG_DEBUG> respectively as I<log-level>.
 400
 401 =back
 402
 403 =head1 GLOBAL VARIABLES
 404
 405 =over 4
 406
 407 =item B<$hostname_g>
 408
 409 As the name suggests this variable keeps the hostname of the system collectd
 410 is running on. The value might be influenced by the B<Hostname> or
 411 B<FQDNLookup> configuration options (see L<collectd.conf(5)> for details).
 412
 413 =item B<$interval_g>
 414
 415 This variable keeps the interval in seconds in which the read functions are
 416 queried (see the B<Interval> configuration option).
 417
 418 =back
 419
 420 Any changes to these variables will be globally visible in collectd.
 421
 422 =head1 EXPORTS
 423
 424 By default no symbols are exported. However, the following export tags are
 425 available (B<:all> will export all of them):
 426
 427 =over 4
 428
 429 =item B<:plugin>
 430
 431 =over 4
 432
 433 =item B<plugin_register> ()
 434
 435 =item B<plugin_unregister> ()
 436
 437 =item B<plugin_dispatch_values> ()
 438
 439 =item B<plugin_flush> ()
 440
 441 =item B<plugin_flush_one> ()
 442
 443 =item B<plugin_flush_all> ()
 444
 445 =item B<plugin_dispatch_notification> ()
 446
 447 =item B<plugin_log> ()
 448
 449 =back
 450
 451 =item B<:types>
 452
 453 =over 4
 454
 455 =item B<TYPE_CONFIG>
 456
 457 =item B<TYPE_INIT>
 458
 459 =item B<TYPE_READ>
 460
 461 =item B<TYPE_WRITE>
 462
 463 =item B<TYPE_FLUSH>
 464
 465 =item B<TYPE_SHUTDOWN>
 466
 467 =item B<TYPE_LOG>
 468
 469 =item B<TYPE_DATASET>
 470
 471 =back
 472
 473 =item B<:ds_types>
 474
 475 =over 4
 476
 477 =item B<DS_TYPE_COUNTER>
 478
 479 =item B<DS_TYPE_GAUGE>
 480
 481 =back
 482
 483 =item B<:log>
 484
 485 =over 4
 486
 487 =item B<ERROR> ()
 488
 489 =item B<WARNING> ()
 490
 491 =item B<NOTICE> ()
 492
 493 =item B<INFO> ()
 494
 495 =item B<DEBUG> ()
 496
 497 =item B<LOG_ERR>
 498
 499 =item B<LOG_WARNING>
 500
 501 =item B<LOG_NOTICE>
 502
 503 =item B<LOG_INFO>
 504
 505 =item B<LOG_DEBUG>
 506
 507 =back
 508
 509 =item B<:notif>
 510
 511 =over 4
 512
 513 =item B<NOTIF_FAILURE>
 514
 515 =item B<NOTIF_WARNING>
 516
 517 =item B<NOTIF_OKAY>
 518
 519 =back
 520
 521 =item B<:globals>
 522
 523 =over 4
 524
 525 =item B<$hostname_g>
 526
 527 =item B<$interval_g>
 528
 529 =back
 530
 531 =back
 532
 533 =head1 EXAMPLES
 534
 535 Any Perl plugin will start similar to:
 536
 537   package Collectd::Plugins::FooBar;
 538
 539   use strict;
 540   use warnings;
 541
 542   use Collectd qw( :all );
 543
 544 A very simple read function will look like:
 545
 546   sub foobar_read
 547   {
 548     my $vl = { plugin => 'foobar' };
 549     $vl->{'values'} = [ rand(42) ];
 550     plugin_dispatch_values ('gauge', $vl);
 551     return 1;
 552   }
 553
 554 A very simple write function will look like:
 555
 556   sub foobar_write
 557   {
 558     my ($type, $ds, $vl) = @_;
 559     for (my $i = 0; $i < scalar (@$ds); ++$i) {
 560       print "$vl->{'plugin'} ($vl->{'type'}): $vl->{'values'}->[$i]\n";
 561     }
 562     return 1;
 563   }
 564
 565 To register those functions with collectd:
 566
 567   plugin_register (TYPE_READ, "foobar", "foobar_read");
 568   plugin_register (TYPE_WRITE, "foobar", "foobar_write");
 569
 570 See the section "DATA TYPES" above for a complete documentation of the data
 571 types used by the read and write functions.
 572
 573 =head1 NOTES
 574
 575 =over 4
 576
 577 =item
 578
 579 Please feel free to send in new plugins to collectd's mailinglist at
 580 E<lt>collectdE<nbsp>atE<nbsp>verplant.orgE<gt> for review and, possibly,
 581 inclusion in the main distribution. In the latter case, we will take care of
 582 keeping the plugin up to date and adapting it to new versions of collectd.
 583
 584 Before submitting your plugin, please take a look at
 585 L<http://collectd.org/dev-info.shtml>.
 586
 587 =back
 588
 589 =head1 CAVEATS
 590
 591 =over 4
 592
 593 =item
 594
 595 collectd is heavily multi-threaded. Each collectd thread accessing the perl
 596 plugin will be mapped to a Perl interpreter thread (see L<threads(3perl)>).
 597 Any such thread will be created and destroyed transparently and on-the-fly.
 598
 599 Hence, any plugin has to be thread-safe if it provides several entry points
 600 from collectd (i.E<nbsp>e. if it registers more than one callback or if a
 601 registered callback may be called more than once in parallel). Please note
 602 that no data is shared between threads by default. You have to use the
 603 B<threads::shared> module to do so.
 604
 605 =item
 606
 607 Each function name registered with collectd has to be available before the
 608 first thread has been created (i.E<nbsp>e. basically at compile time). This
 609 basically means that hacks (yes, I really consider this to be a hack) like
 610 C<*foo = \&bar; plugin_register (TYPE_READ, "plugin", "foo");> most likely
 611 will not work. This is due to the fact that the symbol table is not shared
 612 across different threads.
 613
 614 =item
 615
 616 Each plugin is usually only loaded once and kept in memory for performance
 617 reasons. Therefore, END blocks are only executed once when collectd shuts
 618 down. You should not rely on END blocks anyway - use B<shutdown functions>
 619 instead.
 620
 621 =item
 622
 623 The perl plugin exports the internal API of collectd which is considered
 624 unstable and subject to change at any time. We try hard to not break backwards
 625 compatibility in the Perl API during the life cycle of one major release.
 626 However, this cannot be guaranteed at all times. Watch out for warnings
 627 dispatched by the perl plugin after upgrades.
 628
 629 =back
 630
 631 =head1 KNOWN BUGS
 632
 633 =over 4
 634
 635 =item
 636
 637 Currently, it is not possible to flush a single Perl plugin only. You can
 638 either flush all Perl plugins or none at all and you have to use C<perl> as
 639 plugin name when doing so.
 640
 641 =back
 642
 643 =head1 SEE ALSO
 644
 645 L<collectd(1)>,
 646 L<collectd.conf(5)>,
 647 L<collectd-exec(5)>,
 648 L<types.db(5)>,
 649 L<perl(1)>,
 650 L<threads(3perl)>,
 651 L<threads::shared(3perl)>,
 652 L<perldebug(1)>
 653
 654 =head1 AUTHOR
 655
 656 The C<perl plugin> has been written by Sebastian Harl
 657 E<lt>shE<nbsp>atE<nbsp>tokkee.orgE<gt>.
 658
 659 This manpage has been written by Florian Forster
 660 E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt> and Sebastian Harl
 661 E<lt>shE<nbsp>atE<nbsp>tokkee.orgE<gt>.
 662
 663 =cut
 664