src/collectdctl.pod

   1 =encoding UTF-8
   2
   3 =head1 NAME
   4
   5 collectdctl - Control interface for collectd
   6
   7 =head1 SYNOPSIS
   8
   9 collectdctl I<[options]> I<E<lt>commandE<gt>> I<[command options]>
  10
  11 =head1 DESCRIPTION
  12
  13 collectdctl provides a control interface for collectd, which may be used to
  14 interact with the daemon using the C<unixsock plugin>.
  15
  16 =head1 OPTIONS
  17
  18 collectdctl supports the following options:
  19
  20 =over 4
  21
  22 =item B<-s> I<socket>
  23
  24 Path to the UNIX socket opened by collectd's C<unixsock plugin>.
  25 Default: /var/run/collectd-unixsock
  26
  27 =item B<-h>
  28
  29 Display usage information and exit.
  30
  31 =back
  32
  33 =head1 AVAILABLE COMMANDS
  34
  35 The following commands are supported:
  36
  37 =over 4
  38
  39 =item B<getval> I<E<lt>identifierE<gt>>
  40
  41 Query the latest collected value identified by the specified
  42 I<E<lt>identifierE<gt>> (see below). The value-list associated with that
  43 data-set is returned as a list of key-value-pairs, each on its own line. Keys
  44 and values are separated by the equal sign (C<=>).
  45
  46 =item B<flush> [B<timeout=>I<E<lt>secondsE<gt>>] [B<plugin=>I<E<lt>nameE<gt>>]
  47 [B<identifier=>I<E<lt>idE<gt>>]
  48
  49 Flush the daemon. This is useful, e.E<nbsp>g., to make sure that the latest
  50 values have been written to the respective RRD file before graphing them or
  51 copying them to somewhere else.
  52
  53 The following options are supported by the flush command:
  54
  55 =over 4
  56
  57 =item B<timeout=>I<E<lt>secondsE<gt>>
  58
  59 Flush values older than the specified timeout (in seconds) only.
  60
  61 =item B<plugin=>I<E<lt>nameE<gt>>
  62
  63 Flush the specified plugin only. I.E<nbsp>e., data cached by the specified
  64 plugin is written to disk (or network or whatever), if the plugin supports
  65 that operation.
  66
  67 Example: B<rrdtool>.
  68
  69 =item B<identifier=>I<E<lt>idE<gt>>
  70
  71 If this option is present, only the data specified by the specified identifier
  72 (see below) will be flushed. Note that this option is not supported by all
  73 plugins (e.E<nbsp>g., the C<network> plugin does not support this).
  74
  75 =back
  76
  77 The B<plugin> and B<identifier> options may be specified more than once. In
  78 that case, all combinations of specified plugins and identifiers will be
  79 flushed only.
  80
  81 =item B<listval>
  82
  83 Returns a list of all values (by their identifier) available to the
  84 C<unixsock> plugin. Each value is printed on its own line. I.E<nbsp>e., this
  85 command returns a list of valid identifiers that may be used with the other
  86 commands.
  87
  88 =item B<putval> I<E<lt>identifierE<gt>> [B<interval=>I<E<lt>secondsE<gt>>]
  89 I<E<lt>value-list(s)E<gt>>
  90
  91 Submit one or more values (identified by I<E<lt>identifierE<gt>>, see below)
  92 to the daemon which will then dispatch them to the write plugins. B<interval>
  93 specifies the interval (in seconds) used to collect the values following that
  94 option. It defaults to the default of the running collectd instance receiving
  95 the data. Multiple I<E<lt>value-list(s)E<gt>> (see below) may be specified.
  96 Each of them will be submitted to the daemon. The values have to match the
  97 data-set definition specified by the type as given in the identifier (see
  98 L<types.db(5)> for details).
  99
 100 =back
 101
 102 =head1 IDENTIFIERS
 103
 104 An identifier has the following format:
 105
 106 [I<hostname>/]I<plugin>[-I<plugin_instance>]/I<type>[-I<type_instance>]
 107
 108 Examples:
 109  somehost/cpu-0/cpu-idle
 110  uptime/uptime
 111  otherhost/memory/memory-used
 112
 113 Hostname defaults to the local (non-fully qualified) hostname if omitted. No
 114 error is returned if the specified identifier does not exist (this is a
 115 limitation in the C<libcollectdclient> library).
 116
 117 =head1 VALUE-LIST
 118
 119 A value list describes one data-set as handled by collectd. It is a colon
 120 (C<:>) separated list of the time and the values. Each value is either given
 121 as an integer if the data-type is a counter, or as a double if the data-type
 122 is a gauge value. A literal C<U> is interpreted as an undefined gauge value.
 123 The number of values and the data-types have to match the type specified in
 124 the identifier (see L<types.db(5)> for details). The time is specified as
 125 epoch (i.E<nbsp>e., standard UNIX time) or as a literal C<N> which will be
 126 interpreted as now.
 127
 128 =head1 EXAMPLES
 129
 130 =over 4
 131
 132 =item C<collectdctl flush plugin=rrdtool identifier=somehost/cpu-0/cpu-wait>
 133
 134 Flushes all CPU wait RRD values of the first CPU of the local host.
 135 I.E<nbsp>e., writes all pending RRD updates of that data-source to disk.
 136
 137 =item C<for ident in `collectdctl listval | grep users/users`; do
 138       collectdctl getval $ident;
 139   done>
 140
 141 Query the latest number of logged in users on all hosts known to the local
 142 collectd instance.
 143
 144 =back
 145
 146 =head1 SEE ALSO
 147
 148 L<collectd(1)>,
 149 L<collectd.conf(5)>,
 150 L<collectd-unixsock(5)>,
 151 L<types.db(5)>
 152
 153 =head1 AUTHOR
 154
 155 collectd has been written by Florian Forster E<lt>octo at verplant.orgE<gt>
 156 and many contributors (see `AUTHORS').
 157
 158 collectdctl has been written by
 159 Håkon J Dugstad Johnsen E<lt>hakon-dugstad.johnsenE<nbsp>atE<nbsp>telenor.comE<gt>
 160 and Sebastian Harl E<lt>sh at tokkee.orgE<gt>.
 161
 162 =cut