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 4a01d14..7cd5d72 100644 (file)
--- a/src/collectd-perl.pod
+++ b/src/collectd-perl.pod
@@ -67,7 +67,7 @@ registered by the plugins. Any plugin basically consists of the implementation
 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
 
@@ -92,6 +92,12 @@ amount of time until it returns B<true> again.
 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
@@ -160,6 +166,7 @@ layout looks like this:
     time   => time (),
     host   => $hostname_g,
     plugin => 'myplugin',
+    type   => 'myplugin',
     plugin_instance => '',
     type_instance   => ''
   }
@@ -203,6 +210,8 @@ I<type> can be one of:
 
 =item TYPE_WRITE
 
+=item TYPE_FLUSH
+
 =item TYPE_LOG
 
 =item TYPE_NOTIF
@@ -245,13 +254,19 @@ arguments:
 
 =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
@@ -272,13 +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.
 
+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_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
@@ -332,6 +380,12 @@ available (B<:all> will export all of them):
 
 =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> ()
@@ -348,6 +402,8 @@ available (B<:all> will export all of them):
 
 =item B<TYPE_WRITE>
 
+=item B<TYPE_FLUSH>
+
 =item B<TYPE_SHUTDOWN>
 
 =item B<TYPE_LOG>
@@ -502,6 +558,26 @@ 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
+
+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