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