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