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