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   </Plugin>
  15
  16 =head1 DESCRIPTION
  17
  18 The C<perl plugin> embeds a Perl-interpreter into collectd and provides an
  19 interface to collectd's plugin system. This makes it possible to write plugins
  20 for collectd in Perl. This is a lot more efficient than executing a
  21 Perl-script every time you want to read a value with the C<exec plugin> (see
  22 L<collectd-exec(5)>) and provides a lot more functionality, too.
  23
  24 Please note that this is still considered to be experimental and subject to
  25 change between minor releases.
  26
  27 =head1 CONFIGURATION
  28
  29 =over 4
  30
  31 =item B<LoadPlugin> I<Plugin>
  32
  33 Loads the Perl plugin I<Plugin>. This does basically the same as B<use> would
  34 do in a Perl program. As a side effect, the first occurrence of this option
  35 causes the Perl-interpreter to be initialized.
  36
  37 =item B<BaseName> I<Name>
  38
  39 Prepends I<Name>B<::> to all plugin names loaded after this option. This is
  40 provided for convenience to keep plugin names short.
  41
  42 =item B<EnableDebugger> I<Package>[=I<option>,...]
  43
  44 Run collectd under the control of the Perl source debugger. If I<Package> is
  45 not the empty string, control is passed to the debugging, profiling, or
  46 tracing module installed as Devel::I<Package>. A comma-separated list of
  47 options may be specified after the "=" character. Please note that you may not
  48 leave out the I<Package> option even if you specify B<"">. This is the same as
  49 using the B<-d:Package> command line option.
  50
  51 See L<perldebug> for detailed documentation about debugging Perl.
  52
  53 This option does not prevent collectd from daemonizing, so you should start
  54 collectd with the B<-f> command line option. Else you will not be able to use
  55 the command line driven interface of the debugger.
  56
  57 =item B<IncludeDir> I<Dir>
  58
  59 Adds I<Dir> to the B<@INC> array. This is the same as using the B<-IDir>
  60 command line option or B<use lib Dir> in the source code. Please note that it
  61 only has effect on plugins loaded after this option.
  62
  63 =back
  64
  65 =head1 WRITING YOUR OWN PLUGINS
  66
  67 Writing your own plugins is quite simply. collectd manages plugins by means of
  68 B<dispatch functions> which call the appropriate B<callback functions>
  69 registered by the plugins. Any plugin basically consists of the implementation
  70 of these callback functions and initializing code which registers the
  71 functions with collectd. See the section "EXAMPLES" below for a really basic
  72 example. The following types of B<callback functions> are known to collectd
  73 (all of these are optional):
  74
  75 =over 4
  76
  77 =item init functions
  78
  79 This type of functions is called once after loading the module and before any
  80 calls to the read and write functions. It should be used to initialize the
  81 internal state of the plugin (e.E<nbsp>g. open sockets, ...). If the return
  82 value evaluates to B<false>, the plugin will be disabled.
  83
  84 =item read functions
  85
  86 This type of function is used to collect the actual data. It is called once
  87 per interval (see the B<Interval> configuration option of collectd). Usually
  88 it will call B<plugin_dispatch_values> to dispatch the values to collectd
  89 which will pass them on to all registered B<write functions>. If the return
  90 value evaluates to B<false> the plugin will be skipped for an increasing
  91 amount of time until it returns B<true> again.
  92
  93 =item write functions
  94
  95 This type of function is used to write the dispatched values. It is called
  96 once for each call to B<plugin_dispatch_values>.
  97
  98 =item log functions
  99
 100 This type of function is used to pass messages of plugins or the daemon itself
 101 to the user.
 102
 103 =item shutdown functions
 104
 105 This type of function is called once before the daemon shuts down. It should
 106 be used to clean up the plugin (e.g. close sockets, ...).
 107
 108 =back
 109
 110 Any function may set the B<$@> variable to describe errors in more detail. The
 111 message will be passed on to the user using collectd's logging mechanism.
 112
 113 See the documentation of the B<plugin_register> method in the section
 114 "METHODS" below for the number and types of arguments passed to each
 115 B<callback function>. This section also explains how to register B<callback
 116 functions> with collectd.
 117
 118 To enable a plugin, copy it to a place where Perl can find it (i.E<nbsp>e. a
 119 directory listed in the B<@INC> array) just as any other Perl plugin and add
 120 an appropriate B<LoadPlugin> option to the configuration file. After
 121 restarting collectd you're done.
 122
 123 =head1 DATA TYPES
 124
 125 The following complex types are used to pass values between the Perl plugin
 126 and collectd:
 127
 128 =over 4
 129
 130 =item Data-Set
 131
 132 A data-set is a list of one or more data-sources. Each data-source defines a
 133 name, type, min- and max-value and the data-set wraps them up into one
 134 structure. The general layout looks like this:
 135
 136   [{
 137     name => 'data_source_name',
 138     type => DS_TYPE_COUNTER || DS_TYPE_GAUGE
 139     min  => value || undef,
 140     max  => value || undef
 141   }, ...]
 142
 143 =item Value-List
 144
 145 A value-list is one structure which features an array of values and fields to
 146 identify the values, i.E<nbsp>e. time and host, plugin name and
 147 plugin-instance as well as a type and type-instance. Since the "type" is not
 148 included in the value-list but is passed as an extra argument, the general
 149 layout looks like this:
 150
 151   {
 152     values => [123, 0.5],
 153     time   => time (),
 154     host   => 'localhost',
 155     plugin => 'myplugin',
 156     plugin_instance => '',
 157     type_instance   => ''
 158   }
 159
 160 =back
 161
 162 =head1 METHODS
 163
 164 The following functions provide the C-interface to Perl-modules. They are
 165 exported by the ":plugin" export tag (see the section "EXPORTS" below).
 166
 167 =over 4
 168
 169 =item B<plugin_register> (I<type>, I<name>, I<data>)
 170
 171 Registers a callback-function or data-set.
 172
 173 I<type> can be one of:
 174
 175 =over 4
 176
 177 =item TYPE_INIT
 178
 179 =item TYPE_READ
 180
 181 =item TYPE_WRITE
 182
 183 =item TYPE_LOG
 184
 185 =item TYPE_SHUTDOWN
 186
 187 =item TYPE_DATASET
 188
 189 =back
 190
 191 I<name> is the name of the callback-function or the type of the data-set,
 192 depending on the value of I<type>. (Please note that the type of the data-set
 193 is the value passed as I<name> here and has nothing to do with the I<type>
 194 argument which simply tells B<plugin_register> what is being registered.)
 195
 196 The last argument, I<data>, is either a function name or an array-reference.
 197 If I<type> is B<TYPE_DATASET>, then the I<data> argument must be an
 198 array-reference which points to an array of hashes. Each hash describes one
 199 data-source. For the exact layout see B<Data-Set> above. Please note that
 200 there is a large number of predefined data-sets available in the B<types.db>
 201 file which are automatically registered with collectd.
 202
 203 If the I<type> argument is any of the other types (B<TYPE_INIT>, B<TYPE_READ>,
 204 ...) then I<data> is expected to be a function name. If the name is not
 205 prefixed with the plugin's package name collectd will add it automatically.
 206 The interface slightly differs from the C interface (which expects a function
 207 pointer instead) because Perl does not support to share references to
 208 subroutines between threads.
 209
 210 These functions are called in the various stages of the daemon (see the
 211 section "WRITING YOUR OWN PLUGINS" above) and are passed the following
 212 arguments:
 213
 214 =over 4
 215
 216 =item TYPE_INIT
 217
 218 =item TYPE_READ
 219
 220 =item TYPE_SHUTDOWN
 221
 222 No arguments are passed
 223
 224 =item TYPE_WRITE
 225
 226 The arguments passed are I<type>, I<data-set>, and I<value-list>. I<type> is a
 227 string. For the layout of I<data-set> and I<value-list> see above.
 228
 229 =item TYPE_LOG
 230
 231 The arguments are I<log-level> and I<message>. The log level is small for
 232 important messages and high for less important messages. The least important
 233 level is B<LOG_DEBUG>, the most important level is B<LOG_ERR>. In between there
 234 are (from least to most important): B<LOG_INFO>, B<LOG_NOTICE>, and
 235 B<LOG_WARNING>. I<message> is simply a string B<without> a newline at the end.
 236
 237 =back
 238
 239 =item B<plugin_unregister> (I<type>, I<plugin>)
 240
 241 Removes a callback or data-set from collectd's internal list of
 242 functionsE<nbsp>/ datasets.
 243
 244 =item B<plugin_dispatch_values> (I<type>, I<value-list>)
 245
 246 Submits a I<value-list> of type I<type> to the daemon. If the data-set I<type>
 247 is found (and the number of values matches the number of data-sources) then the
 248 type, data-set and value-list is passed to all write-callbacks that are
 249 registered with the daemon.
 250
 251 =item B<plugin_log> (I<log-level>, I<message>)
 252
 253 Submits a I<message> of level I<log-level> to collectd's logging mechanism.
 254 The message is passed to all log-callbacks that are registered with collectd.
 255
 256 =item B<ERROR>, B<WARNING>, B<NOTICE>, B<INFO>, B<DEBUG> (I<message>)
 257
 258 Wrappers around B<plugin_log>, using B<LOG_ERR>, B<LOG_WARNING>,
 259 B<LOG_NOTICE>, B<LOG_INFO> and B<LOG_DEBUG> respectively as I<log-level>.
 260
 261 =back
 262
 263 =head1 EXPORTS
 264
 265 By default no symbols are exported. However, the following export tags are
 266 available (B<:all> will export all of them):
 267
 268 =over 4
 269
 270 =item B<:plugin>
 271
 272 =over 4
 273
 274 =item B<plugin_register> ()
 275
 276 =item B<plugin_unregister> ()
 277
 278 =item B<plugin_dispatch_values> ()
 279
 280 =item B<plugin_log> ()
 281
 282 =back
 283
 284 =item B<:types>
 285
 286 =over 4
 287
 288 =item B<TYPE_INIT>
 289
 290 =item B<TYPE_READ>
 291
 292 =item B<TYPE_WRITE>
 293
 294 =item B<TYPE_SHUTDOWN>
 295
 296 =item B<TYPE_LOG>
 297
 298 =back
 299
 300 =item B<:ds_types>
 301
 302 =over 4
 303
 304 =item B<DS_TYPE_COUNTER>
 305
 306 =item B<DS_TYPE_GAUGE>
 307
 308 =back
 309
 310 =item B<:log>
 311
 312 =over 4
 313
 314 =item B<ERROR> ()
 315
 316 =item B<WARNING> ()
 317
 318 =item B<NOTICE> ()
 319
 320 =item B<INFO> ()
 321
 322 =item B<DEBUG> ()
 323
 324 =item B<LOG_ERR>
 325
 326 =item B<LOG_WARNING>
 327
 328 =item B<LOG_NOTICE>
 329
 330 =item B<LOG_INFO>
 331
 332 =item B<LOG_DEBUG>
 333
 334 =back
 335
 336 =back
 337
 338 =head1 EXAMPLES
 339
 340 Any Perl plugin will start similar to:
 341
 342   package Collectd::Plugins::FooBar;
 343
 344   use strict;
 345   use warnings;
 346
 347   use Collectd qw( :all );
 348
 349 A very simple read function will look like:
 350
 351   sub foobar_read
 352   {
 353     my $vl = { plugin => 'foobar' };
 354     $vl->{'values'} = [ rand(42) ];
 355     plugin_dispatch_values ('gauge', $vl);
 356     return 1;
 357   }
 358
 359 A very simple write function will look like:
 360
 361   sub foobar_write
 362   {
 363     my ($type, $ds, $vl) = @_;
 364     for (my $i = 0; $i < scalar (@$ds); ++$i) {
 365       print "$vl->{'plugin'} ($vl->{'type'}): $vl->{'values'}->[$i]\n";
 366     }
 367     return 1;
 368   }
 369
 370 To register those functions with collectd:
 371
 372   plugin_register (TYPE_READ, "foobar", "foobar_read");
 373   plugin_register (TYPE_WRITE, "foobar", "foobar_write");
 374
 375 See the section "DATA TYPES" above for a complete documentation of the data
 376 types used by the read and write functions.
 377
 378 =head1 BUGS
 379
 380 This plugin does not yet work correctly if collectd uses multiple threads.
 381 Perl does not allow multiple threads to access a single interpreter at the
 382 same time. As a temporary workaround you should use a single read thread only
 383 (see collectd's B<ReadThread> configuration option).
 384
 385 =head1 SEE ALSO
 386
 387 L<collectd(1)>,
 388 L<collectd.conf(5)>,
 389 L<collectd-exec(5)>,
 390 L<perl(1)>,
 391 L<perldebug(1)>
 392
 393 =head1 AUTHOR
 394
 395 The C<perl plugin> has been written by Sebastian Harl
 396 E<lt>shE<nbsp>atE<nbsp>tokkee.orgE<gt>.
 397
 398 This manpage has been written by Florian Forster
 399 E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt> and Sebastian Harl
 400 E<lt>shE<nbsp>atE<nbsp>tokkee.orgE<gt>.
 401
 402 =cut
 403