X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=src%2Fcollectd-perl.pod;h=b8d72f06fd8605574acc5f4a5a87cb400252d85e;hb=4371ef7f98f6f51ea3df34d5e26e175d6b44a328;hp=8cdf08bb3b6807229bb4a985a5b01f74771f8378;hpb=d9ba7e3ed5d93e9abd34f961fff51676a096ac02;p=collectd.git

diff --git a/src/collectd-perl.pod b/src/collectd-perl.pod
index 8cdf08bb..02563066 100644
--- a/src/collectd-perl.pod
+++ b/src/collectd-perl.pod
@@ -1,3 +1,5 @@
+=encoding UTF-8
+
 =head1 NAME
 
 collectd-perl - Documentation of collectd's C<perl plugin>
@@ -8,9 +10,13 @@ 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"
+
+    <Plugin FooBar>
+      Foo "Bar"
+    </Plugin>
   </Plugin>
 
 =head1 DESCRIPTION
@@ -34,7 +40,19 @@ causes the Perl-interpreter to be initialized.
 =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
+
+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>,...]
 
@@ -71,6 +89,13 @@ example. The following types of B<callback functions> are known to collectd
 
 =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
@@ -140,6 +165,19 @@ and collectd:
 
 =over 4
 
+=item Config-Item
+
+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.
+
+  {
+    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
@@ -148,7 +186,7 @@ structure. The general layout looks like this:
 
   [{
     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
   }, ...]
@@ -164,8 +202,10 @@ layout looks like this:
   {
     values => [123, 0.5],
     time   => time (),
+    interval => plugin_get_interval (),
     host   => $hostname_g,
     plugin => 'myplugin',
+    type   => 'myplugin',
     plugin_instance => '',
     type_instance   => ''
   }
@@ -173,7 +213,9 @@ layout looks like this:
 =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,
@@ -183,7 +225,30 @@ status message as well as an identification of a data instance:
     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
@@ -203,6 +268,8 @@ I<type> can be one of:
 
 =over 4
 
+=item TYPE_CONFIG
+
 =item TYPE_INIT
 
 =item TYPE_READ
@@ -234,6 +301,10 @@ there is a large number of predefined data-sets available in the B<types.db>
 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.
@@ -247,6 +318,11 @@ arguments:
 
 =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
@@ -262,8 +338,9 @@ string. For the layout of I<data-set> and I<value-list> see above.
 
 =item TYPE_FLUSH
 
-The only argument passed is I<timeout> which indicates that only data older
-than I<timeout> seconds is to be flushed.
+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
 
@@ -285,28 +362,37 @@ data type.
 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.
 
-=item B<plugin_flush> ([B<timeout> => I<timeout>,] [B<plugins> => I<...>])
-
-Flush one or more plugins. I<timeout> is passed on to the registered
-flush-callbacks. If omitted, C<-1> is used. If the I<plugins> argument has
-been specified, only named plugins will be flushed. The argument's value 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>".
-
-=item B<plugin_flush_all> (I<timeout>)
-
-This is identical to using "plugin_flush (timeout =E<gt> I<timeout>)".
+=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_dispatch_notification> (I<notification>)
 
@@ -323,6 +409,75 @@ The message is passed to all log-callbacks that are registered with collectd.
 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
@@ -340,6 +495,11 @@ B<FQDNLookup> configuration options (see L<collectd.conf(5)> for details).
 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.
@@ -377,6 +537,8 @@ available (B<:all> will export all of them):
 
 =over 4
 
+=item B<TYPE_CONFIG>
+
 =item B<TYPE_INIT>
 
 =item B<TYPE_READ>
@@ -389,6 +551,8 @@ available (B<:all> will export all of them):
 
 =item B<TYPE_LOG>
 
+=item B<TYPE_DATASET>
+
 =back
 
 =item B<:ds_types>
@@ -399,6 +563,10 @@ available (B<:all> will export all of them):
 
 =item B<DS_TYPE_GAUGE>
 
+=item B<DS_TYPE_DERIVE>
+
+=item B<DS_TYPE_ABSOLUTE>
+
 =back
 
 =item B<:log>
@@ -427,6 +595,34 @@ available (B<:all> will export all of them):
 
 =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
@@ -462,17 +658,17 @@ Any Perl plugin will start similar to:
 
   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
   {
@@ -483,21 +679,35 @@ A very simple write function will look like:
     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.
@@ -511,7 +721,7 @@ L<http://collectd.org/dev-info.shtml>.
 
 =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)>).
@@ -523,7 +733,7 @@ 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
+=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
@@ -532,20 +742,28 @@ C<*foo = \&bar; plugin_register (TYPE_READ, "plugin", "foo");> most likely
 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 *
+
+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
+=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