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 simply. 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 name or an array-reference.
190 If 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 name. If the name is not
198 prefixed with the plugin's package name collectd will add it automatically.
199 The interface slightly differs from the C interface (which expects a function
200 pointer instead) because Perl does not support to share references to
201 subroutines between threads.
203 These functions are called in the various stages of the daemon (see the
204 section "WRITING YOUR OWN PLUGINS" above) and are passed the following
215 No arguments are passed
219 The arguments passed are I<type>, I<data-set>, and I<value-list>. I<type> is a
220 string. For the layout of I<data-set> and I<value-list> see above.
224 The arguments are I<log-level> and I<message>. The log level is small for
225 important messages and high for less important messages. The least important
226 level is B<LOG_DEBUG>, the most important level is B<LOG_ERR>. In between there
227 are (from least to most important): B<LOG_INFO>, B<LOG_NOTICE>, and
228 B<LOG_WARNING>. I<message> is simply a string B<without> a newline at the end.
232 =item B<plugin_unregister> (I<type>, I<plugin>)
234 Removes a callback or data-set from collectd's internal list of
235 functionsE<nbsp>/ datasets.
237 =item B<plugin_dispatch_values> (I<type>, I<value-list>)
239 Submits a I<value-list> of type I<type> to the daemon. If the data-set I<type>
240 is found (and the number of values matches the number of data-sources) then the
241 type, data-set and value-list is passed to all write-callbacks that are
242 registered with the daemon.
244 =item B<plugin_log> (I<log-level>, I<message>)
246 Submits a I<message> of level I<log-level> to collectd's logging mechanism.
247 The message is passed to all log-callbacks that are registered with collectd.
249 =item B<ERROR>, B<WARNING>, B<NOTICE>, B<INFO>, B<DEBUG> (I<message>)
251 Wrappers around B<plugin_log>, using B<LOG_ERR>, B<LOG_WARNING>,
252 B<LOG_NOTICE>, B<LOG_INFO> and B<LOG_DEBUG> respectively as I<log-level>.
258 By default no symbols are exported. However, the following export tags are
259 available (B<:all> will export all of them):
267 =item B<plugin_register> ()
269 =item B<plugin_unregister> ()
271 =item B<plugin_dispatch_values> ()
273 =item B<plugin_log> ()
287 =item B<TYPE_SHUTDOWN>
297 =item B<DS_TYPE_COUNTER>
299 =item B<DS_TYPE_GAUGE>
333 Any Perl plugin will start similar to:
335 package Collectd::Plugins::FooBar;
340 use Collectd qw( :all );
342 A very simple read function will look like:
346 my $vl = { plugin => 'foobar' };
347 $vl->{'values'} = [ rand(42) ];
348 plugin_dispatch_values ('gauge', $vl);
352 A very simple write function will look like:
356 my ($type, $ds, $vl) = @_;
357 for (my $i = 0; $i < scalar (@$ds); ++$i) {
358 print "$vl->{'plugin'} ($vl->{'type'}): $vl->{'values'}->[$i]\n";
363 To register those functions with collectd:
365 plugin_register (TYPE_READ, "foobar", "foobar_read");
366 plugin_register (TYPE_WRITE, "foobar", "foobar_write");
368 See the section "DATA TYPES" above for a complete documentation of the data
369 types used by the read and write functions.
373 This plugin does not yet work correctly if collectd uses multiple threads.
374 Perl does not allow multiple threads to access a single interpreter at the
375 same time. As a temporary workaround you should use a single read thread only
376 (see collectd's B<ReadThread> configuration option).
388 The C<perl plugin> has been written by Sebastian Harl
389 E<lt>shE<nbsp>atE<nbsp>tokkee.orgE<gt>.
391 This manpage has been written by Florian Forster
392 E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt> and Sebastian Harl
393 E<lt>shE<nbsp>atE<nbsp>tokkee.orgE<gt>.