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>SelectionE<gt>>] [I<E<lt>AggregationE<gt>> I<E<lt>GroupingE<gt>>]
 101
 102 Show values or an aggregation of values. The I<Selection> selects which values
 103 to show. The selection consists of the five options B<host>, B<plugin>,
 104 B<plugin_instance>, B<type> and B<type_instance> which take a regular
 105 expression each. The regular expressions are passed on to the C<LISTVAL>
 106 command so they will behave exactly as documented in L<collectd-unixsock(5)>.
 107
 108 Example: Show CPU statistics only.
 109
 110     collectdctl show plugin="^cpu$" type="^cpu$"
 111
 112 If you're not interested in single values, but aggregations of values, you can
 113 use the I<Aggregation> and I<Grouping> options to get an overview over your
 114 system(s) and such. The two options to this effect are:
 115
 116 =over 4
 117
 118 =item B<aggregate=>I<aggr>[B<,>I<aggr>[...]]
 119
 120 List all the aggregation functions that shall be used to combine multiple
 121 values. Available aggregation functions are:
 122
 123 =over 4
 124
 125 =item B<count>
 126
 127 Number of non-NAN values. This value may be zero if all individual values are
 128 NAN.
 129
 130 =item B<min>
 131
 132 Minimum value.
 133
 134 =item B<max>
 135
 136 Maximum value.
 137
 138 =item B<avg>
 139
 140 Average of all values.
 141
 142 =item B<sum>
 143
 144 Sum of all values.
 145
 146 =item B<sdev>
 147
 148 Standard deviation of all non-NAN values. The standard deviation is NAN if
 149 there were no non-NAN values (B<count> reportsE<nbsp>0) and zero if there was
 150 exactly one non-NAN value.
 151
 152 =back
 153
 154 =item B<group=>I<field>[B<,>I<field>[...]]
 155
 156 Chose the fields of the I<identifier> you want to group values by. Valid
 157 I<fields> are B<host>, B<plugin>, B<plugin_instance>, B<type> and
 158 B<type_instance>. In 99E<nbsp>% of all cases, you want to make sure all values
 159 have the same I<type> -- either by using a construct like C<type='^foo$'>
 160 or by adding B<type> to the B<group> option (e.g. C<group=type>).
 161
 162 =back
 163
 164 Example: Print the minimum, average and maximum time spent in each CPU state
 165 for all your web servers:
 166
 167     collectdctl show host="^www[0-9]\\." plugin="^cpu$" type="^cpu$" aggregate=min,avg,max group=type_instance
 168
 169 =back
 170
 171 =head1 IDENTIFIERS
 172
 173 An identifier has the following format:
 174
 175 [I<hostname>/]I<plugin>[-I<plugin_instance>]/I<type>[-I<type_instance>]
 176
 177 Examples:
 178  somehost/cpu-0/cpu-idle
 179  uptime/uptime
 180  otherhost/memory/memory-used
 181
 182 Hostname defaults to the local (non-fully qualified) hostname if omitted. No
 183 error is returned if the specified identifier does not exist (this is a
 184 limitation in the C<libcollectdclient> library).
 185
 186 =head1 VALUE-LIST
 187
 188 A value list describes one data-set as handled by collectd. It is a colon
 189 (C<:>) separated list of the time and the values. Each value is either given
 190 as an integer if the data-type is a counter, or as a double if the data-type
 191 is a gauge value. A literal C<U> is interpreted as an undefined gauge value.
 192 The number of values and the data-types have to match the type specified in
 193 the identifier (see L<types.db(5)> for details). The time is specified as
 194 epoch (i.E<nbsp>e., standard UNIX time) or as a literal C<N> which will be
 195 interpreted as now.
 196
 197 =head1 EXAMPLES
 198
 199 =over 4
 200
 201 =item C<collectdctl flush plugin=rrdtool identifier=somehost/cpu-0/cpu-wait>
 202
 203 Flushes all CPU wait RRD values of the first CPU of the local host.
 204 I.E<nbsp>e., writes all pending RRD updates of that data-source to disk.
 205
 206 =item C<for ident in `collectdctl listval | grep users/users`; do
 207       collectdctl getval $ident;
 208   done>
 209
 210 Query the latest number of logged in users on all hosts known to the local
 211 collectd instance.
 212
 213 =back
 214
 215 =head1 SEE ALSO
 216
 217 L<collectd(1)>,
 218 L<collectd.conf(5)>,
 219 L<collectd-unixsock(5)>,
 220 L<types.db(5)>
 221
 222 =head1 AUTHOR
 223
 224 collectd has been written by Florian Forster E<lt>octo at collectd.orgE<gt>
 225 and many contributors (see `AUTHORS').
 226
 227 collectdctl has been written by
 228 Håkon J Dugstad Johnsen E<lt>hakon-dugstad.johnsenE<nbsp>atE<nbsp>telenor.comE<gt>,
 229 Sebastian Harl E<lt>sh at tokkee.orgE<gt> and
 230 Florian Forster E<lt>octo at collectd.orgE<gt>.
 231
 232 =cut