src/collectd-perl.pod

   1 =head1 NAME
   2
   3 collectd-perl - Documentation of collectd's C<perl plugin>
   4
   5 =head1 SYNOPSIS
   6
   7   # See collectd.conf(5)
   8   LoadPlugin perl
   9   # ...
  10   <Plugin perl>
  11     IncludeDir "/path/to/perl/plugins"
  12     BaseName "Collectd::Plugin"
  13     LoadPlugin "FooBar"
  14   </Plugin>
  15
  16 =head1 DESCRIPTION
  17
  18 The C<perl plugin> includes a Perl-interpreter in collectd and provides
  19 Perl-equivalents of the plugin-functions. This makes it possible to write
  20 plugins for collectd in Perl. This is a lot more performant 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 DATA TYPES
  28
  29 There are two more complex types you need to know about:
  30
  31 =over 4
  32
  33 =item Data-Set
  34
  35 A data-set is a list of one or more data-sources. Each data-source defines a
  36 name, type, min- and max-value and the data-set wraps them up into one
  37 structure. The general layout looks like this:
  38
  39   [{
  40     name => 'data_source_name',
  41     type => DS_TYPE_COUNTER || DS_TYPE_GAUGE
  42     min  => value || undef,
  43     max  => value || undef
  44   }, ...]
  45
  46 =item Value-List
  47
  48 A value-list is one structure which features an array of values and fields to
  49 identify the values, i. e. time and host, plugin name and plugin-instance as
  50 well as a type and type-instance. Since the "type" is not included in the
  51 value-list but is passed as an extra argument, the general layout looks like
  52 this:
  53
  54   {
  55     values => [123, 0.5],
  56     time   => time (),
  57     host   => 'localhost',
  58     plugin => 'myplugin',
  59     plugin_instance => '',
  60     type_instance   => ''
  61   }
  62
  63 =back
  64
  65 =head1 METHODS
  66
  67 The following functions provide the C-interface to Perl-modules. They are
  68 automatically exported into the module's namespace. You don't need to C<use>
  69 any special Modules to access them.
  70
  71 =over 4
  72
  73 =item B<plugin_register> (I<type>, I<name>, I<data>)
  74
  75 Registers a callback-function or data-set.
  76
  77 I<type> can be one of:
  78
  79 =over 4
  80
  81 =item TYPE_INIT
  82
  83 =item TYPE_READ
  84
  85 =item TYPE_WRITE
  86
  87 =item TYPE_LOG
  88
  89 =item TYPE_SHUTDOWN
  90
  91 =item TYPE_DATASET
  92
  93 =back
  94
  95 I<name> is the name of the callback-function or the type of the data-set,
  96 depending on the value of I<type>. (Please note that the type of the data-set
  97 is the value passed as I<name> here and has nothing to do with the I<type>
  98 argument which simply tells B<plugin_register> what is being registered.)
  99
 100 The last argument, I<data>, is either a function- or an array-reference. If
 101 I<type> is B<TYPE_DATASET>, then the I<data> argument must be an
 102 array-reference which points to an array of hashes. Each hash describes one
 103 data-source. For the exact layout see B<Data-Set> above.
 104
 105 If the I<type> argument is any of the other types (B<TYPE_INIT>, B<TYPE_READ>,
 106 ...) then I<data> is expected to be a function reference. These functions are
 107 called in the various stages of the daemon and are passed the following
 108 arguments:
 109
 110 =over 4
 111
 112 =item TYPE_INIT
 113
 114 =item TYPE_READ
 115
 116 =item TYPE_SHUTDOWN
 117
 118 No arguments are passed
 119
 120 =item TYPE_WRITE
 121
 122 The arguments passed are I<type>, I<data-set>, and I<value-list>. I<type> is a
 123 string. For the layout of I<data-set> and I<value-list> see above.
 124
 125 =item TYPE_LOG
 126
 127 The arguments are I<log-level> and I<message>. The log level is small for
 128 important messages and high for less important messages. The least important
 129 level is B<LOG_DEBUG>, the most important level is B<LOG_ERR>. In between there
 130 are (from least to most important): B<LOG_INFO>, B<LOG_NOTICE>, and
 131 B<LOG_WARNING>. I<message> is simply a string B<without> a newline at the end.
 132
 133 =back
 134
 135 =item B<plugin_unregister> (I<type>, I<plugin>)
 136
 137 Removes a callback or data-set from collectd's internal list of
 138 functionsE<nbsp>/ datasets.
 139
 140 =item B<plugin_dispatch_values> (I<type>, I<value-list>)
 141
 142 Submits a I<value-list> of type I<type> to the daemon. If the data-set I<type>
 143 is found (and the number of values matches the number of data-sources) then the
 144 type, data-set and value-list is passed to all write-callbacks that are
 145 registered with the daemon.
 146
 147 =item B<plugin_log> (I<log-level>, I<message>)
 148
 149 Submits a I<message> of level I<log-level> to collectd's logging mechanism.
 150 The message is passed to all log-callbacks that are registered with collectd.
 151
 152 =back
 153
 154 =head1 SEE ALSO
 155
 156 L<collectd(1)>,
 157 L<collectd.conf(5)>,
 158 L<collectd-exec(5)>,
 159 L<perl(1)>
 160
 161 =head1 AUTHOR
 162
 163 The C<perl plugin> has been written by Sebastian Harl E<lt>shE<nbsp>atE<nbsp>tokkee.orgE<gt>.
 164
 165 This manpage has been written by Florian Forster E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt>.
 166
 167 =cut