X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=src%2Fcollectd-perl.pod;h=4a01d1465b90a9e37986416f4a49b88649b0a5e8;hb=54ada5ddddb3692d8ec3493fbf4a5fd7aa39b5d1;hp=b327ef5698d89fb397bb2519f8b9fba981dcf799;hpb=4a5e97d6e317ee050b0a942e50159473a7d144dc;p=collectd.git

diff --git a/src/collectd-perl.pod b/src/collectd-perl.pod
index b327ef56..4a01d146 100644
--- 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
@@ -193,9 +221,10 @@ argument which simply tells B<plugin_register> what is being registered.)
 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 +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>)
@@ -245,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.
@@ -293,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
@@ -349,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
@@ -401,6 +454,22 @@ To register those functions with collectd:
 See the section "DATA TYPES" above for a complete documentation of the data
 types used by the read and write functions.
 
+=head1 NOTES
+
+=over 4
+
+=item
+
+Please feel free to send in new plugins to collectd's mailinglist at
+E<lt>collectdE<nbsp>atE<nbsp>verplant.orgE<gt> for review and, possibly,
+inclusion in the main distribution. In the latter case, we will take care of
+keeping the plugin up to date and adapting it to new versions of collectd.
+
+Before submitting your plugin, please take a look at
+L<http://collectd.org/dev-info.shtml>.
+
+=back
+
 =head1 CAVEATS
 
 =over 4
@@ -412,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
@@ -439,6 +509,7 @@ instead.
 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)>,