perl plugin: Added "<Plugin>" configuration block.

[collectd.git] / src / collectd-perl.pod

diff --git a/src/collectd-perl.pod b/src/collectd-perl.pod
index 8cdf08b..7cd5d72 100644 (file)
--- a/src/collectd-perl.pod
+++ b/src/collectd-perl.pod
@@ -166,6 +166,7 @@ layout looks like this:
     time   => time (),
     host   => $hostname_g,
     plugin => 'myplugin',
+    type   => 'myplugin',
     plugin_instance => '',
     type_instance   => ''
   }
@@ -262,8 +263,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,29 +287,46 @@ 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<...>])
+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.
 
-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> ([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>
+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
@@ -539,6 +558,14 @@ 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