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 commands and handlers (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 MySQL query cache (F<mysql_qcache.rrd>)
 201
 202   DS:hits:COUNTER:25:0:U
 203   DS:inserts:COUNTER:25:0:U
 204   DS:not_cached:COUNTER:25:0:U
 205   DS:lowmem_prunes:COUNTER:25:0:U
 206   DS:queries_in_cache:GAUGE:25:0:U
 207
 208 =item MySQL threads (F<mysql_threads.rrd>)
 209
 210   DS:running:GAUGE:25:0:U
 211   DS:connected:GAUGE:25:0:U
 212   DS:cached:GAUGE:25:0:U
 213   DS:created:COUNTER:25:0:U
 214
 215 =item NFSv2 Procedures (F<nfs2_procedures-I<(client|server)>.rrd>)
 216
 217   DS:null:COUNTER:25:0:U
 218   DS:getattr:COUNTER:25:0:U
 219   DS:setattr:COUNTER:25:0:U
 220   DS:root:COUNTER:25:0:U
 221   DS:lookup:COUNTER:25:0:U
 222   DS:readlink:COUNTER:25:0:U
 223   DS:read:COUNTER:25:0:U
 224   DS:wrcache:COUNTER:25:0:U
 225   DS:write:COUNTER:25:0:U
 226   DS:create:COUNTER:25:0:U
 227   DS:remove:COUNTER:25:0:U
 228   DS:rename:COUNTER:25:0:U
 229   DS:link:COUNTER:25:0:U
 230   DS:symlink:COUNTER:25:0:U
 231   DS:mkdir:COUNTER:25:0:U
 232   DS:rmdir:COUNTER:25:0:U
 233   DS:readdir:COUNTER:25:0:U
 234   DS:fsstat:COUNTER:25:0:U
 235
 236 =item NFSv3 Procedures (F<nfs3_procedures-I<(client|server)>.rrd>)
 237
 238   DS:null:COUNTER:25:0:U
 239   DS:getattr:COUNTER:25:0:U
 240   DS:setattr:COUNTER:25:0:U
 241   DS:lookup:COUNTER:25:0:U
 242   DS:access:COUNTER:25:0:U
 243   DS:readlink:COUNTER:25:0:U
 244   DS:read:COUNTER:25:0:U
 245   DS:write:COUNTER:25:0:U
 246   DS:create:COUNTER:25:0:U
 247   DS:mkdir:COUNTER:25:0:U
 248   DS:symlink:COUNTER:25:0:U
 249   DS:mknod:COUNTER:25:0:U
 250   DS:remove:COUNTER:25:0:U
 251   DS:rmdir:COUNTER:25:0:U
 252   DS:rename:COUNTER:25:0:U
 253   DS:link:COUNTER:25:0:U
 254   DS:readdir:COUNTER:25:0:U
 255   DS:readdirplus:COUNTER:25:0:U
 256   DS:fsstat:COUNTER:25:0:U
 257   DS:fsinfo:COUNTER:25:0:U
 258   DS:pathconf:COUNTER:25:0:U
 259   DS:commit:COUNTER:25:0:U
 260
 261 =item Network latency / Ping (F<ping-I<E<lt>hostnameE<gt>>.rrd>)
 262
 263   DS:ping:GAUGE:25:0:65535
 264
 265 =item Processes (F<processes.rrd>)
 266
 267   DS:running:GAUGE:25:0:65535
 268   DS:sleeping:GAUGE:25:0:65535
 269   DS:zombies:GAUGE:25:0:65535
 270   DS:stopped:GAUGE:25:0:65535
 271   DS:paging:GAUGE:25:0:65535
 272   DS:blocked:GAUGE:25:0:65535
 273
 274 =item lm_sensors (F<sensors-I<E<lt>chipE<gt>>-I<E<lt>featureE<gt>>.rrd>)
 275
 276   DS:value:GAUGE:25:U:U
 277
 278 =item Serial port traffic (F<serial-I<E<lt>numE<gt>>.rrd>)
 279
 280   DS:incoming:COUNTER:25:0:U
 281   DS:outgoing:COUNTER:25:0:U
 282
 283 =item Swap usage (F<swap.rrd>)
 284
 285   DS:used:GAUGE:25:0:1099511627776
 286   DS:free:GAUGE:25:0:1099511627776
 287   DS:cached:GAUGE:25:0:1099511627776
 288   DS:resv:GAUGE:25:0:1099511627776
 289
 290 =item Tape drive usage (F<tape-I<E<lt>nameE<gt>>.rrd>)
 291
 292   DS:rcount:COUNTER:25:0:
 293   DS:rmerged:COUNTER:25:0:U
 294   DS:rbytes:COUNTER:25:0:U
 295   DS:rtime:COUNTER:25:0:U
 296   DS:wcount:COUNTER:25:0:U
 297   DS:wmerged:COUNTER:25:0:U
 298   DS:wbytes:COUNTER:25:0:U
 299   DS:wtime:COUNTER:25:0:U
 300
 301 =item Network traffic (F<traffic-I<E<lt>nameE<gt>>.rrd>)
 302
 303   DS:incoming:COUNTER:25:0:U
 304   DS:outgoing:COUNTER:25:0:U
 305
 306 =item Users (F<users.rrd>)
 307
 308   DS:users:GAUGE:25:0:65535
 309
 310 =back
 311
 312 =head1 MODES
 313
 314 By default collectd starts in the so called I<local mode> which is not very
 315 interesting. It collects data and writes it into RRD files in
 316 F</var/lib/collectd>. There's nothing special so I won't discuss that in more
 317 detail..
 318
 319 Please be aware that B<client-, local- and server-mode are mutual exclusive>. A
 320 later declaration overrides earlier ones. I<collectd -l -c -s> will start in
 321 server-mode. If you want statistics of the server too you will have to start a
 322 client process as well.
 323
 324 Starting with version 3 collectd may send data over a network. As common with
 325 network stuff there are two modes: A I<sender> and a I<listener>. Since one
 326 usually has many senders and only a few listeners the sender is also called
 327 I<client> (using the option B<-c>) and the listener is called I<server> (using
 328 the option B<-s>).
 329
 330 Communication happends using the (IPv4) multicast group B<239.192.74.66> and
 331 packets sent to the port B<25826/udp>. Every ten seconds the I<client> queries
 332 all the modules and sends the collected data to the multicast group. The
 333 I<server> subscribes to the multicast group upon startup and then waits for
 334 incoming packets. As it receives the packets it checks wether it has the
 335 neccessary module and, if found, writes the data to an RRD file, creating
 336 directories and files as needed.
 337
 338 The multicast group used is within the I<Organization Local Scope> as defined
 339 by L<RFC2365>. Addresses within that space are meant to be routed within an AS
 340 but not to the outside. However collectd cannot control this and won't try. So
 341 it's totally up to you to secure your net.
 342
 343 The UDP port used has been checked to not be assigned by the IANA.
 344
 345 On multi-homed machines you may need to add a route to the multicast net
 346 (B<224.0.0.0/4>) if multicast packages take the wrong interface. The listener
 347 on the other hand listens on B<all> interfaces.
 348
 349 =head1 SPECIAL PLUGINS
 350
 351 =head2 cpufreq
 352
 353 This module reads F</sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq> (for
 354 the first CPU installed) to get the current CPU frequency. If this file does
 355 not exist make sure B<cpufreqd> (L<http://cpufreqd.sourceforge.net/>) or a
 356 similar tool is installed.
 357
 358 =head2 mysql
 359
 360 Requires B<mysqlclient> to be installed. It connects to the database when
 361 started and keeps the connection up as long as possible. When the connection is
 362 interrupted for whatever reason it will try to re-connect. The syslog will
 363 contain loud complaints in case anything goes wrong.
 364
 365 This plugin issues C<SHOW STATUS> and evaluates C<Bytes_{received,sent}>,
 366 C<Com_*> and C<Handler_*> which correspond to F<traffic-mysql.rrd>,
 367 F<mysql_commands-*.rrd> and F<mysql_handler-*.rrd>. Also, the values of
 368 C<Qcache_*> are put in F<mysql_qcache.rrd> and values of C<Threads_*> are put
 369 in F<mysql_threads.rrd>. Please refer to the B<MySQL reference manual>,
 370 I<5.2.4. Server Status Variables> for an explanation of these values.
 371
 372 =head2 sensors
 373
 374 The B<sensors> module uses lm_sensors to retrieve sensor-values. This means
 375 that all the needed modules have to be loaded and lm_sensors has to be
 376 configured (most likely by editing F</etc/sensors.conf>. Read
 377 L<sensors.conf(5)> for details.
 378
 379 The B<lm_sensors> homepage can be found at
 380 L<http://secure.netroedge.com/~lm78/>.
 381
 382 =head2 hddtemp
 383
 384 To get values from B<hddtemp> collectd connects to B<localhost> (127.0.0.1),
 385 port B<7634/tcp>. The B<Host> and B<Port> options can be used to change these
 386 default values. See L<collectd.conf(5)> for details. C<hddtemp> has to be
 387 running to work correctly. If C<hddtemp> is not running timeouts may appear
 388 which may interfere with other statistics..
 389
 390 The B<hddtemp> homepage can be found at
 391 L<http://www.guzu.net/linux/hddtemp.php>.
 392
 393 =head1 SEE ALSO
 394
 395 L<collectd.conf(5)>, L<rrdtool(1)>, L<sensors(1)>, L<hddtemp(8)>,
 396 L<kstat(3KSTAT)>
 397
 398 =head1 AUTHOR
 399
 400 Florian Forster E<lt>octo@verplant.orgE<gt>
 401
 402 =cut