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