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