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