src/collectdctl.pod

   1 =head1 NAME
   2
   3 collectdctl - Control interface for collectd
   4
   5 =head1 SYNOPSIS
   6
   7 collectdctl I<[options]> I<E<lt>commandE<gt>> I<[command options]>
   8
   9 =head1 DESCRIPTION
  10
  11 collectdctl provides a control interface for collectd, which may be used to
  12 interact with the daemon using the C<unixsock plugin>.
  13
  14 =head1 OPTIONS
  15
  16 collectdctl supports the following options:
  17
  18 =over 4
  19
  20 =item B<-s> I<socket>
  21
  22 Path to the UNIX socket opened by collectd's C<unixsock plugin>.
  23 Default: /var/run/collectd-unixsock
  24
  25 =item B<-h>
  26
  27 Display usage information and exit.
  28
  29 =back
  30
  31 =head1 AVAILABLE COMMANDS
  32
  33 The following commands are supported:
  34
  35 =over 4
  36
  37 =item B<getval> I<E<lt>identifierE<gt>>
  38
  39 Query the latest collected value identified by the specified
  40 I<E<lt>identifierE<gt>> (see below). The value-list associated with that
  41 data-set is returned as a list of key-value-pairs, each on its own line. Keys
  42 and values are separated by the equal sign (C<=>).
  43
  44 =item B<flush> [B<timeout=>I<E<lt>secondsE<gt>>] [B<plugin=>I<E<lt>nameE<gt>>]
  45 [B<identifier=>I<E<lt>idE<gt>>]
  46
  47 Flush the daemon. This is useful, e.E<nbsp>g., to make sure that the latest
  48 values have been written to the respective RRD file before graphing them or
  49 copying them to somewhere else.
  50
  51 The following options are supported by the flush command:
  52
  53 =over 4
  54
  55 =item B<timeout=>I<E<lt>secondsE<gt>>
  56
  57 Flush values older than the specified timeout (in seconds) only.
  58
  59 =item B<plugin=>I<E<lt>nameE<gt>>
  60
  61 Flush the specified plugin only. I.E<nbsp>e., data cached by the specified
  62 plugin is written to disk (or network or whatever), if the plugin supports
  63 that operation.
  64
  65 Example: B<rrdtool>.
  66
  67 =item B<identifier=>I<E<lt>idE<gt>>
  68
  69 If this option is present, only the data specified by the specified identifier
  70 (see below) will be flushed. Note that this option is not supported by all
  71 plugins (e.E<nbsp>g., the C<network> plugin does not support this).
  72
  73 =back
  74
  75 The B<plugin> and B<identifier> options may be specified more than once. In
  76 that case, all combinations of specified plugins and identifiers will be
  77 flushed only.
  78
  79 =item B<listval>
  80
  81 Returns a list of all values (by their identifier) available to the
  82 C<unixsock> plugin. Each value is printed on its own line. I.E<nbsp>e., this
  83 command returns a list of valid identifiers that may be used with the other
  84 commands.
  85
  86 =item B<putval> I<E<lt>identifierE<gt>> [B<interval=>I<E<lt>secondsE<gt>>]
  87 I<E<lt>value-list(s)E<gt>>
  88
  89 Submit one or more values (identified by I<E<lt>identifierE<gt>>, see below)
  90 to the daemon which will then dispatch them to the write plugins. B<interval>
  91 specifies the interval (in seconds) used to collect the values following that
  92 option. It defaults to the default of the running collectd instance receiving
  93 the data. Multiple I<E<lt>value-list(s)E<gt>> (see below) may be specified.
  94 Each of them will be submitted to the daemon. The values have to match the
  95 data-set definition specified by the type as given in the identifier (see
  96 L<types.db(5)> for details).
  97
  98 =item B<show> [I<E<lt>SelectionE<gt>>] [I<E<lt>AggregationE<gt>> I<E<lt>GroupingE<gt>>]
  99
 100 Show values or an aggregation of values. The I<Selection> selects which values
 101 to show. The selection consists of the five options B<host>, B<plugin>,
 102 B<plugin_instance>, B<type> and B<type_instance> which take a regular
 103 expression each. The regular expressions are passed on to the C<LISTVAL>
 104 command so they will behave exactly as documented in L<collectd-unixsock(5)>.
 105
 106 Example: Show CPU statistics only.
 107
 108     collectdctl show plugin="^cpu$" type="^cpu$"
 109
 110 If you're not interested in single values, but aggregations of values, you can
 111 use the I<Aggregation> and I<Grouping> options to get an overview over your
 112 system(s) and such. The two options to this effect are:
 113
 114 =over 4
 115
 116 =item B<aggregate=>I<aggr>[B<,>I<aggr>[...]]
 117
 118 List all the aggregation functions that shall be used to combine multiple
 119 values. Available aggregation functions are:
 120
 121 =over 4
 122
 123 =item B<count>
 124
 125 Number of non-NAN values. This value may be zero if all individual values are
 126 NAN.
 127
 128 =item B<min>
 129
 130 Minimum value.
 131
 132 =item B<max>
 133
 134 Maximum value.
 135
 136 =item B<avg>
 137
 138 Average of all values.
 139
 140 =item B<sum>
 141
 142 Sum of all values.
 143
 144 =item B<sdev>
 145
 146 Standard deviation of all non-NAN values. The standard deviation is NAN if
 147 there were no non-NAN values (B<count> reportsE<nbsp>0) and zero if there was
 148 exactly one non-NAN value.
 149
 150 =back
 151
 152 =item B<group=>I<field>[B<,>I<field>[...]]
 153
 154 Chose the fields of the I<identifier> you want to group values by. Valid
 155 I<fields> are B<host>, B<plugin>, B<plugin_instance>, B<type> and
 156 B<type_instance>. In 99E<nbsp>% of all cases, you want to make sure all values
 157 have the same I<type> -- either by using a construct like C<type='^foo$'>
 158 or by adding B<type> to the B<group> option (e.g. C<group=type>).
 159
 160 =back
 161
 162 Example: Print the minimum, average and maximum time spent in each CPU state
 163 for all your web servers:
 164
 165     collectdctl show host="^www[0-9]\\." plugin="^cpu$" type="^cpu$" aggregate=min,avg,max group=type_instance
 166
 167 =back
 168
 169 =head1 IDENTIFIERS
 170
 171 An identifier has the following format:
 172
 173 [I<hostname>/]I<plugin>[-I<plugin_instance>]/I<type>[-I<type_instance>]
 174
 175 Examples:
 176  somehost/cpu-0/cpu-idle
 177  uptime/uptime
 178  otherhost/memory/memory-used
 179
 180 Hostname defaults to the local (non-fully qualified) hostname if omitted. No
 181 error is returned if the specified identifier does not exist (this is a
 182 limitation in the C<libcollectdclient> library).
 183
 184 =head1 VALUE-LIST
 185
 186 A value list describes one data-set as handled by collectd. It is a colon
 187 (C<:>) separated list of the time and the values. Each value is either given
 188 as an integer if the data-type is a counter, or as a double if the data-type
 189 is a gauge value. A literal C<U> is interpreted as an undefined gauge value.
 190 The number of values and the data-types have to match the type specified in
 191 the identifier (see L<types.db(5)> for details). The time is specified as
 192 epoch (i.E<nbsp>e., standard UNIX time) or as a literal C<N> which will be
 193 interpreted as now.
 194
 195 =head1 EXAMPLES
 196
 197 =over 4
 198
 199 =item C<collectdctl flush plugin=rrdtool identifier=somehost/cpu-0/cpu-wait>
 200
 201 Flushes all CPU wait RRD values of the first CPU of the local host.
 202 I.E<nbsp>e., writes all pending RRD updates of that data-source to disk.
 203
 204 =item C<for ident in `collectdctl listval | grep users/users`; do
 205       collectdctl getval $ident;
 206   done>
 207
 208 Query the latest number of logged in users on all hosts known to the local
 209 collectd instance.
 210
 211 =back
 212
 213 =head1 SEE ALSO
 214
 215 L<collectd(1)>,
 216 L<collectd.conf(5)>,
 217 L<collectd-unixsock(5)>,
 218 L<types.db(5)>
 219
 220 =head1 AUTHOR
 221
 222 collectd has been written by Florian Forster E<lt>octo at collectd.orgE<gt>
 223 and many contributors (see `AUTHORS').
 224
 225 collectdctl has been written by
 226 Håkon J Dugstad Johnsen E<lt>hakon-dugstad.johnsenE<nbsp>atE<nbsp>telenor.comE<gt>,
 227 Sebastian Harl E<lt>sh at tokkee.orgE<gt> and
 228 Florian Forster E<lt>octo at collectd.orgE<gt>.
 229
 230 =cut