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 =item B<show> I<E<lt>selectorE<gt>> I<E<lt>aggregationE<gt>> [I<E<lt>aggregationE<gt>> ...]
 101
 102 Show values or an aggregation of values. The I<selector> selects which values
 103 to show. It is basically an I<identifier> with special meaning for C<+> and
 104 C<*>. If a hostname, plugin, type or one of the two instances is C<+> or C<*>,
 105 any string will match the selector. The difference between the two is that all
 106 identifiers with the same substitution for C<+> are grouped and aggregated by
 107 the specified aggregation function(s). For example, the selector
 108
 109   +/cpu-*/cpu-+
 110
 111 will return the CPU states of each host, aggregated over all CPUs of each
 112 system. Please see L</"IDENTIFIERS"> for a description of identifiers.
 113
 114 The I<aggregation> setting defines how multiple values are combined into one
 115 value. Valid values are:
 116
 117 =over 4
 118
 119 =item B<count>
 120
 121 Number of non-NAN values. This value may be zero if all individual values are
 122 NAN.
 123
 124 =item B<min>
 125
 126 Minimum value.
 127
 128 =item B<max>
 129
 130 Maximum value.
 131
 132 =item B<avg>
 133
 134 Average of all values.
 135
 136 =item B<sum>
 137
 138 Sum of all values.
 139
 140 =item B<sdev>
 141
 142 Standard deviation of all non-NAN values. The standard deviation is NAN if
 143 there were no non-NAN values (B<count> reportsE<nbsp>0) and zero if there was
 144 exactly one non-NAN value.
 145
 146 =back
 147
 148 =back
 149
 150 =head1 IDENTIFIERS
 151
 152 An identifier has the following format:
 153
 154 [I<hostname>/]I<plugin>[-I<plugin_instance>]/I<type>[-I<type_instance>]
 155
 156 Examples:
 157  somehost/cpu-0/cpu-idle
 158  uptime/uptime
 159  otherhost/memory/memory-used
 160
 161 Hostname defaults to the local (non-fully qualified) hostname if omitted. No
 162 error is returned if the specified identifier does not exist (this is a
 163 limitation in the C<libcollectdclient> library).
 164
 165 =head1 VALUE-LIST
 166
 167 A value list describes one data-set as handled by collectd. It is a colon
 168 (C<:>) separated list of the time and the values. Each value is either given
 169 as an integer if the data-type is a counter, or as a double if the data-type
 170 is a gauge value. A literal C<U> is interpreted as an undefined gauge value.
 171 The number of values and the data-types have to match the type specified in
 172 the identifier (see L<types.db(5)> for details). The time is specified as
 173 epoch (i.E<nbsp>e., standard UNIX time) or as a literal C<N> which will be
 174 interpreted as now.
 175
 176 =head1 EXAMPLES
 177
 178 =over 4
 179
 180 =item C<collectdctl flush plugin=rrdtool identifier=somehost/cpu-0/cpu-wait>
 181
 182 Flushes all CPU wait RRD values of the first CPU of the local host.
 183 I.E<nbsp>e., writes all pending RRD updates of that data-source to disk.
 184
 185 =item C<for ident in `collectdctl listval | grep users/users`; do
 186       collectdctl getval $ident;
 187   done>
 188
 189 Query the latest number of logged in users on all hosts known to the local
 190 collectd instance.
 191
 192 =back
 193
 194 =head1 SEE ALSO
 195
 196 L<collectd(1)>,
 197 L<collectd.conf(5)>,
 198 L<collectd-unixsock(5)>,
 199 L<types.db(5)>
 200
 201 =head1 AUTHOR
 202
 203 collectd has been written by Florian Forster E<lt>octo at verplant.orgE<gt>
 204 and many contributors (see `AUTHORS').
 205
 206 collectdctl has been written by
 207 Håkon J Dugstad Johnsen E<lt>hakon-dugstad.johnsenE<nbsp>atE<nbsp>telenor.comE<gt>
 208 and Sebastian Harl E<lt>sh at tokkee.orgE<gt>.
 209
 210 =cut