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 =back
  86
  87 =head1 OPTIONS
  88
  89 =over 4
  90
  91 =item B<-C> I<E<lt>config-fileE<gt>>
  92
  93 Specify an alternative config file. This is the place to go when you wish to
  94 change B<collectd>'s behavior. The path may be relative to the current working
  95 directory.
  96
  97 =item B<-f>
  98
  99 Don't fork to the background. I<collectd> will also B<not> close standard file
 100 descriptors, detach from the session nor write a pid file. This is mainly
 101 thought for 'supervisioning' init replacements such as I<runit>.
 102
 103 =item B<-h>
 104
 105 Output usage information and exit.
 106
 107 =back
 108
 109 =head1 RRD FILES
 110
 111 The RRD files are created automatically with the following RRAs:
 112
 113   RRA:AVERAGE:0.2:6:1500
 114   RRA:AVERAGE:0.1:180:1680
 115   RRA:AVERAGE:0.1:2160:1520
 116   RRA:MIN:0.2:6:1500
 117   RRA:MIN:0.1:180:1680
 118   RRA:MIN:0.1:2160:1520
 119   RRA:MAX:0.2:6:1500
 120   RRA:MAX:0.1:180:1680
 121   RRA:MAX:0.1:2160:1520
 122
 123 Since collectd uses a 10 second I<step> the RRAs contain the following
 124 timespans:
 125
 126   Resolution | Data points |  Timespan
 127   -----------+-------------+----------
 128   60 seconds |        1500 |  25 hours
 129   30 minutes |        1680 |  35 days
 130    6 hours   |        1520 | 380 days
 131
 132 The DS'es depend on the module creating the RRD files:
 133
 134 =over 4
 135
 136 =item Battery charge (F<battery-I<E<lt>nameE<gt>>/charge.rrd>)
 137
 138   DS:charge:GAUGE:25:0:U
 139
 140 =item Battery current (F<battery-I<E<lt>nameE<gt>>/current.rrd>)
 141
 142   DS:current:GAUGE:25:U:U
 143
 144 =item Battery voltage (F<battery-I<E<lt>nameE<gt>>/voltage.rrd>)
 145
 146   DS:voltage:GAUGE:25:U:U
 147
 148 =item CPU (F<cpu-I<E<lt>numE<gt>>.rrd>)
 149
 150   DS:user:COUNTER:25:0:100
 151   DS:nice:COUNTER:25:0:100
 152   DS:syst:COUNTER:25:0:100
 153   DS:idle:COUNTER:25:0:100
 154   DS:wait:COUNTER:25:0:100
 155
 156 =item Mountpoints (F<df-I<E<lt>pathE<gt>>.rrd>)
 157
 158   DS:used:GAUGE:25:0:U
 159   DS:free:GAUGE:25:0:U
 160
 161 =item Diskstats (F<disk-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
 162
 163   DS:rcount:COUNTER:25:0:U
 164   DS:rmerged:COUNTER:25:0:U
 165   DS:rbytes:COUNTER:25:0:U
 166   DS:rtime:COUNTER:25:0:U
 167   DS:wcount:COUNTER:25:0:U
 168   DS:wmerged:COUNTER:25:0:U
 169   DS:wbytes:COUNTER:25:0:U
 170   DS:wtime:COUNTER:25:0:U
 171
 172 =item Diskstats (F<partition-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
 173
 174   DS:rcount:COUNTER:25:0:U
 175   DS:rbytes:COUNTER:25:0:U
 176   DS:wcount:COUNTER:25:0:U
 177   DS:wbytes:COUNTER:25:0:U
 178
 179 =item HDD Temperature (F<hddtemp-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
 180
 181   DS:value:GAUGE:25:U:U
 182
 183 =item System load (F<load.rrd>)
 184
 185   DS:shortterm:GAUGE:25:0:100
 186   DS:midterm:GAUGE:25:0:100
 187   DS:longterm:GAUGE:25:0:100
 188
 189 =item Memory usage (F<memory.rrd>)
 190
 191   DS:used:GAUGE:25:0:9223372036854775807
 192   DS:free:GAUGE:25:0:9223372036854775807
 193   DS:buffers:GAUGE:25:0:9223372036854775807
 194   DS:cached:GAUGE:25:0:9223372036854775807
 195
 196 =item MySQL statistics (F<mysql_commands-I<E<lt>commandE<gt>>.rrd> and F<mysql_handler-I<E<lt>handlerE<gt>>.rrd>)
 197
 198   DS:value:COUNTER:25:0:U
 199
 200 =item NFSv2 Procedures (F<nfs2_procedures-I<(client|server)>.rrd>)
 201
 202   DS:null:COUNTER:25:0:U
 203   DS:getattr:COUNTER:25:0:U
 204   DS:setattr:COUNTER:25:0:U
 205   DS:root:COUNTER:25:0:U
 206   DS:lookup:COUNTER:25:0:U
 207   DS:readlink:COUNTER:25:0:U
 208   DS:read:COUNTER:25:0:U
 209   DS:wrcache:COUNTER:25:0:U
 210   DS:write:COUNTER:25:0:U
 211   DS:create:COUNTER:25:0:U
 212   DS:remove:COUNTER:25:0:U
 213   DS:rename:COUNTER:25:0:U
 214   DS:link:COUNTER:25:0:U
 215   DS:symlink:COUNTER:25:0:U
 216   DS:mkdir:COUNTER:25:0:U
 217   DS:rmdir:COUNTER:25:0:U
 218   DS:readdir:COUNTER:25:0:U
 219   DS:fsstat:COUNTER:25:0:U
 220
 221 =item NFSv3 Procedures (F<nfs3_procedures-I<(client|server)>.rrd>)
 222
 223   DS:null:COUNTER:25:0:U
 224   DS:getattr:COUNTER:25:0:U
 225   DS:setattr:COUNTER:25:0:U
 226   DS:lookup:COUNTER:25:0:U
 227   DS:access:COUNTER:25:0:U
 228   DS:readlink:COUNTER:25:0:U
 229   DS:read:COUNTER:25:0:U
 230   DS:write:COUNTER:25:0:U
 231   DS:create:COUNTER:25:0:U
 232   DS:mkdir:COUNTER:25:0:U
 233   DS:symlink:COUNTER:25:0:U
 234   DS:mknod:COUNTER:25:0:U
 235   DS:remove:COUNTER:25:0:U
 236   DS:rmdir:COUNTER:25:0:U
 237   DS:rename:COUNTER:25:0:U
 238   DS:link:COUNTER:25:0:U
 239   DS:readdir:COUNTER:25:0:U
 240   DS:readdirplus:COUNTER:25:0:U
 241   DS:fsstat:COUNTER:25:0:U
 242   DS:fsinfo:COUNTER:25:0:U
 243   DS:pathconf:COUNTER:25:0:U
 244   DS:commit:COUNTER:25:0:U
 245
 246 =item Network latency / Ping (F<ping-I<E<lt>hostnameE<gt>>.rrd>)
 247
 248   DS:ping:GAUGE:25:0:65535
 249
 250 =item Processes (F<processes.rrd>)
 251
 252   DS:running:GAUGE:25:0:65535
 253   DS:sleeping:GAUGE:25:0:65535
 254   DS:zombies:GAUGE:25:0:65535
 255   DS:stopped:GAUGE:25:0:65535
 256   DS:paging:GAUGE:25:0:65535
 257   DS:blocked:GAUGE:25:0:65535
 258
 259 =item lm_sensors (F<sensors-I<E<lt>chipE<gt>>-I<E<lt>featureE<gt>>.rrd>)
 260
 261   DS:value:GAUGE:25:U:U
 262
 263 =item Serial port traffic (F<serial-I<E<lt>numE<gt>>.rrd>)
 264
 265   DS:incoming:COUNTER:25:0:U
 266   DS:outgoing:COUNTER:25:0:U
 267
 268 =item Swap usage (F<swap.rrd>)
 269
 270   DS:used:GAUGE:25:0:1099511627776
 271   DS:free:GAUGE:25:0:1099511627776
 272   DS:cached:GAUGE:25:0:1099511627776
 273   DS:resv:GAUGE:25:0:1099511627776
 274
 275 =item Tape drive usage (F<tape-I<E<lt>nameE<gt>>.rrd>)
 276
 277   DS:rcount:COUNTER:25:0:
 278   DS:rmerged:COUNTER:25:0:U
 279   DS:rbytes:COUNTER:25:0:U
 280   DS:rtime:COUNTER:25:0:U
 281   DS:wcount:COUNTER:25:0:U
 282   DS:wmerged:COUNTER:25:0:U
 283   DS:wbytes:COUNTER:25:0:U
 284   DS:wtime:COUNTER:25:0:U
 285
 286 =item Network traffic (F<traffic-I<E<lt>nameE<gt>>.rrd>)
 287
 288   DS:incoming:COUNTER:25:0:U
 289   DS:outgoing:COUNTER:25:0:U
 290
 291 =item Users (F<users.rrd>)
 292
 293   DS:users:GAUGE:25:0:65535
 294
 295 =back
 296
 297 =head1 MODES
 298
 299 By default collectd starts in the so called I<local mode> which is not very
 300 interesting. It collects data and writes it into RRD files in
 301 F</var/lib/collectd>. There's nothing special so I won't discuss that in more
 302 detail..
 303
 304 Please be aware that B<client-, local- and server-mode are mutual exclusive>. A
 305 later declaration overrides earlier ones. I<collectd -l -c -s> will start in
 306 server-mode. If you want statistics of the server too you will have to start a
 307 client process as well.
 308
 309 Starting with version 3 collectd may send data over a network. As common with
 310 network stuff there are two modes: A I<sender> and a I<listener>. Since one
 311 usually has many senders and only a few listeners the sender is also called
 312 I<client> (using the option B<-c>) and the listener is called I<server> (using
 313 the option B<-s>).
 314
 315 Communication happends using the (IPv4) multicast group B<239.192.74.66> and
 316 packets sent to the port B<25826/udp>. Every ten seconds the I<client> queries
 317 all the modules and sends the collected data to the multicast group. The
 318 I<server> subscribes to the multicast group upon startup and then waits for
 319 incoming packets. As it receives the packets it checks wether it has the
 320 neccessary module and, if found, writes the data to an RRD file, creating
 321 directories and files as needed.
 322
 323 The multicast group used is within the I<Organization Local Scope> as defined
 324 by L<RFC2365>. Addresses within that space are meant to be routed within an AS
 325 but not to the outside. However collectd cannot control this and won't try. So
 326 it's totally up to you to secure your net.
 327
 328 The UDP port used has been checked to not be assigned by the IANA.
 329
 330 On multi-homed machines you may need to add a route to the multicast net
 331 (B<224.0.0.0/4>) if multicast packages take the wrong interface. The listener
 332 on the other hand listens on B<all> interfaces.
 333
 334 =head1 SPECIAL PLUGINS
 335
 336 =head2 cpufreq
 337
 338 This module reads F</sys/devices/system/cpu/cpu0/cpufreq/cpuinfo_cur_freq> (for
 339 the first CPU installed) to get the current CPU frequency. If this file does
 340 not exist make sure B<cpufreqd> (L<http://cpufreqd.sourceforge.net/>) or a
 341 similar tool is installed.
 342
 343 =head2 mysql
 344
 345 Requires B<mysqlclient> to be installed. It connects to the database when
 346 started and keeps the connection up as long as possible. When the connection is
 347 interrupted for whatever reason it will try to re-connect. The syslog will
 348 contain loud complaints in case anything goes wrong.
 349
 350 This plugin issues C<SHOW STATUS> and evaluates C<Bytes_{received,sent}>,
 351 C<Com_*> and C<Handler_*> which correspond to F<traffic-mysql.rrd>,
 352 F<mysql_commands-*.rrd> and F<mysql_handler-*.rrd>. Also, the values of
 353 C<Qcache_*> are put in F<mysql_qcache.rrd> and values of C<Threads_*> are put
 354 in F<mysql_threads.rrd>. Please refer to the B<MySQL reference manual>,
 355 I<5.2.4. Server Status Variables> for an explanation of these values.
 356
 357 =head2 sensors
 358
 359 The B<sensors> module uses lm_sensors to retrieve sensor-values. This means
 360 that all the needed modules have to be loaded and lm_sensors has to be
 361 configured (most likely by editing F</etc/sensors.conf>. Read
 362 L<sensors.conf(5)> for details.
 363
 364 The B<lm_sensors> homepage can be found at
 365 L<http://secure.netroedge.com/~lm78/>.
 366
 367 =head2 hddtemp
 368
 369 To get values from B<hddtemp> collectd connects to B<localhost> (127.0.0.1),
 370 port B<7634/tcp>. hddtemp has to be running to work correctly. If hddtemp is
 371 not running timeouts may appear which may interfere with other statistics..
 372
 373 The B<hddtemp> homepage can be found at
 374 L<http://www.guzu.net/linux/hddtemp.php>.
 375
 376 =head1 SEE ALSO
 377
 378 L<collectd.conf(5)>, L<rrdtool(1)>, L<sensors(1)>, L<hddtemp(8)>,
 379 L<kstat(3KSTAT)>
 380
 381 =head1 AUTHOR
 382
 383 Florian Forster E<lt>octo@verplant.orgE<gt>
 384
 385 =cut