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