X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=src%2Fcollectd-exec.pod;h=7dc765417a0dc75a96442227e9aedc63b2db7c08;hb=bd21265ce20def847ceb4b0f90330f25a91522bf;hp=111f2d0029f3f1dfc07f0a078aef9e18e9802cb2;hpb=e77d585b9a7a107c1ae2dd9200f59259a4fa1411;p=collectd.git

diff --git a/src/collectd-exec.pod b/src/collectd-exec.pod
index 111f2d00..7dc76541 100644
--- a/src/collectd-exec.pod
+++ b/src/collectd-exec.pod
@@ -8,18 +8,21 @@ 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>.
 
+If you want/need better performance or more functionality you should take a
+long look at the C<perl plugin>, L<collectd-perl(5)>.
+
 =head1 DATA FORMAT
 
 The forked executable is expected to print values to C<STDOUT>. The expected
@@ -33,16 +36,54 @@ 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. I<plugin> and each I<instance>-part may be chosen freely as long
+as the tuple (plugin, plugin instance, type instance) uniquely identifies the
+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.
+
+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.
@@ -66,7 +107,11 @@ must have an UID that is non-zero.
 
 =head1 SEE ALSO
 
-L<collectd(1)>, L<collectd.conf(5)>, L<fork(2)>, L<exec(3)>
+L<collectd(1)>,
+L<collectd.conf(5)>,
+L<collectd-perl(5)>,
+L<collectd-unixsock(5)>,
+L<fork(2)>, L<exec(3)>
 
 =head1 AUTHOR