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 Battery charge (F<battery-I<E<lt>nameE<gt>>/charge.rrd>)
 268
 269   DS:charge:GAUGE:25:0:U
 270
 271 =item Battery current (F<battery-I<E<lt>nameE<gt>>/current.rrd>)
 272
 273   DS:current:GAUGE:25:U:U
 274
 275 =item Battery voltage (F<battery-I<E<lt>nameE<gt>>/voltage.rrd>)
 276
 277   DS:voltage:GAUGE:25:U:U
 278
 279 =item CPU (F<cpu-I<E<lt>numE<gt>>.rrd>)
 280
 281   DS:user:COUNTER:25:0:100
 282   DS:nice:COUNTER:25:0:100
 283   DS:syst:COUNTER:25:0:100
 284   DS:idle:COUNTER:25:0:100
 285   DS:wait:COUNTER:25:0:100
 286
 287 =item Mountpoints (F<df-I<E<lt>pathE<gt>>.rrd>)
 288
 289   DS:used:GAUGE:25:0:U
 290   DS:free:GAUGE:25:0:U
 291
 292 =item Diskstats (F<disk-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
 293
 294   DS:rcount:COUNTER:25:0:U
 295   DS:rmerged:COUNTER:25:0:U
 296   DS:rbytes:COUNTER:25:0:U
 297   DS:rtime:COUNTER:25:0:U
 298   DS:wcount:COUNTER:25:0:U
 299   DS:wmerged:COUNTER:25:0:U
 300   DS:wbytes:COUNTER:25:0:U
 301   DS:wtime:COUNTER:25:0:U
 302
 303 =item Diskstats (F<partition-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
 304
 305   DS:rcount:COUNTER:25:0:U
 306   DS:rbytes:COUNTER:25:0:U
 307   DS:wcount:COUNTER:25:0:U
 308   DS:wbytes:COUNTER:25:0:U
 309
 310 =item HDD Temperature (F<hddtemp-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
 311
 312   DS:value:GAUGE:25:U:U
 313
 314 =item System load (F<load.rrd>)
 315
 316   DS:shortterm:GAUGE:25:0:100
 317   DS:midterm:GAUGE:25:0:100
 318   DS:longterm:GAUGE:25:0:100
 319
 320 =item Memory usage (F<memory.rrd>)
 321
 322   DS:used:GAUGE:25:0:9223372036854775807
 323   DS:free:GAUGE:25:0:9223372036854775807
 324   DS:buffers:GAUGE:25:0:9223372036854775807
 325   DS:cached:GAUGE:25:0:9223372036854775807
 326
 327 =item MySQL commands and handlers (F<mysql_commands-I<E<lt>commandE<gt>>.rrd> and F<mysql_handler-I<E<lt>handlerE<gt>>.rrd>)
 328
 329   DS:value:COUNTER:25:0:U
 330
 331 =item MySQL query cache (F<mysql_qcache.rrd>)
 332
 333   DS:hits:COUNTER:25:0:U
 334   DS:inserts:COUNTER:25:0:U
 335   DS:not_cached:COUNTER:25:0:U
 336   DS:lowmem_prunes:COUNTER:25:0:U
 337   DS:queries_in_cache:GAUGE:25:0:U
 338
 339 =item MySQL threads (F<mysql_threads.rrd>)
 340
 341   DS:running:GAUGE:25:0:U
 342   DS:connected:GAUGE:25:0:U
 343   DS:cached:GAUGE:25:0:U
 344   DS:created:COUNTER:25:0:U
 345
 346 =item NFSv2 Procedures (F<nfs2_procedures-I<(client|server)>.rrd>)
 347
 348   DS:null:COUNTER:25:0:U
 349   DS:getattr:COUNTER:25:0:U
 350   DS:setattr:COUNTER:25:0:U
 351   DS:root:COUNTER:25:0:U
 352   DS:lookup:COUNTER:25:0:U
 353   DS:readlink:COUNTER:25:0:U
 354   DS:read:COUNTER:25:0:U
 355   DS:wrcache:COUNTER:25:0:U
 356   DS:write:COUNTER:25:0:U
 357   DS:create:COUNTER:25:0:U
 358   DS:remove:COUNTER:25:0:U
 359   DS:rename:COUNTER:25:0:U
 360   DS:link:COUNTER:25:0:U
 361   DS:symlink:COUNTER:25:0:U
 362   DS:mkdir:COUNTER:25:0:U
 363   DS:rmdir:COUNTER:25:0:U
 364   DS:readdir:COUNTER:25:0:U
 365   DS:fsstat:COUNTER:25:0:U
 366
 367 =item NFSv3 Procedures (F<nfs3_procedures-I<(client|server)>.rrd>)
 368
 369   DS:null:COUNTER:25:0:U
 370   DS:getattr:COUNTER:25:0:U
 371   DS:setattr:COUNTER:25:0:U
 372   DS:lookup:COUNTER:25:0:U
 373   DS:access:COUNTER:25:0:U
 374   DS:readlink:COUNTER:25:0:U
 375   DS:read:COUNTER:25:0:U
 376   DS:write:COUNTER:25:0:U
 377   DS:create:COUNTER:25:0:U
 378   DS:mkdir:COUNTER:25:0:U
 379   DS:symlink:COUNTER:25:0:U
 380   DS:mknod:COUNTER:25:0:U
 381   DS:remove:COUNTER:25:0:U
 382   DS:rmdir:COUNTER:25:0:U
 383   DS:rename:COUNTER:25:0:U
 384   DS:link:COUNTER:25:0:U
 385   DS:readdir:COUNTER:25:0:U
 386   DS:readdirplus:COUNTER:25:0:U
 387   DS:fsstat:COUNTER:25:0:U
 388   DS:fsinfo:COUNTER:25:0:U
 389   DS:pathconf:COUNTER:25:0:U
 390   DS:commit:COUNTER:25:0:U
 391
 392 =item Network latency / Ping (F<ping-I<E<lt>hostnameE<gt>>.rrd>)
 393
 394   DS:ping:GAUGE:25:0:65535
 395
 396 =item Processes (F<processes.rrd>)
 397
 398   DS:running:GAUGE:25:0:65535
 399   DS:sleeping:GAUGE:25:0:65535
 400   DS:zombies:GAUGE:25:0:65535
 401   DS:stopped:GAUGE:25:0:65535
 402   DS:paging:GAUGE:25:0:65535
 403   DS:blocked:GAUGE:25:0:65535
 404
 405 =item lm_sensors (F<sensors-I<E<lt>chipE<gt>>-I<E<lt>featureE<gt>>.rrd>)
 406
 407   DS:value:GAUGE:25:U:U
 408
 409 =item Serial port traffic (F<serial-I<E<lt>numE<gt>>.rrd>)
 410
 411   DS:incoming:COUNTER:25:0:U
 412   DS:outgoing:COUNTER:25:0:U
 413
 414 =item Swap usage (F<swap.rrd>)
 415
 416   DS:used:GAUGE:25:0:1099511627776
 417   DS:free:GAUGE:25:0:1099511627776
 418   DS:cached:GAUGE:25:0:1099511627776
 419   DS:resv:GAUGE:25:0:1099511627776
 420
 421 =item Tape drive usage (F<tape-I<E<lt>nameE<gt>>.rrd>)
 422
 423   DS:rcount:COUNTER:25:0:
 424   DS:rmerged:COUNTER:25:0:U
 425   DS:rbytes:COUNTER:25:0:U
 426   DS:rtime:COUNTER:25:0:U
 427   DS:wcount:COUNTER:25:0:U
 428   DS:wmerged:COUNTER:25:0:U
 429   DS:wbytes:COUNTER:25:0:U
 430   DS:wtime:COUNTER:25:0:U
 431
 432 =item Network traffic (F<traffic-I<E<lt>nameE<gt>>.rrd>)
 433
 434   DS:incoming:COUNTER:25:0:U
 435   DS:outgoing:COUNTER:25:0:U
 436
 437 =item Users (F<users.rrd>)
 438
 439   DS:users:GAUGE:25:0:65535
 440
 441 =item VServer load (F<vserver-I<E<lt>xidE<gt>>/load.rrd>)
 442
 443   DS:shortterm:GAUGE:25:0:100
 444   DS:midterm:GAUGE:25:0:100
 445   DS:longterm:GAUGE:25:0:100
 446
 447 =item VServer threads (F<vserver-I<E<lt>xidE<gt>>/threads.rrd>)
 448
 449   DS:total:GAUGE:25:0:65535
 450   DS:running:GAUGE:25:0:65535
 451   DS:uninterruptible:GAUGE:25:0:65535
 452   DS:onhold:GAUGE:25:0:65535
 453
 454 =item VServer network traffic (F<vserver-I<E<lt>xidE<gt>>/traffic-I<E<lt>nameE<gt>>.rrd>)
 455
 456   DS:incoming:COUNTER:25:0:9223372036854775807
 457   DS:outgoing:COUNTER:25:0:9223372036854775807
 458   DS:failed:COUNTER:25:0:9223372036854775807
 459
 460 =item VServer processes (F<vserver-I<E<lt>xidE<gt>>/vs_processes.rrd>)
 461
 462   DS:total:GAUGE:25:0:65535
 463
 464 =item VServer memory usage (F<vserver-I<E<lt>xidE<gt>>/vs_memory.rrd>)
 465
 466   DS:vm:GAUGE:25:0:9223372036854775807
 467   DS:vml:GAUGE:25:0:9223372036854775807
 468   DS:rss:GAUGE:25:0:9223372036854775807
 469   DS:anon:GAUGE:25:0:9223372036854775807
 470
 471 =back
 472
 473 =head1 SEE ALSO
 474
 475 L<collectd.conf(5)>, L<rrdtool(1)>, L<sensors(1)>, L<hddtemp(8)>,
 476 L<kstat(3KSTAT)>
 477
 478 =head1 AUTHOR
 479
 480 Florian Forster E<lt>octo@verplant.orgE<gt>
 481
 482 =cut