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