Merge branch 'pull/collectd-4.1' into collectd-4.1

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

diff --git a/src/collectd-exec.pod b/src/collectd-exec.pod
index cb6069c..27d0eed 100644 (file)
--- a/src/collectd-exec.pod
+++ b/src/collectd-exec.pod
@@ -8,14 +8,14 @@ collectd-exec - Documentation of collectd's C<exec plugin>
   LoadPlugin exec
   # ...
   <Plugin exec>
-    Exec myuser myprog
-    Exec otheruser /path/to/another/binary
+    Exec "myuser:mygroup" "myprog"
+    Exec "otheruser" "/path/to/another/binary"
   </Plugin>
 
 =head1 DESCRIPTION
 
 The C<exec plugin> forks of an executable and reads back values that it writes
-to C<STDOUT>. The executable is forked in a fassion similar to L<init>: It is
+to C<STDOUT>. The executable is forked in a fashion similar to L<init>: It is
 forked once and not again until it exits. If it exited, it will be forked again
 after at most I<Interval> seconds. It is perfectly legal for the executable to
 run for a long time and continuously write values to C<STDOUT>.
@@ -36,16 +36,50 @@ Each line beginning with a C<#> (hash mark) is ignored.
 
 =item
 
-Any other line must be of the form C<I<type>,I<type-instance>,I<value>>, where
-I<type> is either B<counter> or B<gauge>, I<type-instance> may not contain
-C<,> (comma), C</> (slash) and C<\0> (null byte) and I<value> is either an
-integer (if I<type> is B<counter>) or a floating-point number (if I<type> is
-B<gauge>).
+Other lines must consist of an I<Identifier>, an optional I<Option-List> and a
+I<Value-List>, separated by a spaces. A description of these two parts follows:
+
+An I<Identifier> is of the form
+C<I<host>B</>I<plugin>B<->I<instance>B</>I<type>B<->I<instance>> with both
+I<instance>-parts being optional. If they're omitted the hyphen must be
+omitted, too.
+
+The I<OptionList> is an optional list of I<Options>, where each option if a
+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
+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).
+
+You can mix options and values, but the order is important: Options only
+effect following values, so specifying an option as last field is allowed, but
+useless. Also, an option applies to B<all> following values, so you don't need
+to re-set an option over and over again.
+
+The currently defined B<Options> are:
+
+=over 4
+
+=item B<interval=>I<seconds>
+
+Gives the interval in which the data identified by I<Identifier> is being
+collected.
 
 =back
 
-The values are always considered to be "fresh", i.E<nbsp>e. the time is set to
-"now".
+Please note that this is the same format as used in the B<unixsock plugin>, see
+L<collectd-unixsock(5)>. There's also a bit more information on identifiers in
+case you're confused.
+
+Since examples usually let one understand a lot better, here are some:
+
+  leeloo/cpu-0/cpu-idle N:2299366
+  alice/interface/if_octets-eth0 interval=10 1180647081:421465:479194
+
+=back
 
 When collectd exits it sends a B<SIGTERM> to all still running
 child-processes upon which they have to quit.
@@ -72,6 +106,7 @@ must have an UID that is non-zero.
 L<collectd(1)>,
 L<collectd.conf(5)>,
 L<collectd-perl(5)>,
+L<collectd-unixsock(5)>,
 L<fork(2)>, L<exec(3)>
 
 =head1 AUTHOR