+=encoding UTF-8
+
=head1 NAME
collectd-perl - Documentation of collectd's C<perl plugin>
# ...
<Plugin perl>
IncludeDir "/path/to/perl/plugins"
- BaseName "Collectd::Plugin"
+ BaseName "Collectd::Plugins"
EnableDebugger ""
LoadPlugin "FooBar"
=item B<BaseName> I<Name>
Prepends I<Name>B<::> to all plugin names loaded after this option. This is
-provided for convenience to keep plugin names short.
+provided for convenience to keep plugin names short. All Perl-based plugins
+provided with the I<collectd> distributions reside in the C<Collectd::Plugins>
+namespace.
=item E<lt>B<Plugin> I<Name>E<gt> block
=item Config-Item
-A config-item is one structure which keeps the informations provided in the
+A config-item is one structure which keeps the information provided in the
configuration file. The array of children keeps one entry for each
configuration option. Each such entry is another config-item structure, which
may nest further if nested blocks are used.
[{
name => 'data_source_name',
- type => DS_TYPE_COUNTER || DS_TYPE_GAUGE,
+ type => DS_TYPE_COUNTER || DS_TYPE_GAUGE || DS_TYPE_DERIVE || DS_TYPE_ABSOLUTE,
min => value || undef,
max => value || undef
}, ...]
{
values => [123, 0.5],
time => time (),
+ interval => plugin_get_interval (),
host => $hostname_g,
plugin => 'myplugin',
type => 'myplugin',
=item Notification
A notification is one structure defining the severity, time and message of the
-status message as well as an identification of a data instance:
+status message as well as an identification of a data instance. Also, it
+includes an optional list of user-defined meta information represented as
+(name, value) pairs:
{
severity => NOTIF_FAILURE || NOTIF_WARNING || NOTIF_OKAY,
plugin => 'myplugin',
type => 'mytype',
plugin_instance => '',
- type_instance => ''
+ type_instance => '',
+ meta => [ { name => <name>, value => <value> }, ... ]
+ }
+
+=item Match-Proc
+
+A match-proc is one structure storing the callbacks of a "match" of the filter
+chain infrastructure. The general layout looks like this:
+
+ {
+ create => 'my_create',
+ destroy => 'my_destroy',
+ match => 'my_match'
+ }
+
+=item Target-Proc
+
+A target-proc is one structure storing the callbacks of a "target" of the
+filter chain infrastructure. The general layout looks like this:
+
+ {
+ create => 'my_create',
+ destroy => 'my_destroy',
+ invoke => 'my_invoke'
}
=back
file which are automatically registered with collectd - see L<types.db(5)> for
a description of the format of this file.
+B<Note>: Using B<plugin_register> to register a data-set is deprecated. Add
+the new type to a custom L<types.db(5)> file instead. This functionality might
+be removed in a future version of collectd.
+
If the I<type> argument is any of the other types (B<TYPE_INIT>, B<TYPE_READ>,
...) then I<data> is expected to be a function name. If the name is not
prefixed with the plugin's package name collectd will add it automatically.
type, data-set and value-list is passed to all write-callbacks that are
registered with the daemon.
-B<Note>: Prior to version 4.4 of collectd, the data-set type used to be passed
-as the first argument to B<plugin_register>. This syntax is still supported
-for backwards compatibility but has been deprecated and will be removed in
-some future version of collectd.
+=item B<plugin_write> ([B<plugins> => I<...>][, B<datasets> => I<...>],
+B<valuelists> => I<...>)
+
+Calls the write function of the given I<plugins> with the provided I<data
+sets> and I<value lists>. In contrast to B<plugin_dispatch_values>, it does
+not update collectd's internal cache and bypasses the filter mechanism (see
+L<collectd.conf(5)> for details). If the B<plugins> argument has been omitted,
+the values will be dispatched to all registered write plugins. If the
+B<datasets> argument has been omitted, the required data sets are looked up
+according to the C<type> member in the appropriate value list. The value of
+all three arguments may either be a single scalar or a reference to an array.
+If the B<datasets> argument has been specified, the number of data sets has to
+equal the number of specified value lists.
=item B<plugin_flush> ([B<timeout> => I<timeout>][, B<plugins> => I<...>][,
B<identifiers> => I<...>])
Flush one or more plugins. I<timeout> and the specified I<identifiers> are
passed on to the registered flush-callbacks. If omitted, the timeout defaults
-to C<-1>. The identifier defaults to the undefined value. If the
I<plugins>
+to C<-1>. The identifier defaults to the undefined value. If the
B<plugins>
argument has been specified, only named plugins will be flushed. The value of
the B<plugins> and B<identifiers> arguments may either be a string or a
reference to an array of strings.
-=item B<plugin_flush_one> (I<timeout>, I<plugin>)
-
-This is identical to using "plugin_flush (timeout =E<gt> I<timeout>, plugins
-=E<gt> I<plugin>".
-
-B<Note>: Starting with version 4.5 of collectd, B<plugin_flush_one> has been
-deprecated and will be removed in some future version of collectd. Use
-B<plugin_flush> instead.
-
-=item B<plugin_flush_all> (I<timeout>)
-
-This is identical to using "plugin_flush (timeout =E<gt> I<timeout>)".
-
-B<Note>: Starting with version 4.5 of collectd, B<plugin_flush_all> has been
-deprecated and will be removed in some future version of collectd. Use
-B<plugin_flush> instead.
-
=item B<plugin_dispatch_notification> (I<notification>)
Submits a I<notification> to the daemon which will then pass it to all
Wrappers around B<plugin_log>, using B<LOG_ERR>, B<LOG_WARNING>,
B<LOG_NOTICE>, B<LOG_INFO> and B<LOG_DEBUG> respectively as I<log-level>.
+=item B<plugin_get_interval> ()
+
+Returns the interval of the current plugin as a floating point number in
+seconds. This value depends on the interval configured within the
+C<LoadPlugin perl> block or the global interval (see L<collectd.conf(5)> for
+details).
+
+=back
+
+The following function provides the filter chain C-interface to Perl-modules.
+It is exported by the ":filter_chain" export tag (see the section "EXPORTS"
+below).
+
+=over 4
+
+=item B<fc_register> (I<type>, I<name>, I<proc>)
+
+Registers filter chain callbacks with collectd.
+
+I<type> may be any of:
+
+=over 4
+
+=item FC_MATCH
+
+=item FC_TARGET
+
+=back
+
+I<name> is the name of the match or target. By this name, the callbacks are
+identified in the configuration file when specifying a B<Match> or B<Target>
+block (see L<collectd.conf(5)> for details).
+
+I<proc> is a hash reference. The hash includes up to three callbacks: an
+optional constructor (B<create>) and destructor (B<destroy>) and a mandatory
+B<match> or B<invoke> callback. B<match> is called whenever processing an
+appropriate match, while B<invoke> is called whenever processing an
+appropriate target (see the section "FILTER CONFIGURATION" in
+L<collectd.conf(5)> for details). Just like any other callbacks, filter chain
+callbacks are identified by the function name rather than a function pointer
+because Perl does not support to share references to subroutines between
+threads. The following arguments are passed to the callbacks:
+
+=over 4
+
+=item create
+
+The arguments passed are I<config-item> and I<user-data>. See above for the
+layout of the config-item data-type. I<user-data> is a reference to a scalar
+value that may be used to store any information specific to this particular
+instance. The daemon does not care about this information at all. It's for the
+plugin's use only.
+
+=item destroy
+
+The only argument passed is I<user-data> which is a reference to the user data
+initialized in the B<create> callback. This callback may be used to cleanup
+instance-specific information and settings.
+
+=item match, invoke
+
+The arguments passed are I<data-set>, I<value-list>, I<meta> and I<user-data>.
+See above for the layout of the data-set and value-list data-types. I<meta> is
+a pointer to an array of meta information, just like the B<meta> member of the
+notification data-type (see above). I<user-data> is a reference to the user
+data initialized in the B<create> callback.
+
+=back
+
=back
=head1 GLOBAL VARIABLES
This variable keeps the interval in seconds in which the read functions are
queried (see the B<Interval> configuration option).
+B<Note:> This variable should no longer be used in favor of
+C<plugin_get_interval()> (see above). This function takes any plugin-specific
+interval settings into account (see the C<Interval> option of C<LoadPlugin> in
+L<collectd.conf(5)> for details).
+
=back
Any changes to these variables will be globally visible in collectd.
=item B<DS_TYPE_GAUGE>
+=item B<DS_TYPE_DERIVE>
+
+=item B<DS_TYPE_ABSOLUTE>
+
=back
=item B<:log>
=back
+=item B<:filter_chain>
+
+=over 4
+
+=item B<fc_register>
+
+=item B<FC_MATCH_NO_MATCH>
+
+=item B<FC_MATCH_MATCHES>
+
+=item B<FC_TARGET_CONTINUE>
+
+=item B<FC_TARGET_STOP>
+
+=item B<FC_TARGET_RETURN>
+
+=back
+
+=item B<:fc_types>
+
+=over 4
+
+=item B<FC_MATCH>
+
+=item B<FC_TARGET>
+
+=back
+
=item B<:notif>
=over 4
use Collectd qw( :all );
-A very simple read function will look like:
+A very simple read function might look like:
sub foobar_read
{
- my $vl = { plugin => 'foobar' };
+ my $vl = { plugin => 'foobar', type => 'gauge' };
$vl->{'values'} = [ rand(42) ];
- plugin_dispatch_values ('gauge', $vl);
+ plugin_dispatch_values ($vl);
return 1;
}
-A very simple write function will look like:
+A very simple write function might look like:
sub foobar_write
{
return 1;
}
+A very simple match callback might look like:
+
+ sub foobar_match
+ {
+ my ($ds, $vl, $meta, $user_data) = @_;
+ if (matches($ds, $vl)) {
+ return FC_MATCH_MATCHES;
+ } else {
+ return FC_MATCH_NO_MATCH;
+ }
+ }
+
To register those functions with collectd:
plugin_register (TYPE_READ, "foobar", "foobar_read");
plugin_register (TYPE_WRITE, "foobar", "foobar_write");
+ fc_register (FC_MATCH, "foobar", "foobar_match");
+
See the section "DATA TYPES" above for a complete documentation of the data
-types used by the read and write functions.
+types used by the read, write and match functions.
=head1 NOTES
=over 4
-=item
+=item *
-Please feel free to send in new plugins to collectd's mailinglist at
+Please feel free to send in new plugins to collectd's mailing list at
E<lt>collectdE<nbsp>atE<nbsp>verplant.orgE<gt> for review and, possibly,
inclusion in the main distribution. In the latter case, we will take care of
keeping the plugin up to date and adapting it to new versions of collectd.
=over 4
-=item
+=item *
collectd is heavily multi-threaded. Each collectd thread accessing the perl
plugin will be mapped to a Perl interpreter thread (see L<threads(3perl)>).
that no data is shared between threads by default. You have to use the
B<threads::shared> module to do so.
-=item
+=item *
Each function name registered with collectd has to be available before the
first thread has been created (i.E<nbsp>e. basically at compile time). This
will not work. This is due to the fact that the symbol table is not shared
across different threads.
-=item
+=item *
Each plugin is usually only loaded once and kept in memory for performance
reasons. Therefore, END blocks are only executed once when collectd shuts
down. You should not rely on END blocks anyway - use B<shutdown functions>
instead.
-=item
+=item *
The perl plugin exports the internal API of collectd which is considered
unstable and subject to change at any time. We try hard to not break backwards
=over 4
-=item
+=item *
Currently, it is not possible to flush a single Perl plugin only. You can
either flush all Perl plugins or none at all and you have to use C<perl> as
projects / collectd.git / blobdiff