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