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