Merge branch 'collectd-4.2' into collectd-4.3

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

diff --git a/src/collectd-unixsock.pod b/src/collectd-unixsock.pod
index 7a82541..3ef2438 100644 (file)
--- a/src/collectd-unixsock.pod
+++ b/src/collectd-unixsock.pod
@@ -52,13 +52,13 @@ Example:
 
 =item B<LISTVAL>
 
 
 =item B<LISTVAL>
 

-Returnes a list of the values available in the value cache together with the
+Returns a list of the values available in the value cache together with the

 time of the last update, so that querying applications can issue a B<GETVAL>
 command for the values that have changed.
 
 The first line's status number is the number of identifiers returned or less
 time of the last update, so that querying applications can issue a B<GETVAL>
 command for the values that have changed.
 
 The first line's status number is the number of identifiers returned or less

-than zero if an error occured. Each of the following lines containes the
-update time as an epoch value and the identifier, seperated by a space.
+than zero if an error occurred. Each of the following lines contains the
+update time as an epoch value and the identifier, separated by a space.

 
 Example:
   -> | LISTVAL
 
 Example:
   -> | LISTVAL


@@ -83,12 +83,12 @@ plugin within collectd. I<type> identifies the type and number of values
 (i.E<nbsp>e. data-set) passed to collectd. A large list of predefined
 data-sets is available in the B<types.db> file.
 
 (i.E<nbsp>e. data-set) passed to collectd. A large list of predefined
 data-sets is available in the B<types.db> file.
 

-The I<OptionList> is an optional list of I<Options>, where each option if a
+The I<OptionList> is an optional list of I<Options>, where each option is a

 key-value-pair. A list of currently understood options can be found below, all
 other options will be ignored.
 
 key-value-pair. A list of currently understood options can be found below, all
 other options will be ignored.
 

-I<Valuelist> is a colon-seperated list of the time and the values, each either
-an integer if the data-source is a counter, of a double if the data-source if
+I<Valuelist> is a colon-separated list of the time and the values, each either
+an integer if the data-source is a counter, or a double if the data-source is

 of type "gauge". You can submit an undefined gauge-value by using B<U>. When
 submitting B<U> to a counter the behavior is undefined. The time is given as
 epoch (i.E<nbsp>e. standard UNIX time).
 of type "gauge". You can submit an undefined gauge-value by using B<U>. When
 submitting B<U> to a counter the behavior is undefined. The time is given as
 epoch (i.E<nbsp>e. standard UNIX time).


@@ -116,6 +116,64 @@ Example:
   -> | PUTVAL testhost/interface/if_octets-test0 interval=10 1179574444:123:456
   <- | 0 Success
 
   -> | PUTVAL testhost/interface/if_octets-test0 interval=10 1179574444:123:456
   <- | 0 Success
 

+=item B<PUTNOTIF> [I<OptionList>] B<message=>I<Message>
+
+Submits a notification to the daemon which will then dispatch it to all plugins
+which have registered for receiving notifications. 
+
+The B<PUTNOTIF> if followed by a list of options which further describe the
+notification. The B<message> option is special in that it will consume the rest
+of the line as its value. The B<message>, B<severity>, and B<time> options are
+mandatory.
+
+Valid options are:
+
+=over 4
+
+=item B<message=>I<Message> (B<REQUIRED>)
+
+Sets the message of the notification. This is the message that will be made
+accessible to the user, so it should contain some useful information. This
+option must be the last option because the rest of the line will be its value,
+even if there are spaces and equal-signs following it! This option is
+mandatory.
+
+=item B<severity=failure>|B<warning>|B<okay> (B<REQUIRED>)
+
+Sets the severity of the notification. This option is mandatory.
+
+=item B<time=>I<Time> (B<REQUIRED>)
+
+Sets the time of the notification. The time is given as "epoch", i.E<nbsp>e. as
+seconds since January 1st, 1970, 00:00:00. This option is mandatory.
+
+=item B<host=>I<Hostname>
+
+=item B<plugin=>I<Plugin>
+
+=item B<plugin_instance=>I<Plugin-Instance>
+
+=item B<type=>I<Type>
+
+=item B<type_instance=>I<Type-Instance>
+
+These "associative" options establish a relation between this notification and
+collected performance data. This connection is purely informal, i.E<nbsp>e. the
+daemon itself doesn't do anything with this information. However, websites or
+GUIs may use this information to place notifications near the affected graph or
+table. All the options are optional, but B<plugin_instance> without B<plugin>
+or B<type_instance> without B<type> doesn't make much sense and should be
+avoided.
+
+Please note that this is the same format as used in the B<exec plugin>, see
+L<collectd-exec(5)>.
+
+=back
+
+Example:
+  -> | PUTNOTIF type=temperature severity=warning time=1201094702 message=The roof is on fire!
+  <- | 0 Success
+

 =back
 
 =head2 Identifiers
 =back
 
 =head2 Identifiers


@@ -149,10 +207,12 @@ value on failure and never return zero.
 
 =head1 ABSTRACTION LAYER
 
 
 =head1 ABSTRACTION LAYER
 

-Shipped with the sourcecode comes the Perl-Module L<Collectd::Unixsock> which
+B<collectd> ships the Perl-Module L<Collectd::Unixsock> which

 provides an abstraction layer over the actual socket connection. It can be
 provides an abstraction layer over the actual socket connection. It can be

-found in the directory F<contrib/PerlLib>. If you want to use Perl to
-communicate with the daemon, you're encouraged to use and expand this module.
+found in the directory F<bindings/perl/> in the source distribution or
+(usually) somewhere near F</usr/share/perl5/> if you're using a package. If
+you want to use Perl to communicate with the daemon, you're encouraged to use
+and expand this module.

 
 =head1 SEE ALSO
 
 
 =head1 SEE ALSO