src/collectd.pod

   1 =head1 NAME
   2
   3 collectd - System statistics collection daemon
   4
   5 =head1 SYNOPSIS
   6
   7 collectd I<[options]>
   8
   9 =head1 DESCRIPTION
  10
  11 collectd is a daemon that collects various system statistics periodically and
  12 stores them into RRD-files. Which data is collected depends on compile-time
  13 settings. The following features may be available:
  14
  15 =over 4
  16
  17 =item
  18
  19 CPU utilization (I<cpu>)
  20
  21 =item
  22
  23 Disk and partition usage/throughput (I<disk>)
  24
  25 =item
  26
  27 Harddisk temperatures (I<hddtemp>)
  28
  29 =item
  30
  31 System load averages (I<load>)
  32
  33 =item
  34
  35 Memory usage (I<memory>)
  36
  37 =item
  38
  39 NFS utilization (I<nfs>, Linux only)
  40
  41 =item
  42
  43 Network latency (I<ping>)
  44
  45 =item
  46
  47 Number of processes (I<processes>, Linux only)
  48
  49 =item
  50
  51 lm_sensors information (I<sensors>, Linux only)
  52
  53 =item
  54
  55 Serial port traffic (I<serial>, Linux only)
  56
  57 =item
  58
  59 Swap usage (I<swap>)
  60
  61 =item
  62
  63 Tape drive usage (I<tape>, Solaris only)
  64
  65 =item
  66
  67 Network traffic (I<traffic>)
  68
  69 =back
  70
  71 =head1 OPTIONS
  72
  73 =over 4
  74
  75 =item B<-c>
  76
  77 Start in client (transmitter) mode. Data will be sent to the multicast group.
  78 See L<"MODES">.
  79
  80 =item B<-d> I<E<lt>directoryE<gt>>
  81
  82 Sets the directory collectd should work in. All F<.rrd>-files are created in
  83 this directory. Per default this is F</var/lib/collectd/>.
  84
  85 =item B<-f>
  86
  87 Don't fork to the background. I<collectd> will also B<not> close standard file
  88 descriptors, detach from the session nor write a pid file. This is mainly
  89 thought for 'supervisioning' init replacements such as I<runit>.
  90
  91 =item B<-h>
  92
  93 Output usage information and exit.
  94
  95 =item B<-l>
  96
  97 Start in local mode. This is the default. No data will be sent or read to/from
  98 the network. Information will be read and written by the same process. See
  99 L<"MODES">.
 100
 101 =item B<-p> I<E<lt>hostE<gt>>
 102
 103 Sets the host to ping periodically. This option may be given more than once to
 104 ping multiple hosts. If this option is not given at least once no host will be
 105 pinged.
 106
 107 =item B<-s>
 108
 109 Start in server (receiver) mode. Data sent to the multicast group will be read
 110 and stored in RRD files. See L<"MODES">.
 111
 112 =back
 113
 114 =head1 RRD FILES
 115
 116 The RRD files are created automatically with the following RRAs:
 117
 118   RRA:AVERAGE:0.2:6:1500
 119   RRA:AVERAGE:0.1:180:1680
 120   RRA:AVERAGE:0.1:2160:1520
 121   RRA:MIN:0.2:6:1500
 122   RRA:MIN:0.1:180:1680
 123   RRA:MIN:0.1:2160:1520
 124   RRA:MAX:0.2:6:1500
 125   RRA:MAX:0.1:180:1680
 126   RRA:MAX:0.1:2160:1520
 127
 128 Since collectd uses a 10 second I<step> the RRAs contain the following
 129 timespans:
 130
 131   Resolution | Data points |  Timespan
 132   -----------+-------------+----------
 133   60 seconds |        1500 |  25 hours
 134   30 minutes |        1680 |  35 days
 135    6 hours   |        1520 | 380 days
 136
 137 The DS'es depend on the module creating the RRD files:
 138
 139 =over 4
 140
 141 =item CPU (F<cpu-I<E<lt>numE<gt>>.rrd>)
 142
 143   DS:user:COUNTER:25:0:100
 144   DS:nice:COUNTER:25:0:100
 145   DS:syst:COUNTER:25:0:100
 146   DS:idle:COUNTER:25:0:100
 147   DS:wait:COUNTER:25:0:100
 148
 149 =item Diskstats (F<disk-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
 150
 151   DS:rcount:COUNTER:25:0:
 152   DS:rmerged:COUNTER:25:0:U
 153   DS:rbytes:COUNTER:25:0:U
 154   DS:rtime:COUNTER:25:0:U
 155   DS:wcount:COUNTER:25:0:U
 156   DS:wmerged:COUNTER:25:0:U
 157   DS:wbytes:COUNTER:25:0:U
 158   DS:wtime:COUNTER:25:0:U
 159
 160 =item Diskstats (F<partition-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
 161
 162   DS:rcount:COUNTER:25:0:U
 163   DS:rbytes:COUNTER:25:0:U
 164   DS:wcount:COUNTER:25:0:U
 165   DS:wbytes:COUNTER:25:0:U
 166
 167 =item HDD Temperature (F<hddtemp-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
 168
 169   DS:value:GAUGE:25:U:U
 170
 171 =item System load (F<load.rrd>)
 172
 173   DS:shortterm:GAUGE:25:0:100
 174   DS:midterm:GAUGE:25:0:100
 175   DS:longterm:GAUGE:25:0:100
 176
 177 =item Memory usage (F<memory.rrd>)
 178
 179   DS:used:GAUGE:25:0:9223372036854775807
 180   DS:free:GAUGE:25:0:9223372036854775807
 181   DS:buffers:GAUGE:25:0:9223372036854775807
 182   DS:cached:GAUGE:25:0:9223372036854775807
 183
 184 =item NFSv2 Procedures (F<nfs2_procedures-I<(client|server)>.rrd>)
 185
 186   DS:null:COUNTER:25:0:U
 187   DS:getattr:COUNTER:25:0:U
 188   DS:setattr:COUNTER:25:0:U
 189   DS:root:COUNTER:25:0:U
 190   DS:lookup:COUNTER:25:0:U
 191   DS:readlink:COUNTER:25:0:U
 192   DS:read:COUNTER:25:0:U
 193   DS:wrcache:COUNTER:25:0:U
 194   DS:write:COUNTER:25:0:U
 195   DS:create:COUNTER:25:0:U
 196   DS:remove:COUNTER:25:0:U
 197   DS:rename:COUNTER:25:0:U
 198   DS:link:COUNTER:25:0:U
 199   DS:symlink:COUNTER:25:0:U
 200   DS:mkdir:COUNTER:25:0:U
 201   DS:rmdir:COUNTER:25:0:U
 202   DS:readdir:COUNTER:25:0:U
 203   DS:fsstat:COUNTER:25:0:U
 204
 205 =item NFSv3 Procedures (F<nfs3_procedures-I<(client|server)>.rrd>)
 206
 207   DS:null:COUNTER:25:0:U
 208   DS:getattr:COUNTER:25:0:U
 209   DS:setattr:COUNTER:25:0:U
 210   DS:lookup:COUNTER:25:0:U
 211   DS:access:COUNTER:25:0:U
 212   DS:readlink:COUNTER:25:0:U
 213   DS:read:COUNTER:25:0:U
 214   DS:write:COUNTER:25:0:U
 215   DS:create:COUNTER:25:0:U
 216   DS:mkdir:COUNTER:25:0:U
 217   DS:symlink:COUNTER:25:0:U
 218   DS:mknod:COUNTER:25:0:U
 219   DS:remove:COUNTER:25:0:U
 220   DS:rmdir:COUNTER:25:0:U
 221   DS:rename:COUNTER:25:0:U
 222   DS:link:COUNTER:25:0:U
 223   DS:readdir:COUNTER:25:0:U
 224   DS:readdirplus:COUNTER:25:0:U
 225   DS:fsstat:COUNTER:25:0:U
 226   DS:fsinfo:COUNTER:25:0:U
 227   DS:pathconf:COUNTER:25:0:U
 228   DS:commit:COUNTER:25:0:U
 229
 230 =item Network latency / Ping (F<ping-I<E<lt>hostnameE<gt>>.rrd>)
 231
 232   DS:ping:GAUGE:25:0:65535
 233
 234 =item Processes (F<processes.rrd>)
 235
 236   DS:running:GAUGE:25:0:65535
 237   DS:sleeping:GAUGE:25:0:65535
 238   DS:zombies:GAUGE:25:0:65535
 239   DS:stopped:GAUGE:25:0:65535
 240   DS:paging:GAUGE:25:0:65535
 241   DS:blocked:GAUGE:25:0:65535
 242
 243 =item lm_sensors (F<sensors-I<E<lt>chipE<gt>>-I<E<lt>featureE<gt>>.rrd>)
 244
 245   DS:value:GAUGE:25:U:U
 246
 247 =item Serial port traffic (F<serial-I<E<lt>numE<gt>>.rrd>)
 248
 249   DS:incoming:COUNTER:25:0:U
 250   DS:outgoing:COUNTER:25:0:U
 251
 252 =item Swap usage (F<swap.rrd>)
 253
 254   DS:used:GAUGE:25:0:1099511627776
 255   DS:free:GAUGE:25:0:1099511627776
 256   DS:cached:GAUGE:25:0:1099511627776
 257   DS:resv:GAUGE:25:0:1099511627776
 258
 259 =item Tape drive usage (F<tape-I<E<lt>nameE<gt>>.rrd>)
 260
 261   DS:rcount:COUNTER:25:0:
 262   DS:rmerged:COUNTER:25:0:U
 263   DS:rbytes:COUNTER:25:0:U
 264   DS:rtime:COUNTER:25:0:U
 265   DS:wcount:COUNTER:25:0:U
 266   DS:wmerged:COUNTER:25:0:U
 267   DS:wbytes:COUNTER:25:0:U
 268   DS:wtime:COUNTER:25:0:U
 269
 270 =item Network traffic (F<traffic-I<E<lt>nameE<gt>>.rrd>)
 271
 272   DS:incoming:COUNTER:25:0:U
 273   DS:outgoing:COUNTER:25:0:U
 274
 275 =back
 276
 277 =head1 MODES
 278
 279 By default collectd starts in the so called I<local mode> which is not very
 280 interesting. It collects data and writes it into RRD files in
 281 F</var/lib/collectd>. There's nothing special so I won't discuss that in more
 282 detail..
 283
 284 Please be aware that B<client-, local- and server-mode are mutual exclusive>. A
 285 later declaration overrides earlier ones. I<collectd -l -c -s> will start in
 286 server-mode. If you want statistics of the server too you will have to start a
 287 client process as well.
 288
 289 Starting with version 3 collectd may send data over a network. As common with
 290 network stuff there are two modes: A I<sender> and a I<listener>. Since one
 291 usually has many senders and only a few listeners the sender is also called
 292 I<client> (using the option B<-c>) and the listener is called I<server> (using
 293 the option B<-s>).
 294
 295 Communication happends using the (IPv4) multicast group B<239.192.74.66> and
 296 packets sent to the port B<25826/udp>. Every ten seconds the I<client> queries
 297 all the modules and sends the collected data to the multicast group. The
 298 I<server> subscribes to the multicast group upon startup and then waits for
 299 incoming packets. As it receives the packets it checks wether it has the
 300 neccessary module and, if found, writes the data to an RRD file, creating
 301 directories and files as needed.
 302
 303 The multicast group used is within the I<Organization Local Scope> as defined
 304 by L<RFC2365>. Addresses within that space are meant to be routed within an AS
 305 but not to the outside. However collectd cannot control this and won't try. So
 306 it's totally up to you to secure your net.
 307
 308 The UDP port used has been checked to not be assigned by the IANA.
 309
 310 =head1 SPECIAL MODULES
 311
 312 =head2 cpufreq
 313
 314 This module reads F</sys/devices/system/cpu/cpu0/cpufreq/cpuinfo_cur_freq> (for
 315 the first CPU installed) to get the current CPU frequency. If this file does
 316 not exist make sure B<cpufreqd> (L<http://cpufreqd.sourceforge.net/>) or a
 317 similar tool is installed.
 318
 319 =head2 sensors
 320
 321 The B<sensors> module uses lm_sensors to retrieve sensor-values. This means
 322 that all the needed modules have to be loaded and lm_sensors has to be
 323 configured (most likely by editing F</etc/sensors.conf>. Read
 324 L<sensors.conf(5)> for details.
 325
 326 The B<lm_sensors> homepage can be found at
 327 L<http://secure.netroedge.com/~lm78/>.
 328
 329 =head2 hddtemp
 330
 331 To get values from B<hddtemp> collectd connects to B<localhost> (127.0.0.1),
 332 port B<7634/tcp>. hddtemp has to be running to work correctly. If hddtemp is
 333 not running timeouts may appear which may interfere with other statistics..
 334
 335 The B<hddtemp> homepage can be found at
 336 L<http://www.guzu.net/linux/hddtemp.php>.
 337
 338 =head1 SEE ALSO
 339
 340 L<rrdtool(1)>, L<sensors(1)>, L<hddtemp(8)>, L<kstat(3KSTAT)>
 341
 342 =head1 AUTHOR
 343
 344 Florian Forster E<lt>octo@verplant.orgE<gt>
 345
 346 =cut