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:mygroup" "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 fashion 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 Other lines must consist of an I<Identifier>, an optional I<Option-List> and a
  40 I<Value-List>, separated by a spaces. A description of these two parts follows:
  41
  42 An I<Identifier> is of the form
  43 C<I<host>B</>I<plugin>B<->I<instance>B</>I<type>B<->I<instance>> with both
  44 I<instance>-parts being optional. If they're omitted the hyphen must be
  45 omitted, too. I<plugin> and each I<instance>-part may be chosen freely as long
  46 as the tuple (plugin, plugin instance, type instance) uniquely identifies the
  47 plugin within collectd. I<type> identifies the type and number of values
  48 (i.E<nbsp>e. data-set) passed to collectd. A large list of predefined
  49 data-sets is available in the B<types.db> file.
  50
  51 The I<OptionList> is an optional list of I<Options>, where each option if a
  52 key-value-pair. A list of currently understood options can be found below, all
  53 other options will be ignored.
  54
  55 I<Valuelist> is a colon-separated list of the time and the values, each either
  56 an integer if the data-source is a counter, of a double if the data-source if
  57 of type "gauge". You can submit an undefined gauge-value by using B<U>. When
  58 submitting B<U> to a counter the behavior is undefined. The time is given as
  59 epoch (i.E<nbsp>e. standard UNIX time).
  60
  61 You can mix options and values, but the order is important: Options only
  62 effect following values, so specifying an option as last field is allowed, but
  63 useless. Also, an option applies to B<all> following values, so you don't need
  64 to re-set an option over and over again.
  65
  66 The currently defined B<Options> are:
  67
  68 =over 4
  69
  70 =item B<interval=>I<seconds>
  71
  72 Gives the interval in which the data identified by I<Identifier> is being
  73 collected.
  74
  75 =back
  76
  77 Please note that this is the same format as used in the B<unixsock plugin>, see
  78 L<collectd-unixsock(5)>. There's also a bit more information on identifiers in
  79 case you're confused.
  80
  81 Since examples usually let one understand a lot better, here are some:
  82
  83   leeloo/cpu-0/cpu-idle N:2299366
  84   alice/interface/if_octets-eth0 interval=10 1180647081:421465:479194
  85
  86 =back
  87
  88 When collectd exits it sends a B<SIGTERM> to all still running
  89 child-processes upon which they have to quit.
  90
  91 =head1 CAVEATS
  92
  93 =over 4
  94
  95 =item
  96
  97 If the executable only writes one value and then exits I will be executed every
  98 I<Interval> seconds. If I<Interval> is short (the default is 10 seconds) this
  99 may result in serious system load.
 100
 101 =item
 102
 103 The user, the binary is executed as, may not have root privileges, i.E<nbsp>e.
 104 must have an UID that is non-zero.
 105
 106 =back
 107
 108 =head1 SEE ALSO
 109
 110 L<collectd(1)>,
 111 L<collectd.conf(5)>,
 112 L<collectd-perl(5)>,
 113 L<collectd-unixsock(5)>,
 114 L<fork(2)>, L<exec(3)>
 115
 116 =head1 AUTHOR
 117
 118 Florian Forster E<lt>octo@verplant.orgE<gt>
 119
 120 =cut