BaseName "Collectd::Plugin"
EnableDebugger ""
LoadPlugin "FooBar"
+
+ <Plugin FooBar>
+ Foo "Bar"
+ </Plugin>
</Plugin>
=head1 DESCRIPTION
Prepends I<Name>B<::> to all plugin names loaded after this option. This is
provided for convenience to keep plugin names short.
+=item E<lt>B<Plugin> I<Name>E<gt> block
+
+This block may be used to pass on configuration settings to a Perl plugin. The
+configuration is converted into a config-item data type which is passed to the
+registered configuration callback. See below for details about the config-item
+data type and how to register callbacks.
+
+The I<name> identifies the callback. It is used literally and independent of
+the B<BaseName> setting.
+
=item B<EnableDebugger> I<Package>[=I<option>,...]
Run collectd under the control of the Perl source debugger. If I<Package> is
of these callback functions and initializing code which registers the
functions with collectd. See the section "EXAMPLES" below for a really basic
example. The following types of B<callback functions> are known to collectd
-(all of these are optional):
+(all of them are optional):
=over 4
+=item configuration functions
+
+This type of functions is called during configuration if an appropriate
+B<Plugin> block has been encountered. It is called once for each B<Plugin>
+block which matches the name of the callback as provided with the
+B<plugin_register> method - see below.
+
=item init functions
This type of functions is called once after loading the module and before any
This type of function is used to write the dispatched values. It is called
once for each call to B<plugin_dispatch_values>.
+=item flush functions
+
+This type of function is used to flush internal caches of plugins. It is
+usually triggered by the user only. Any plugin which caches data before
+writing it to disk should provide this kind of callback function.
+
=item log functions
This type of function is used to pass messages of plugins or the daemon itself
to the user.
+=item notification function
+
+This type of function is used to act upon notifications. In general, a
+notification is a status message that may be associated with a data instance.
+Usually, a notification is generated by the daemon if a configured threshold
+has been exceeded (see the section "THRESHOLD CONFIGURATION" in
+L<collectd.conf(5)> for more details), but any plugin may dispatch
+notifications as well.
+
=item shutdown functions
This type of function is called once before the daemon shuts down. It should
=back
-Any function may set the B<$@> variable to describe errors in more detail. The
-message will be passed on to the user using collectd's logging mechanism.
+Any function (except log functions) may set the B<$@> variable to describe
+errors in more detail. The message will be passed on to the user using
+collectd's logging mechanism.
See the documentation of the B<plugin_register> method in the section
"METHODS" below for the number and types of arguments passed to each
=over 4
+=item Config-Item
+
+A config-item is one structure which keeps the informations 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.
+
+ {
+ key => key,
+ values => [ val1, val2, ... ],
+ children => [ { ... }, { ... }, ... ]
+ }
+
=item Data-Set
A data-set is a list of one or more data-sources. Each data-source defines a
[{
name => 'data_source_name',
- type => DS_TYPE_COUNTER || DS_TYPE_GAUGE
+ type => DS_TYPE_COUNTER || DS_TYPE_GAUGE,
min => value || undef,
max => value || undef
}, ...]
{
values => [123, 0.5],
time => time (),
- host => 'localhost',
+ interval => $interval_g,
+ host => $hostname_g,
plugin => 'myplugin',
+ type => 'myplugin',
plugin_instance => '',
type_instance => ''
}
+=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. Also, it
+includes an optional list of user-defined meta information represented as
+(name, value) pairs:
+
+ {
+ severity => NOTIF_FAILURE || NOTIF_WARNING || NOTIF_OKAY,
+ time => time (),
+ message => 'status message',
+ host => $hostname_g,
+ plugin => 'myplugin',
+ type => 'mytype',
+ plugin_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
=head1 METHODS
=over 4
+=item TYPE_CONFIG
+
=item TYPE_INIT
=item TYPE_READ
=item TYPE_WRITE
+=item TYPE_FLUSH
+
=item TYPE_LOG
+=item TYPE_NOTIF
+
=item TYPE_SHUTDOWN
=item TYPE_DATASET
=over 4
+=item TYPE_CONFIG
+
+The only argument passed is I<config-item>. See above for the layout of this
+data type.
+
=item TYPE_INIT
=item TYPE_READ
=item TYPE_SHUTDOWN
-No arguments are passed
+No arguments are passed.
=item TYPE_WRITE
The arguments passed are I<type>, I<data-set>, and I<value-list>. I<type> is a
string. For the layout of I<data-set> and I<value-list> see above.
+=item TYPE_FLUSH
+
+The arguments passed are I<timeout> and I<identifier>. I<timeout> indicates
+that only data older than I<timeout> seconds is to be flushed. I<identifier>
+specifies which values are to be flushed.
+
=item TYPE_LOG
The arguments are I<log-level> and I<message>. The log level is small for
are (from least to most important): B<LOG_INFO>, B<LOG_NOTICE>, and
B<LOG_WARNING>. I<message> is simply a string B<without> a newline at the end.
+=item TYPE_NOTIF
+
+The only argument passed is I<notification>. See above for the layout of this
+data type.
+
=back
=item B<plugin_unregister> (I<type>, I<plugin>)
Removes a callback or data-set from collectd's internal list of
functionsE<nbsp>/ datasets.
-=item B<plugin_dispatch_values> (I<type>, I<value-list>)
+=item B<plugin_dispatch_values> (I<value-list>)
-Submits a I<value-list> of type I<type> to the daemon. If the data-set I<type>
+Submits a I<value-list> to the daemon. If the data-set identified by
+I<value-list>->{I<type>}
is found (and the number of values matches the number of data-sources) then the
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 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
+notification-callbacks that are registered.
+
=item B<plugin_log> (I<log-level>, I<message>)
Submits a I<message> of level I<log-level> to collectd's logging mechanism.
=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
=over 4
=item B<plugin_dispatch_values> ()
+=item B<plugin_flush> ()
+
+=item B<plugin_flush_one> ()
+
+=item B<plugin_flush_all> ()
+
+=item B<plugin_dispatch_notification> ()
+
=item B<plugin_log> ()
=back
=over 4
+=item B<TYPE_CONFIG>
+
=item B<TYPE_INIT>
=item B<TYPE_READ>
=item B<TYPE_WRITE>
+=item B<TYPE_FLUSH>
+
=item B<TYPE_SHUTDOWN>
=item B<TYPE_LOG>
+=item B<TYPE_DATASET>
+
=back
=item B<:ds_types>
=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
+
+=item B<NOTIF_FAILURE>
+
+=item B<NOTIF_WARNING>
+
+=item B<NOTIF_OKAY>
+
+=back
+
=item B<:globals>
=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
{
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
Any such thread will be created and destroyed transparently and on-the-fly.
Hence, any plugin has to be thread-safe if it provides several entry points
-from collectd (i.E<nbsp>e. if it registers more than one callback). Please
-note that no data is shared between threads by default. You have to use the
+from collectd (i.E<nbsp>e. if it registers more than one callback or if a
+registered callback may be called more than once in parallel). Please note
+that no data is shared between threads by default. You have to use the
B<threads::shared> module to do so.
=item
down. You should not rely on END blocks anyway - use B<shutdown functions>
instead.
+=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
+compatibility in the Perl API during the life cycle of one major release.
+However, this cannot be guaranteed at all times. Watch out for warnings
+dispatched by the perl plugin after upgrades.
+
+=back
+
+=head1 KNOWN BUGS
+
+=over 4
+
+=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
+plugin name when doing so.
+
=back
=head1 SEE ALSO
projects / collectd.git / blobdiff