[collectd] [PATCH 3/3] collectd-perl(5): Added documentation for the notification support.
sh at tokkee.org
Mon Jan 28 12:23:55 CET 2008
Some minor errors have been fixed as well and the ChangeLog has been updated.
Signed-off-by: Sebastian Harl <sh at tokkee.org>
ChangeLog | 8 +++---
src/collectd-perl.pod | 65 ++++++++++++++++++++++++++++++++++++++++++++----
2 files changed, 63 insertions(+), 10 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 5c6f22d..f8c40e2 100644
@@ -1,6 +1,6 @@
yyyy-mm-dd, Version 4.3.0
* collectd: Notifications have been added to the daemon. Notifications
- are status messages that may be associated with an data instance.
+ are status messages that may be associated with a data instance.
* collectd: Threshold checking has been added to the daemon. This
means that you can configure threshold values for each data
instance. If this threshold is exceeded a notification will be
@@ -23,9 +23,9 @@ yyyy-mm-dd, Version 4.3.0
domain name lookups in this plugin.
* perl plugin: Many internal changes added support for handling multiple
threads making the plugin reasonably usable inside collectd. The API has
- been extended to export global variables to Perl plugins; callbacks now
- have to be identified by name rather than a pointer to a subroutine. The
- plugin is no longer experimental.
+ been extended to support notifications and export global variables to
+ Perl plugins; callbacks now have to be identified by name rather than a
+ pointer to a subroutine. The plugin is no longer experimental.
* uuid plugin: The new UUID plugin sets the hostname to an unique
identifier for this host. This is meant for setups where each client
may migrate to another physical host, possibly going through one or
diff --git a/src/collectd-perl.pod b/src/collectd-perl.pod
index 194aa54..4a01d14 100644
@@ -97,6 +97,15 @@ once for each call to B<plugin_dispatch_values>.
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
@@ -104,8 +113,9 @@ be used to clean up the plugin (e.g. close sockets, ...).
-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
@@ -132,7 +142,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,
min => value || undef,
max => value || undef
@@ -148,12 +158,28 @@ layout looks like this:
values => [123, 0.5],
time => time (),
- host => 'localhost',
+ host => $hostname_g,
plugin => 'myplugin',
plugin_instance => '',
type_instance => ''
+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 => ''
@@ -179,6 +205,8 @@ I<type> can be one of:
@@ -232,6 +260,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.
+The only argument passed is I<notification>. See above for the layout of this
=item B<plugin_unregister> (I<type>, I<plugin>)
@@ -246,6 +279,11 @@ 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_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.
@@ -294,6 +332,8 @@ available (B<:all> will export all of them):
=item B<plugin_dispatch_values> ()
+=item B<plugin_dispatch_notification> ()
=item B<plugin_log> ()
@@ -350,6 +390,18 @@ available (B<:all> will export all of them):
@@ -429,8 +481,9 @@ plugin will be mapped to a Perl interpreter thread (see L<threads(3perl)>).
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.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Size: 189 bytes
Desc: Digital signature
Url : http://mailman.verplant.org/pipermail/collectd/attachments/20080128/c7d503b8/attachment.pgp
More information about the collectd