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