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