diff --git a/src/collectd-perl.pod b/src/collectd-perl.pod
index 00a1cbbbb8bf5ba553ef483b091c33f1e874adeb..5a58d357dd8ff5e7e1f5bc7988f66becfd4bea16 100644 (file)
--- a/src/collectd-perl.pod
+++ b/src/collectd-perl.pod
This type of function is used to pass messages of plugins or the daemon itself
to the user.
+=item notification function
+
+This type of function is used to act upon notifications. In general, a
+notification is a status message that may be associated with a data instance.
+Usually, a notification is generated by the daemon if a configured threshold
+has been exceeded (see the section "THRESHOLD CONFIGURATION" in
+L<collectd.conf(5)> for more details), but any plugin may dispatch
+notifications as well.
+
=item shutdown functions
This type of function is called once before the daemon shuts down. It should
=back
-Any function may set the B<$@> variable to describe errors in more detail. The
-message will be passed on to the user using collectd's logging mechanism.
+Any function (except log functions) may set the B<$@> variable to describe
+errors in more detail. The message will be passed on to the user using
+collectd's logging mechanism.
See the documentation of the B<plugin_register> method in the section
"METHODS" below for the number and types of arguments passed to each
[{
name => 'data_source_name',
- type => DS_TYPE_COUNTER || DS_TYPE_GAUGE
+ type => DS_TYPE_COUNTER || DS_TYPE_GAUGE,
min => value || undef,
max => value || undef
}, ...]
{
values => [123, 0.5],
time => time (),
- host => 'localhost',
+ host => $hostname_g,
plugin => 'myplugin',
+ type => 'myplugin',
+ plugin_instance => '',
+ type_instance => ''
+ }
+
+=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:
+
+ {
+ severity => NOTIF_FAILURE || NOTIF_WARNING || NOTIF_OKAY,
+ time => time (),
+ message => 'status message',
+ host => $hostname_g,
+ plugin => 'myplugin',
+ type => 'mytype',
plugin_instance => '',
type_instance => ''
}
=item TYPE_LOG
+=item TYPE_NOTIF
+
=item TYPE_SHUTDOWN
=item TYPE_DATASET
The last argument, I<data>, is either a function name or an array-reference.
If I<type> is B<TYPE_DATASET>, then the I<data> argument must be an
array-reference which points to an array of hashes. Each hash describes one
-data-source. For the exact layout see B<Data-Set> above. Please note that
+data-set. For the exact layout see B<Data-Set> above. Please note that
there is a large number of predefined data-sets available in the B<types.db>
-file which are automatically registered with collectd.
+file which are automatically registered with collectd - see L<types.db(5)> for
+a description of the format of this file.
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
@@ -231,6 +261,11 @@ level is B<LOG_DEBUG>, the most important level is B<LOG_ERR>. In between there
are (from least to most important): B<LOG_INFO>, B<LOG_NOTICE>, and
B<LOG_WARNING>. I<message> is simply a string B<without> a newline at the end.
+=item TYPE_NOTIF
+
+The only argument passed is I<notification>. See above for the layout of this
+data type.
+
=back
=item B<plugin_unregister> (I<type>, I<plugin>)
@@ -238,13 +273,24 @@ B<LOG_WARNING>. I<message> is simply a string B<without> a newline at the end.
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_dispatch_notification> (I<notification>)
+
+Submits a I<notification> to the daemon which will then pass it to all
+notification-callbacks that are registered.
+
=item B<plugin_log> (I<log-level>, I<message>)
Submits a I<message> of level I<log-level> to collectd's logging mechanism.
=item B<plugin_dispatch_values> ()
+=item B<plugin_dispatch_notification> ()
+
=item B<plugin_log> ()
=back
=back
+=item B<:notif>
+
+=over 4
+
+=item B<NOTIF_FAILURE>
+
+=item B<NOTIF_WARNING>
+
+=item B<NOTIF_OKAY>
+
+=back
+
=item B<:globals>
=over 4
Any such thread will be created and destroyed transparently and on-the-fly.
Hence, any plugin has to be thread-safe if it provides several entry points
-from collectd (i.E<nbsp>e. if it registers more than one callback). Please
-note that no data is shared between threads by default. You have to use the
+from collectd (i.E<nbsp>e. if it registers more than one callback or if a
+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
L<collectd(1)>,
L<collectd.conf(5)>,
L<collectd-exec(5)>,
+L<types.db(5)>,
L<perl(1)>,
L<threads(3perl)>,
L<threads::shared(3perl)>,