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 simple. 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- or an array-reference. If
 190 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 reference. These functions are
 198 called in the various stages of the daemon and are passed the following
 199 arguments:
 200
 201 =over 4
 202
 203 =item TYPE_INIT
 204
 205 =item TYPE_READ
 206
 207 =item TYPE_SHUTDOWN
 208
 209 No arguments are passed
 210
 211 =item TYPE_WRITE
 212
 213 The arguments passed are I<type>, I<data-set>, and I<value-list>. I<type> is a
 214 string. For the layout of I<data-set> and I<value-list> see above.
 215
 216 =item TYPE_LOG
 217
 218 The arguments are I<log-level> and I<message>. The log level is small for
 219 important messages and high for less important messages. The least important
 220 level is B<LOG_DEBUG>, the most important level is B<LOG_ERR>. In between there
 221 are (from least to most important): B<LOG_INFO>, B<LOG_NOTICE>, and
 222 B<LOG_WARNING>. I<message> is simply a string B<without> a newline at the end.
 223
 224 =back
 225
 226 =item B<plugin_unregister> (I<type>, I<plugin>)
 227
 228 Removes a callback or data-set from collectd's internal list of
 229 functionsE<nbsp>/ datasets.
 230
 231 =item B<plugin_dispatch_values> (I<type>, I<value-list>)
 232
 233 Submits a I<value-list> of type I<type> to the daemon. If the data-set I<type>
 234 is found (and the number of values matches the number of data-sources) then the
 235 type, data-set and value-list is passed to all write-callbacks that are
 236 registered with the daemon.
 237
 238 =item B<plugin_log> (I<log-level>, I<message>)
 239
 240 Submits a I<message> of level I<log-level> to collectd's logging mechanism.
 241 The message is passed to all log-callbacks that are registered with collectd.
 242
 243 =item B<ERROR>, B<WARNING>, B<NOTICE>, B<INFO>, B<DEBUG> (I<message>)
 244
 245 Wrappers around B<plugin_log>, using B<LOG_ERR>, B<LOG_WARNING>,
 246 B<LOG_NOTICE>, B<LOG_INFO> and B<LOG_DEBUG> respectively as I<log-level>.
 247
 248 =back
 249
 250 =head1 EXPORTS
 251
 252 By default no symbols are exported. However, the following export tags are
 253 available (B<:all> will export all of them):
 254
 255 =over 4
 256
 257 =item B<:plugin>
 258
 259 =over 4
 260
 261 =item B<plugin_register> ()
 262
 263 =item B<plugin_unregister> ()
 264
 265 =item B<plugin_dispatch_values> ()
 266
 267 =item B<plugin_log> ()
 268
 269 =back
 270
 271 =item B<:types>
 272
 273 =over 4
 274
 275 =item B<TYPE_INIT>
 276
 277 =item B<TYPE_READ>
 278
 279 =item B<TYPE_WRITE>
 280
 281 =item B<TYPE_SHUTDOWN>
 282
 283 =item B<TYPE_LOG>
 284
 285 =back
 286
 287 =item B<:ds_types>
 288
 289 =over 4
 290
 291 =item B<DS_TYPE_COUNTER>
 292
 293 =item B<DS_TYPE_GAUGE>
 294
 295 =back
 296
 297 =item B<:log>
 298
 299 =over 4
 300
 301 =item B<ERROR> ()
 302
 303 =item B<WARNING> ()
 304
 305 =item B<NOTICE> ()
 306
 307 =item B<INFO> ()
 308
 309 =item B<DEBUG> ()
 310
 311 =item B<LOG_ERR>
 312
 313 =item B<LOG_WARNING>
 314
 315 =item B<LOG_NOTICE>
 316
 317 =item B<LOG_INFO>
 318
 319 =item B<LOG_DEBUG>
 320
 321 =back
 322
 323 =back
 324
 325 =head1 EXAMPLES
 326
 327 Any Perl plugin will start similar to:
 328
 329   package Collectd::Plugins::FooBar;
 330
 331   use strict;
 332   use warnings;
 333
 334   use Collectd qw( :all );
 335
 336 A very simple read function will look like:
 337
 338   sub foobar_read
 339   {
 340     my $vl = { plugin => 'foobar' };
 341     $vl->{'values'} = [ rand(42) ];
 342     plugin_dispatch_values ('gauge', $vl);
 343     return 1;
 344   }
 345
 346 A very simple write function will look like:
 347
 348   sub foobar_write
 349   {
 350     my ($type, $ds, $vl) = @_;
 351     for (my $i = 0; $i < scalar (@$ds); ++$i) {
 352       print "$vl->{'plugin'} ($vl->{'type'}): $vl->{'values'}->[$i]\n";
 353     }
 354     return 1;
 355   }
 356
 357 To register those functions with collectd:
 358
 359   plugin_register (TYPE_READ, "foobar", \&foobar_read);
 360   plugin_register (TYPE_WRITE, "foobar", \&foobar_write);
 361
 362 See the section "DATA TYPES" above for a complete documentation of the data
 363 types used by the read and write functions.
 364
 365 =head1 BUGS
 366
 367 This plugin does not yet work correctly if collectd uses multiple threads.
 368 Perl does not allow multiple threads to access a single interpreter at the
 369 same time. As a temporary workaround you should use a single read thread only
 370 (see collectd's B<ReadThread> configuration option).
 371
 372 =head1 SEE ALSO
 373
 374 L<collectd(1)>,
 375 L<collectd.conf(5)>,
 376 L<collectd-exec(5)>,
 377 L<perl(1)>,
 378 L<perldebug(1)>
 379
 380 =head1 AUTHOR
 381
 382 The C<perl plugin> has been written by Sebastian Harl
 383 E<lt>shE<nbsp>atE<nbsp>tokkee.orgE<gt>.
 384
 385 This manpage has been written by Florian Forster
 386 E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt> and Sebastian Harl
 387 E<lt>shE<nbsp>atE<nbsp>tokkee.orgE<gt>.
 388
 389 =cut
 390