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.
26 There are two more complex types you need to know about:
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:
37 name => 'data_source_name',
38 type => DS_TYPE_COUNTER || DS_TYPE_GAUGE
39 min => value || undef,
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
56 plugin_instance => '',
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.
70 =item B<plugin_register> (I<type>, I<name>, I<data>)
72 Registers a callback-function or data-set.
74 I<type> can be one of:
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.)
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.
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
115 No arguments are passed
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.
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.
132 =item B<plugin_unregister> (I<type>, I<plugin>)
134 Removes a callback or data-set from collectd's internal list of
135 functionsE<nbsp>/ datasets.
137 =item B<plugin_dispatch_values> (I<type>, I<value-list>)
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.
144 =item B<plugin_log> (I<log-level>, I<message>)
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.
160 The C<perl plugin> has been written by Sebastian Harl E<lt>shE<nbsp>atE<nbsp>tokkee.orgE<gt>.
162 This manpage has been written by Florian Forster E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt>.