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 Apache server stats (I<apache>)
  20
  21 =item
  22
  23 Apple hardware sensors (I<apple_sensors>, Darwin only)
  24
  25 =item
  26
  27 Battery status (I<battery>)
  28
  29 =item
  30
  31 CPU utilization (I<cpu>)
  32
  33 =item
  34
  35 Mountpoint usage (I<df>)
  36
  37 =item
  38
  39 Disk and partition usage/throughput (I<disk>)
  40
  41 =item
  42
  43 Harddisk temperatures (I<hddtemp>)
  44
  45 =item
  46
  47 System load averages (I<load>)
  48
  49 =item
  50
  51 Memory usage (I<memory>)
  52
  53 =item
  54
  55 MySQL statistics (I<mysql>)
  56
  57 =item
  58
  59 NFS utilization (I<nfs>, Linux only)
  60
  61 =item
  62
  63 Network latency (I<ping>)
  64
  65 =item
  66
  67 Number of processes (I<processes>, Linux only)
  68
  69 =item
  70
  71 lm_sensors information (I<sensors>, Linux only)
  72
  73 =item
  74
  75 Serial port traffic (I<serial>, Linux only)
  76
  77 =item
  78
  79 Swap usage (I<swap>)
  80
  81 =item
  82
  83 Tape drive usage (I<tape>, Solaris only)
  84
  85 =item
  86
  87 Network traffic (I<traffic>)
  88
  89 =item
  90
  91 Number of users logged into the system (I<users>)
  92
  93 =item
  94
  95 System ressources used by VServers (I<vserver>)
  96
  97 =item
  98
  99 Wireless network stats (I<wireless>)
 100
 101 =back
 102
 103 =head1 OPTIONS
 104
 105 =over 4
 106
 107 =item B<-C> I<E<lt>config-fileE<gt>>
 108
 109 Specify an alternative config file. This is the place to go when you wish to
 110 change B<collectd>'s behavior. The path may be relative to the current working
 111 directory.
 112
 113 =item B<-f>
 114
 115 Don't fork to the background. I<collectd> will also B<not> close standard file
 116 descriptors, detach from the session nor write a pid file. This is mainly
 117 thought for 'supervisioning' init replacements such as I<runit>.
 118
 119 =item B<-h>
 120
 121 Output usage information and exit.
 122
 123 =back
 124
 125 =head1 MODES
 126
 127 collectd can operate in three different operating modes. The modes are
 128 described below.
 129
 130 The simplest mode is the so called B<local mode>. Data is collected locally and
 131 written in RRD files that reside in I<DataDir>. This is the default mode when
 132 collectd is linked against C<librrd>.
 133
 134 The other modes, B<client mode> and B<server mode>, are used to send data over
 135 a network and receive it again.
 136
 137 In B<client mode> the daemon collects the data locally and sends its results
 138 to one or more network addresses. No RRD files are written in this case. This
 139 is the only mode available if collectd is not linked against C<librrd>.
 140
 141 If started in B<server mode> the daemon will listen on one or more interfaces
 142 and write the data it receives to RRD files. No data is collected locally.
 143
 144 In the last mode, B<log mode>, data is collected locally and written in
 145 text files that reside in I<DataDir>.
 146
 147 Please refer to L<collectd.conf(5)> for the configuration options and default
 148 values.
 149
 150 =head1 SPECIAL PLUGINS
 151
 152 =head2 apache
 153
 154 This module connects to an Apache webserver and expects the output produced by
 155 B<mod_status.c>. If requires B<libcurl> to set up the HTTP connection and issue
 156 the request(s). The following is a sample config for the Apache webserver. The
 157 use of C<ExtendedStatus on> is mandatory.
 158
 159   ExtendedStatus on
 160   <IfModule mod_status.c>
 161     <Location /mod_status>
 162       SetHandler server-status
 163     </Location>
 164   </IfModule>
 165
 166 This plugin requires further configuration. Please read L<collectd.conf(5)>.
 167
 168 =head2 cpufreq
 169
 170 This module reads F</sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq> (for
 171 the first CPU installed) to get the current CPU frequency. If this file does
 172 not exist make sure B<cpufreqd> (L<http://cpufreqd.sourceforge.net/>) or a
 173 similar tool is installed and an "cpu governor" (that's kernel module) is
 174 loaded.
 175
 176 =head2 mysql
 177
 178 Requires B<mysqlclient> to be installed. It connects to the database when
 179 started and keeps the connection up as long as possible. When the connection is
 180 interrupted for whatever reason it will try to re-connect. The syslog will
 181 contain loud complaints in case anything goes wrong.
 182
 183 This plugin issues C<SHOW STATUS> and evaluates C<Bytes_{received,sent}>,
 184 C<Com_*> and C<Handler_*> which correspond to F<traffic-mysql.rrd>,
 185 F<mysql_commands-*.rrd> and F<mysql_handler-*.rrd>. Also, the values of
 186 C<Qcache_*> are put in F<mysql_qcache.rrd> and values of C<Threads_*> are put
 187 in F<mysql_threads.rrd>. Please refer to the B<MySQL reference manual>,
 188 I<5.2.4. Server Status Variables> for an explanation of these values.
 189
 190 =head2 sensors
 191
 192 The B<sensors> module uses lm_sensors to retrieve sensor-values. This means
 193 that all the needed modules have to be loaded and lm_sensors has to be
 194 configured (most likely by editing F</etc/sensors.conf>. Read
 195 L<sensors.conf(5)> for details.
 196
 197 The B<lm_sensors> homepage can be found at
 198 L<http://secure.netroedge.com/~lm78/>.
 199
 200 =head2 hddtemp
 201
 202 To get values from B<hddtemp> collectd connects to B<localhost> (127.0.0.1),
 203 port B<7634/tcp>. The B<Host> and B<Port> options can be used to change these
 204 default values. See L<collectd.conf(5)> for details. C<hddtemp> has to be
 205 running to work correctly. If C<hddtemp> is not running timeouts may appear
 206 which may interfere with other statistics..
 207
 208 The B<hddtemp> homepage can be found at
 209 L<http://www.guzu.net/linux/hddtemp.php>.
 210
 211 =head2 vserver
 212
 213 B<VServer> support is only available for Linux. It cannot yet be found in a
 214 vanilla kernel, though. To make use of this plugin you need a kernel that has
 215 B<VServer> support built in, i.e. you need to apply the patches and compile
 216 your own kernel, which will then provide the /proc/virtual filesystem that is
 217 required by this plugin.
 218
 219 The B<VServer> homepage can be found at L<http://linux-vserver.org/>.
 220
 221 =head1 RRD FILES
 222
 223 The RRD files are created automatically. The size of the RRAs depend on the
 224 compile time settings of I<step> and I<width>. With the default values (I<step>
 225 = B<10>, I<width> = B<1200>) the following RRAs are created:
 226
 227   RRA:AVERAGE:0.1:1:8640
 228   RRA:AVERAGE:0.1:50:1210
 229   RRA:AVERAGE:0.1:223:1202
 230   RRA:AVERAGE:0.1:2635:1201
 231   RRA:MIN:0.1:1:8640
 232   RRA:MIN:0.1:50:1210
 233   RRA:MIN:0.1:223:1202
 234   RRA:MIN:0.1:2635:1201
 235   RRA:MAX:0.1:1:8640
 236   RRA:MAX:0.1:50:1210
 237   RRA:MAX:0.1:223:1202
 238   RRA:MAX:0.1:2635:1201
 239
 240 By default collectd uses a 10 second I<step>. Thus the RRAs contain the
 241 following timespans. If you've changed the I<step> at compile time you will
 242 have calculate resolution and timespan yourself.
 243
 244   PDP per CDP |  Resolution  | Data points | Timespan
 245   ------------+--------------+-------------+---------
 246             1 | 10.0 seconds !        8640 ! 1 day
 247            50 |  8.3 minutes |        1210 | 1 week
 248           223 | 37.2 minutes |        1202 | 1 month
 249          2635 |  7.3 hours   |        1201 | 1 year
 250
 251 The DS'es depend on the module creating the RRD files:
 252
 253 =over 4
 254
 255 =item Apache traffic (F<apache/apache_bytes.rrd>)
 256
 257   DS:count:COUNTER:HEARTBEAT:0:134217728
 258
 259 =item Apache requests (F<apache/apache_requests.rrd>)
 260
 261   DS:count:COUNTER:HEARTBEAT:0:1048576
 262
 263 =item Apache scoreboard (F<apache/apache_scoreboard-I<E<lt>nameE<gt>>.rrd>)
 264
 265   DS:count:GAUGE:HEARTBEAT:0:U
 266
 267 =item Apple temperature sensor (F<apple_sensors/temperature-I<E<lt>nameE<gt>>.rrd>)
 268
 269   DS:value:GAUGE:HEARTBEAT:U:U
 270
 271 =item Apple fanspeed sensor (F<apple_sensors/fanspeed-I<E<lt>nameE<gt>>.rrd>)
 272
 273   DS:value:GAUGE:HEARTBEAT:U:U
 274
 275 =item Battery charge (F<battery-I<E<lt>nameE<gt>>/charge.rrd>)
 276
 277   DS:charge:GAUGE:HEARTBEAT:0:U
 278
 279 =item Battery current (F<battery-I<E<lt>nameE<gt>>/current.rrd>)
 280
 281   DS:current:GAUGE:HEARTBEAT:U:U
 282
 283 =item Battery voltage (F<battery-I<E<lt>nameE<gt>>/voltage.rrd>)
 284
 285   DS:voltage:GAUGE:HEARTBEAT:U:U
 286
 287 =item CPU (F<cpu-I<E<lt>numE<gt>>.rrd>)
 288
 289   DS:user:COUNTER:HEARTBEAT:0:100
 290   DS:nice:COUNTER:HEARTBEAT:0:100
 291   DS:syst:COUNTER:HEARTBEAT:0:100
 292   DS:idle:COUNTER:HEARTBEAT:0:100
 293   DS:wait:COUNTER:HEARTBEAT:0:100
 294
 295 =item CPU frequency (F<cpufreq-I<E<lt>numE<gt>>.rrd>)
 296
 297   DS:value:GAUGE:HEARTBEAT:0:U
 298
 299 =item Mountpoints (F<df-I<E<lt>pathE<gt>>.rrd>)
 300
 301   DS:used:GAUGE:HEARTBEAT:0:U
 302   DS:free:GAUGE:HEARTBEAT:0:U
 303
 304 =item Diskstats (F<disk-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
 305
 306   DS:rcount:COUNTER:HEARTBEAT:0:U
 307   DS:rmerged:COUNTER:HEARTBEAT:0:U
 308   DS:rbytes:COUNTER:HEARTBEAT:0:U
 309   DS:rtime:COUNTER:HEARTBEAT:0:U
 310   DS:wcount:COUNTER:HEARTBEAT:0:U
 311   DS:wmerged:COUNTER:HEARTBEAT:0:U
 312   DS:wbytes:COUNTER:HEARTBEAT:0:U
 313   DS:wtime:COUNTER:HEARTBEAT:0:U
 314
 315 =item Diskstats (F<partition-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
 316
 317   DS:rcount:COUNTER:HEARTBEAT:0:U
 318   DS:rbytes:COUNTER:HEARTBEAT:0:U
 319   DS:wcount:COUNTER:HEARTBEAT:0:U
 320   DS:wbytes:COUNTER:HEARTBEAT:0:U
 321
 322 =item HDD Temperature (F<hddtemp-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
 323
 324   DS:value:GAUGE:HEARTBEAT:U:U
 325
 326 =item System load (F<load.rrd>)
 327
 328   DS:shortterm:GAUGE:HEARTBEAT:0:100
 329   DS:midterm:GAUGE:HEARTBEAT:0:100
 330   DS:longterm:GAUGE:HEARTBEAT:0:100
 331
 332 =item Memory usage (F<memory.rrd>)
 333
 334   DS:used:GAUGE:HEARTBEAT:0:9223372036854775807
 335   DS:free:GAUGE:HEARTBEAT:0:9223372036854775807
 336   DS:buffers:GAUGE:HEARTBEAT:0:9223372036854775807
 337   DS:cached:GAUGE:HEARTBEAT:0:9223372036854775807
 338
 339 =item MySQL commands and handlers (F<mysql_commands-I<E<lt>commandE<gt>>.rrd> and F<mysql_handler-I<E<lt>handlerE<gt>>.rrd>)
 340
 341   DS:value:COUNTER:HEARTBEAT:0:U
 342
 343 =item MySQL query cache (F<mysql_qcache.rrd>)
 344
 345   DS:hits:COUNTER:HEARTBEAT:0:U
 346   DS:inserts:COUNTER:HEARTBEAT:0:U
 347   DS:not_cached:COUNTER:HEARTBEAT:0:U
 348   DS:lowmem_prunes:COUNTER:HEARTBEAT:0:U
 349   DS:queries_in_cache:GAUGE:HEARTBEAT:0:U
 350
 351 =item MySQL threads (F<mysql_threads.rrd>)
 352
 353   DS:running:GAUGE:HEARTBEAT:0:U
 354   DS:connected:GAUGE:HEARTBEAT:0:U
 355   DS:cached:GAUGE:HEARTBEAT:0:U
 356   DS:created:COUNTER:HEARTBEAT:0:U
 357
 358 =item NFSv2 Procedures (F<nfs2_procedures-I<(client|server)>.rrd>)
 359
 360   DS:null:COUNTER:HEARTBEAT:0:U
 361   DS:getattr:COUNTER:HEARTBEAT:0:U
 362   DS:setattr:COUNTER:HEARTBEAT:0:U
 363   DS:root:COUNTER:HEARTBEAT:0:U
 364   DS:lookup:COUNTER:HEARTBEAT:0:U
 365   DS:readlink:COUNTER:HEARTBEAT:0:U
 366   DS:read:COUNTER:HEARTBEAT:0:U
 367   DS:wrcache:COUNTER:HEARTBEAT:0:U
 368   DS:write:COUNTER:HEARTBEAT:0:U
 369   DS:create:COUNTER:HEARTBEAT:0:U
 370   DS:remove:COUNTER:HEARTBEAT:0:U
 371   DS:rename:COUNTER:HEARTBEAT:0:U
 372   DS:link:COUNTER:HEARTBEAT:0:U
 373   DS:symlink:COUNTER:HEARTBEAT:0:U
 374   DS:mkdir:COUNTER:HEARTBEAT:0:U
 375   DS:rmdir:COUNTER:HEARTBEAT:0:U
 376   DS:readdir:COUNTER:HEARTBEAT:0:U
 377   DS:fsstat:COUNTER:HEARTBEAT:0:U
 378
 379 =item NFSv3 Procedures (F<nfs3_procedures-I<(client|server)>.rrd>)
 380
 381   DS:null:COUNTER:HEARTBEAT:0:U
 382   DS:getattr:COUNTER:HEARTBEAT:0:U
 383   DS:setattr:COUNTER:HEARTBEAT:0:U
 384   DS:lookup:COUNTER:HEARTBEAT:0:U
 385   DS:access:COUNTER:HEARTBEAT:0:U
 386   DS:readlink:COUNTER:HEARTBEAT:0:U
 387   DS:read:COUNTER:HEARTBEAT:0:U
 388   DS:write:COUNTER:HEARTBEAT:0:U
 389   DS:create:COUNTER:HEARTBEAT:0:U
 390   DS:mkdir:COUNTER:HEARTBEAT:0:U
 391   DS:symlink:COUNTER:HEARTBEAT:0:U
 392   DS:mknod:COUNTER:HEARTBEAT:0:U
 393   DS:remove:COUNTER:HEARTBEAT:0:U
 394   DS:rmdir:COUNTER:HEARTBEAT:0:U
 395   DS:rename:COUNTER:HEARTBEAT:0:U
 396   DS:link:COUNTER:HEARTBEAT:0:U
 397   DS:readdir:COUNTER:HEARTBEAT:0:U
 398   DS:readdirplus:COUNTER:HEARTBEAT:0:U
 399   DS:fsstat:COUNTER:HEARTBEAT:0:U
 400   DS:fsinfo:COUNTER:HEARTBEAT:0:U
 401   DS:pathconf:COUNTER:HEARTBEAT:0:U
 402   DS:commit:COUNTER:HEARTBEAT:0:U
 403
 404 =item Network latency / Ping (F<ping-I<E<lt>hostnameE<gt>>.rrd>)
 405
 406   DS:ping:GAUGE:HEARTBEAT:0:65535
 407
 408 =item Processes (F<processes.rrd>)
 409
 410   DS:running:GAUGE:HEARTBEAT:0:65535
 411   DS:sleeping:GAUGE:HEARTBEAT:0:65535
 412   DS:zombies:GAUGE:HEARTBEAT:0:65535
 413   DS:stopped:GAUGE:HEARTBEAT:0:65535
 414   DS:paging:GAUGE:HEARTBEAT:0:65535
 415   DS:blocked:GAUGE:HEARTBEAT:0:65535
 416
 417 =item lm_sensors (F<sensors-I<E<lt>chipE<gt>>-I<E<lt>featureE<gt>>.rrd>)
 418
 419   DS:value:GAUGE:HEARTBEAT:U:U
 420
 421 =item Serial port traffic (F<serial-I<E<lt>numE<gt>>.rrd>)
 422
 423   DS:incoming:COUNTER:HEARTBEAT:0:U
 424   DS:outgoing:COUNTER:HEARTBEAT:0:U
 425
 426 =item Swap usage (F<swap.rrd>)
 427
 428   DS:used:GAUGE:HEARTBEAT:0:1099511627776
 429   DS:free:GAUGE:HEARTBEAT:0:1099511627776
 430   DS:cached:GAUGE:HEARTBEAT:0:1099511627776
 431   DS:resv:GAUGE:HEARTBEAT:0:1099511627776
 432
 433 =item Tape drive usage (F<tape-I<E<lt>nameE<gt>>.rrd>)
 434
 435   DS:rcount:COUNTER:HEARTBEAT:0:
 436   DS:rmerged:COUNTER:HEARTBEAT:0:U
 437   DS:rbytes:COUNTER:HEARTBEAT:0:U
 438   DS:rtime:COUNTER:HEARTBEAT:0:U
 439   DS:wcount:COUNTER:HEARTBEAT:0:U
 440   DS:wmerged:COUNTER:HEARTBEAT:0:U
 441   DS:wbytes:COUNTER:HEARTBEAT:0:U
 442   DS:wtime:COUNTER:HEARTBEAT:0:U
 443
 444 =item Network traffic (F<traffic-I<E<lt>interfaceE<gt>>.rrd>)
 445
 446   DS:incoming:COUNTER:HEARTBEAT:0:U
 447   DS:outgoing:COUNTER:HEARTBEAT:0:U
 448
 449 =item Interface packets (F<if_packets-I<E<lt>interfaceE<gt>>.rrd>)
 450
 451   DS:rx:COUNTER:HEARTBEAT:0:U
 452   DS:tx:COUNTER:HEARTBEAT:0:U
 453
 454 =item Interface errors (F<if_errors-I<E<lt>interfaceE<gt>>.rrd>)
 455
 456   DS:rx:COUNTER:HEARTBEAT:0:U
 457   DS:tx:COUNTER:HEARTBEAT:0:U
 458
 459 =item Users (F<users.rrd>)
 460
 461   DS:users:GAUGE:HEARTBEAT:0:65535
 462
 463 =item VServer load (F<vserver-I<E<lt>xidE<gt>>/load.rrd>)
 464
 465   DS:shortterm:GAUGE:HEARTBEAT:0:100
 466   DS:midterm:GAUGE:HEARTBEAT:0:100
 467   DS:longterm:GAUGE:HEARTBEAT:0:100
 468
 469 =item VServer threads (F<vserver-I<E<lt>xidE<gt>>/threads.rrd>)
 470
 471   DS:total:GAUGE:HEARTBEAT:0:65535
 472   DS:running:GAUGE:HEARTBEAT:0:65535
 473   DS:uninterruptible:GAUGE:HEARTBEAT:0:65535
 474   DS:onhold:GAUGE:HEARTBEAT:0:65535
 475
 476 =item VServer network traffic (F<vserver-I<E<lt>xidE<gt>>/traffic-I<E<lt>nameE<gt>>.rrd>)
 477
 478   DS:incoming:COUNTER:HEARTBEAT:0:9223372036854775807
 479   DS:outgoing:COUNTER:HEARTBEAT:0:9223372036854775807
 480   DS:failed:COUNTER:HEARTBEAT:0:9223372036854775807
 481
 482 =item VServer processes (F<vserver-I<E<lt>xidE<gt>>/vs_processes.rrd>)
 483
 484   DS:total:GAUGE:HEARTBEAT:0:65535
 485
 486 =item VServer memory usage (F<vserver-I<E<lt>xidE<gt>>/vs_memory.rrd>)
 487
 488   DS:vm:GAUGE:HEARTBEAT:0:9223372036854775807
 489   DS:vml:GAUGE:HEARTBEAT:0:9223372036854775807
 490   DS:rss:GAUGE:HEARTBEAT:0:9223372036854775807
 491   DS:anon:GAUGE:HEARTBEAT:0:9223372036854775807
 492
 493 =item Wireless link quality (F<wireless-I<E<lt>interfaceE<gt>>.rrd>)
 494
 495   DS:quality:GAUGE:HEARTBEAT:0:U
 496   DS:power:GAUGE:HEARTBEAT:U:0
 497   DS:noise:GAUGE:HEARTBEAT:U:0
 498
 499 =back
 500
 501 =head1 SEE ALSO
 502
 503 L<collectd.conf(5)>, L<rrdtool(1)>, L<sensors(1)>, L<hddtemp(8)>,
 504 L<kstat(3KSTAT)>
 505
 506 =head1 AUTHOR
 507
 508 Florian Forster E<lt>octo@verplant.orgE<gt>
 509
 510 =cut