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