[{
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 => $interval_g,
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.
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.
=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<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
{
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
projects / collectd.git / blobdiff