src/collectd-exec.pod

   1 =head1 NAME
   2
   3 collectd-exec - Documentation of collectd's C<exec plugin>
   4
   5 =head1 SYNOPSIS
   6
   7   # See collectd.conf(5)
   8   LoadPlugin exec
   9   # ...
  10   <Plugin exec>
  11     Exec myuser myprog
  12     Exec otheruser /path/to/another/binary
  13   </Plugin>
  14
  15 =head1 DESCRIPTION
  16
  17 The C<exec plugin> forks of an executable and reads back values that it writes
  18 to C<STDOUT>. The executable is forked in a fassion similar to L<init>: It is
  19 forked once and not again until it exits. If it exited, it will be forked again
  20 after at most I<Interval> seconds. It is perfectly legal for the executable to
  21 run for a long time and continuously write values to C<STDOUT>.
  22
  23 If you want/need better performance or more functionality you should take a
  24 long look at the C<perl plugin>, L<collectd-perl(5)>.
  25
  26 =head1 DATA FORMAT
  27
  28 The forked executable is expected to print values to C<STDOUT>. The expected
  29 format is as follows:
  30
  31 =over 4
  32
  33 =item
  34
  35 Each line beginning with a C<#> (hash mark) is ignored.
  36
  37 =item
  38
  39 Any other line must be of the form C<I<type>,I<type-instance>,I<value>>, where
  40 I<type> is either B<counter> or B<gauge>, I<type-instance> may not contain
  41 C<,> (comma), C</> (slash) and C<\0> (null byte) and I<value> is either an
  42 integer (if I<type> is B<counter>) or a floating-point number (if I<type> is
  43 B<gauge>).
  44
  45 =back
  46
  47 The values are always considered to be "fresh", i.E<nbsp>e. the time is set to
  48 "now".
  49
  50 When collectd exits it sends a B<SIGTERM> to all still running
  51 child-processes upon which they have to quit.
  52
  53 =head1 CAVEATS
  54
  55 =over 4
  56
  57 =item
  58
  59 If the executable only writes one value and then exits I will be executed every
  60 I<Interval> seconds. If I<Interval> is short (the default is 10 seconds) this
  61 may result in serious system load.
  62
  63 =item
  64
  65 The user, the binary is executed as, may not have root privileges, i.E<nbsp>e.
  66 must have an UID that is non-zero.
  67
  68 =back
  69
  70 =head1 SEE ALSO
  71
  72 L<collectd(1)>,
  73 L<collectd.conf(5)>,
  74 L<collectd-perl(5)>,
  75 L<fork(2)>, L<exec(3)>
  76
  77 =head1 AUTHOR
  78
  79 Florian Forster E<lt>octo@verplant.orgE<gt>
  80
  81 =cut