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