3 collectd-perl - Documentation of collectd's C<perl plugin>
11 IncludeDir "/path/to/perl/plugins"
12 BaseName "Collectd::Plugin"
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.
24 Please note that this is still considered to be experimental and subject to
25 change between minor releases.
29 There are two more complex types you need to know about:
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:
40 name => 'data_source_name',
41 type => DS_TYPE_COUNTER || DS_TYPE_GAUGE
42 min => value || undef,
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
59 plugin_instance => '',
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.
73 =item B<plugin_register> (I<type>, I<name>, I<data>)
75 Registers a callback-function or data-set.
77 I<type> can be one of:
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.)
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.
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
118 No arguments are passed
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.
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.
135 =item B<plugin_unregister> (I<type>, I<plugin>)
137 Removes a callback or data-set from collectd's internal list of
138 functionsE<nbsp>/ datasets.
140 =item B<plugin_dispatch_values> (I<type>, I<value-list>)
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.
147 =item B<plugin_log> (I<log-level>, I<message>)
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.
163 The C<perl plugin> has been written by Sebastian Harl E<lt>shE<nbsp>atE<nbsp>tokkee.orgE<gt>.
165 This manpage has been written by Florian Forster E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt>.