utils_cmd_flush.c: Simplified / improved option parsing.

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

diff --git a/src/collectd-unixsock.pod b/src/collectd-unixsock.pod
index 16ba70f..b7c9878 100644 (file)
--- a/src/collectd-unixsock.pod
+++ b/src/collectd-unixsock.pod
@@ -58,7 +58,10 @@ 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 occurred. Each of the following lines contains the
-update time as an epoch value and the identifier, separated by a space.
+update time as an epoch value and the identifier, separated by a space. The
+update time is the time of the last value, as provided by the collecting
+instance and may be very different from the time the server consideres to be
+"now".
 
 Example:
   -> | LISTVAL
@@ -116,6 +119,78 @@ Example:
   -> | 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
+
+=item B<FLUSH> [B<timeout=>I<Timeout>] [B<plugin=>I<Plugin> [...]]
+
+Flushes all cached data older than I<Timeout> seconds. If no timeout has been
+specified, it defaults to -1 which causes all data to be flushed. B<timeout>
+may be specified multiple times - each occurrence applies to plugins listed
+afterwards.
+
+If specified, only specific plugins are flushed. Otherwise all plugins
+providing a flush callback are flushed.
+
+Example:
+  -> | FLUSH
+  <- | 0 Done
+
 =back
 
 =head2 Identifiers