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