3 collectd-perl - Documentation of collectd's C<perl plugin>
10 IncludeDir "/path/to/perl/plugins"
11 BaseName "Collectd::Plugin"
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.
24 Please note that this is still considered to be experimental and subject to
25 change between minor releases.
31 =item B<LoadPlugin> I<Plugin>
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.
37 =item B<BaseName> I<Name>
39 Prepends I<Name>B<::> to all plugin names loaded after this option. This is
40 provided for convenience to keep plugin names short.
42 =item B<EnableDebugger> I<Package>[=I<option>,...]
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.
51 See L<perldebug> for detailed documentation about debugging Perl.
53 =item B<IncludeDir> I<Dir>
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.
61 =head1 WRITING YOUR OWN PLUGINS
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):
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.
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.
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>.
96 This type of function is used to pass messages of plugins or the daemon itself
99 =item shutdown functions
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, ...).
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.
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.
118 The following complex types are used to pass values between the Perl plugin
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:
130 name => 'data_source_name',
131 type => DS_TYPE_COUNTER || DS_TYPE_GAUGE
132 min => value || undef,
133 max => value || undef
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:
145 values => [123, 0.5],
148 plugin => 'myplugin',
149 plugin_instance => '',
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).
162 =item B<plugin_register> (I<type>, I<name>, I<data>)
164 Registers a callback-function or data-set.
166 I<type> can be one of:
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.)
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.
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
209 No arguments are passed
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.
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.
226 =item B<plugin_unregister> (I<type>, I<plugin>)
228 Removes a callback or data-set from collectd's internal list of
229 functionsE<nbsp>/ datasets.
231 =item B<plugin_dispatch_values> (I<type>, I<value-list>)
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.
238 =item B<plugin_log> (I<log-level>, I<message>)
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.
243 =item B<ERROR>, B<WARNING>, B<NOTICE>, B<INFO>, B<DEBUG> (I<message>)
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>.
252 By default no symbols are exported. However, the following export tags are
253 available (B<:all> will export all of them):
261 =item B<plugin_register> ()
263 =item B<plugin_unregister> ()
265 =item B<plugin_dispatch_values> ()
267 =item B<plugin_log> ()
281 =item B<TYPE_SHUTDOWN>
291 =item B<DS_TYPE_COUNTER>
293 =item B<DS_TYPE_GAUGE>
327 Any Perl plugin will start similar to:
329 package Collectd::Plugins::FooBar;
334 use Collectd qw( :all );
336 A very simple read function will look like:
340 my $vl = { plugin => 'foobar' };
341 $vl->{'values'} = [ rand(42) ];
342 plugin_dispatch_values ('gauge', $vl);
346 A very simple write function will look like:
350 my ($type, $ds, $vl) = @_;
351 for (my $i = 0; $i < scalar (@$ds); ++$i) {
352 print "$vl->{'plugin'} ($vl->{'type'}): $vl->{'values'}->[$i]\n";
357 To register those functions with collectd:
359 plugin_register (TYPE_READ, "foobar", \&foobar_read);
360 plugin_register (TYPE_WRITE, "foobar", \&foobar_write);
362 See the section "DATA TYPES" above for a complete documentation of the data
363 types used by the read and write functions.
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).
382 The C<perl plugin> has been written by Sebastian Harl
383 E<lt>shE<nbsp>atE<nbsp>tokkee.orgE<gt>.
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>.