contrib/exec-nagios.px: Added a Perl script which handles Nagios plugins.

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

diff --git a/src/collectd-perl.pod b/src/collectd-perl.pod
index 194aa54..4a01d14 100644 (file)
--- a/src/collectd-perl.pod
+++ b/src/collectd-perl.pod
@@ -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, ...).
 
 =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
@@ -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   => ''
   }
 
+=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   => ''
+  }
+
 =back
 
 =head1 METHODS
@@ -179,6 +205,8 @@ I<type> can be one of:
 
 =item TYPE_LOG
 
+=item TYPE_NOTIF
+
 =item TYPE_SHUTDOWN
 
 =item TYPE_DATASET
@@ -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.
 
+=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>)
@@ -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> ()
 
 =back
@@ -350,6 +390,18 @@ available (B<:all> will export all of them):
 
 =back
 
+=item B<:notif>
+
+=over 4
+
+=item B<NOTIF_FAILURE>
+
+=item B<NOTIF_WARNING>
+
+=item B<NOTIF_OKAY>
+
+=back
+
 =item B<:globals>
 
 =over 4
@@ -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.
 
 =item