Merge branch 'collectd-4.4'

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

diff --git a/src/collectd-perl.pod b/src/collectd-perl.pod
index 5a58d35..c3fcb10 100644 (file)
--- a/src/collectd-perl.pod
+++ b/src/collectd-perl.pod
@@ -11,6 +11,10 @@ collectd-perl - Documentation of collectd's C<perl plugin>
     BaseName "Collectd::Plugin"
     EnableDebugger ""
     LoadPlugin "FooBar"
     BaseName "Collectd::Plugin"
     EnableDebugger ""
     LoadPlugin "FooBar"

+
+    <Plugin FooBar>
+      Foo "Bar"
+    </Plugin>

   </Plugin>
 
 =head1 DESCRIPTION
   </Plugin>
 
 =head1 DESCRIPTION


@@ -36,6 +40,16 @@ causes the Perl-interpreter to be initialized.
 Prepends I<Name>B<::> to all plugin names loaded after this option. This is
 provided for convenience to keep plugin names short.
 
 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
 =item B<EnableDebugger> I<Package>[=I<option>,...]
 
 Run collectd under the control of the Perl source debugger. If I<Package> is


@@ -67,10 +81,17 @@ 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
 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
 
 
 =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
 =item init functions
 
 This type of functions is called once after loading the module and before any


@@ -92,6 +113,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>.
 
 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
 =item log functions
 
 This type of function is used to pass messages of plugins or the daemon itself


@@ -134,6 +161,19 @@ and collectd:
 
 =over 4
 
 
 =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
 =item Data-Set
 
 A data-set is a list of one or more data-sources. Each data-source defines a


@@ -198,12 +238,16 @@ I<type> can be one of:
 
 =over 4
 
 
 =over 4
 

+=item TYPE_CONFIG
+

 =item TYPE_INIT
 
 =item TYPE_READ
 
 =item TYPE_WRITE
 
 =item TYPE_INIT
 
 =item TYPE_READ
 
 =item TYPE_WRITE
 

+=item TYPE_FLUSH
+

 =item TYPE_LOG
 
 =item TYPE_NOTIF
 =item TYPE_LOG
 
 =item TYPE_NOTIF


@@ -240,19 +284,30 @@ arguments:
 
 =over 4
 
 
 =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
 
 =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_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
 =item TYPE_LOG
 
 The arguments are I<log-level> and I<message>. The log level is small for


@@ -286,6 +341,33 @@ 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.
 
 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
 =item B<plugin_dispatch_notification> (I<notification>)
 
 Submits a I<notification> to the daemon which will then pass it to all


@@ -339,6 +421,12 @@ available (B<:all> will export all of them):
 
 =item B<plugin_dispatch_values> ()
 
 
 =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> ()
 =item B<plugin_dispatch_notification> ()
 
 =item B<plugin_log> ()


@@ -349,16 +437,22 @@ available (B<:all> will export all of them):
 
 =over 4
 
 
 =over 4
 

+=item B<TYPE_CONFIG>
+

 =item B<TYPE_INIT>
 
 =item B<TYPE_READ>
 
 =item B<TYPE_WRITE>
 
 =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_SHUTDOWN>
 
 =item B<TYPE_LOG>
 

+=item B<TYPE_DATASET>
+

 =back
 
 =item B<:ds_types>
 =back
 
 =item B<:ds_types>


@@ -509,6 +603,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.
 
 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
 =back
 
 =head1 SEE ALSO