=head1 NAME

collectd - System statistics collection daemon

=head1 SYNOPSIS

collectd I<[options]>

=head1 DESCRIPTION

collectd is a daemon that collects various system statistics periodically and
stores them into RRD-files. Which data is collected depends on compile-time
settings. The following features may be available:

=over 4

=item

Apache server stats (I<apache>)

=item

Apple hardware sensors (I<apple_sensors>, Darwin only)

=item

Battery status (I<battery>)

=item

CPU utilization (I<cpu>)

=item

Mountpoint usage (I<df>)

=item

Disk and partition usage/throughput (I<disk>)

=item

Harddisk temperatures (I<hddtemp>)

=item

System load averages (I<load>)

=item

Memory usage (I<memory>)

=item

MySQL statistics (I<mysql>)

=item

NFS utilization (I<nfs>, Linux only)

=item

Network latency (I<ping>)

=item

Number of processes (I<processes>, Linux only)

=item

lm_sensors information (I<sensors>, Linux only)

=item

Serial port traffic (I<serial>, Linux only)

=item

Swap usage (I<swap>)

=item

Tape drive usage (I<tape>, Solaris only)

=item

Network traffic (I<traffic>)

=item

Number of users logged into the system (I<users>)

=item

System ressources used by VServers (I<vserver>)

=item

Wireless network stats (I<wireless>)

=back

=head1 OPTIONS

=over 4

=item B<-C> I<E<lt>config-fileE<gt>>

Specify an alternative config file. This is the place to go when you wish to
change B<collectd>'s behavior. The path may be relative to the current working
directory.

=item B<-f>

Don't fork to the background. I<collectd> will also B<not> close standard file
descriptors, detach from the session nor write a pid file. This is mainly
thought for 'supervisioning' init replacements such as I<runit>.

=item B<-h>

Output usage information and exit.

=back

=head1 MODES

collectd can operate in three different operating modes. The modes are
described below.

The simplest mode is the so called B<local mode>. Data is collected locally and
written in RRD files that reside in I<DataDir>. This is the default mode when
collectd is linked against C<librrd>.

The other modes, B<client mode> and B<server mode>, are used to send data over
a network and receive it again.

In B<client mode> the daemon collects the data locally and sends its results
to one or more network addresses. No RRD files are written in this case. This
is the only mode available if collectd is not linked against C<librrd>.

If started in B<server mode> the daemon will listen on one or more interfaces
and write the data it receives to RRD files. No data is collected locally.

In the last mode, B<log mode>, data is collected locally and written in
text files that reside in I<DataDir>.

Please refer to L<collectd.conf(5)> for the configuration options and default
values.

=head1 SPECIAL PLUGINS

=head2 apache

This module connects to an Apache webserver and expects the output produced by
B<mod_status.c>. If requires B<libcurl> to set up the HTTP connection and issue
the request(s). The following is a sample config for the Apache webserver. The
use of C<ExtendedStatus on> is mandatory.

  ExtendedStatus on
  <IfModule mod_status.c>
    <Location /mod_status>
      SetHandler server-status
    </Location>
  </IfModule>

This plugin requires further configuration. Please read L<collectd.conf(5)>.

=head2 cpufreq

This module reads F</sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq> (for
the first CPU installed) to get the current CPU frequency. If this file does
not exist make sure B<cpufreqd> (L<http://cpufreqd.sourceforge.net/>) or a
similar tool is installed and an "cpu governor" (that's kernel module) is
loaded.

=head2 mysql

Requires B<mysqlclient> to be installed. It connects to the database when
started and keeps the connection up as long as possible. When the connection is
interrupted for whatever reason it will try to re-connect. The syslog will
contain loud complaints in case anything goes wrong.

This plugin issues C<SHOW STATUS> and evaluates C<Bytes_{received,sent}>,
C<Com_*> and C<Handler_*> which correspond to F<traffic-mysql.rrd>,
F<mysql_commands-*.rrd> and F<mysql_handler-*.rrd>. Also, the values of
C<Qcache_*> are put in F<mysql_qcache.rrd> and values of C<Threads_*> are put
in F<mysql_threads.rrd>. Please refer to the B<MySQL reference manual>,
I<5.2.4. Server Status Variables> for an explanation of these values.

=head2 sensors

The B<sensors> module uses lm_sensors to retrieve sensor-values. This means
that all the needed modules have to be loaded and lm_sensors has to be
configured (most likely by editing F</etc/sensors.conf>. Read
L<sensors.conf(5)> for details.

The B<lm_sensors> homepage can be found at
L<http://secure.netroedge.com/~lm78/>.

=head2 hddtemp

To get values from B<hddtemp> collectd connects to B<localhost> (127.0.0.1),
port B<7634/tcp>. The B<Host> and B<Port> options can be used to change these
default values. See L<collectd.conf(5)> for details. C<hddtemp> has to be
running to work correctly. If C<hddtemp> is not running timeouts may appear
which may interfere with other statistics..

The B<hddtemp> homepage can be found at
L<http://www.guzu.net/linux/hddtemp.php>.

=head2 vserver

B<VServer> support is only available for Linux. It cannot yet be found in a 
vanilla kernel, though. To make use of this plugin you need a kernel that has 
B<VServer> support built in, i.e. you need to apply the patches and compile 
your own kernel, which will then provide the /proc/virtual filesystem that is
required by this plugin.

The B<VServer> homepage can be found at L<http://linux-vserver.org/>.

=head1 RRD FILES

The RRD files are created automatically. The size of the RRAs depend on the
compile time settings of I<step> and I<width>. With the default values (I<step>
= B<10>, I<width> = B<1200>) the following RRAs are created:

  RRA:AVERAGE:0.1:1:8640
  RRA:AVERAGE:0.1:50:1210
  RRA:AVERAGE:0.1:223:1202
  RRA:AVERAGE:0.1:2635:1201
  RRA:MIN:0.1:1:8640
  RRA:MIN:0.1:50:1210
  RRA:MIN:0.1:223:1202
  RRA:MIN:0.1:2635:1201
  RRA:MAX:0.1:1:8640
  RRA:MAX:0.1:50:1210
  RRA:MAX:0.1:223:1202
  RRA:MAX:0.1:2635:1201

By default collectd uses a 10 second I<step>. Thus the RRAs contain the
following timespans. If you've changed the I<step> at compile time you will
have calculate resolution and timespan yourself.

  PDP per CDP |  Resolution  | Data points | Timespan
  ------------+--------------+-------------+---------
            1 | 10.0 seconds !        8640 ! 1 day
           50 |  8.3 minutes |        1210 | 1 week
          223 | 37.2 minutes |        1202 | 1 month
         2635 |  7.3 hours   |        1201 | 1 year

The DS'es depend on the module creating the RRD files:

=over 4

=item Battery charge (F<battery-I<E<lt>nameE<gt>>/charge.rrd>)

  DS:charge:GAUGE:25:0:U

=item Battery current (F<battery-I<E<lt>nameE<gt>>/current.rrd>)

  DS:current:GAUGE:25:U:U

=item Battery voltage (F<battery-I<E<lt>nameE<gt>>/voltage.rrd>)

  DS:voltage:GAUGE:25:U:U

=item CPU (F<cpu-I<E<lt>numE<gt>>.rrd>)

  DS:user:COUNTER:25:0:100
  DS:nice:COUNTER:25:0:100
  DS:syst:COUNTER:25:0:100
  DS:idle:COUNTER:25:0:100
  DS:wait:COUNTER:25:0:100

=item Mountpoints (F<df-I<E<lt>pathE<gt>>.rrd>)

  DS:used:GAUGE:25:0:U
  DS:free:GAUGE:25:0:U

=item Diskstats (F<disk-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)

  DS:rcount:COUNTER:25:0:U
  DS:rmerged:COUNTER:25:0:U
  DS:rbytes:COUNTER:25:0:U
  DS:rtime:COUNTER:25:0:U
  DS:wcount:COUNTER:25:0:U
  DS:wmerged:COUNTER:25:0:U
  DS:wbytes:COUNTER:25:0:U
  DS:wtime:COUNTER:25:0:U

=item Diskstats (F<partition-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)

  DS:rcount:COUNTER:25:0:U
  DS:rbytes:COUNTER:25:0:U
  DS:wcount:COUNTER:25:0:U
  DS:wbytes:COUNTER:25:0:U

=item HDD Temperature (F<hddtemp-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)

  DS:value:GAUGE:25:U:U

=item System load (F<load.rrd>)

  DS:shortterm:GAUGE:25:0:100
  DS:midterm:GAUGE:25:0:100
  DS:longterm:GAUGE:25:0:100

=item Memory usage (F<memory.rrd>)

  DS:used:GAUGE:25:0:9223372036854775807
  DS:free:GAUGE:25:0:9223372036854775807
  DS:buffers:GAUGE:25:0:9223372036854775807
  DS:cached:GAUGE:25:0:9223372036854775807

=item MySQL commands and handlers (F<mysql_commands-I<E<lt>commandE<gt>>.rrd> and F<mysql_handler-I<E<lt>handlerE<gt>>.rrd>)

  DS:value:COUNTER:25:0:U

=item MySQL query cache (F<mysql_qcache.rrd>)

  DS:hits:COUNTER:25:0:U
  DS:inserts:COUNTER:25:0:U
  DS:not_cached:COUNTER:25:0:U
  DS:lowmem_prunes:COUNTER:25:0:U
  DS:queries_in_cache:GAUGE:25:0:U

=item MySQL threads (F<mysql_threads.rrd>)

  DS:running:GAUGE:25:0:U
  DS:connected:GAUGE:25:0:U
  DS:cached:GAUGE:25:0:U
  DS:created:COUNTER:25:0:U

=item NFSv2 Procedures (F<nfs2_procedures-I<(client|server)>.rrd>)

  DS:null:COUNTER:25:0:U
  DS:getattr:COUNTER:25:0:U
  DS:setattr:COUNTER:25:0:U
  DS:root:COUNTER:25:0:U
  DS:lookup:COUNTER:25:0:U
  DS:readlink:COUNTER:25:0:U
  DS:read:COUNTER:25:0:U
  DS:wrcache:COUNTER:25:0:U
  DS:write:COUNTER:25:0:U
  DS:create:COUNTER:25:0:U
  DS:remove:COUNTER:25:0:U
  DS:rename:COUNTER:25:0:U
  DS:link:COUNTER:25:0:U
  DS:symlink:COUNTER:25:0:U
  DS:mkdir:COUNTER:25:0:U
  DS:rmdir:COUNTER:25:0:U
  DS:readdir:COUNTER:25:0:U
  DS:fsstat:COUNTER:25:0:U

=item NFSv3 Procedures (F<nfs3_procedures-I<(client|server)>.rrd>)

  DS:null:COUNTER:25:0:U
  DS:getattr:COUNTER:25:0:U
  DS:setattr:COUNTER:25:0:U
  DS:lookup:COUNTER:25:0:U
  DS:access:COUNTER:25:0:U
  DS:readlink:COUNTER:25:0:U
  DS:read:COUNTER:25:0:U
  DS:write:COUNTER:25:0:U
  DS:create:COUNTER:25:0:U
  DS:mkdir:COUNTER:25:0:U
  DS:symlink:COUNTER:25:0:U
  DS:mknod:COUNTER:25:0:U
  DS:remove:COUNTER:25:0:U
  DS:rmdir:COUNTER:25:0:U
  DS:rename:COUNTER:25:0:U
  DS:link:COUNTER:25:0:U
  DS:readdir:COUNTER:25:0:U
  DS:readdirplus:COUNTER:25:0:U
  DS:fsstat:COUNTER:25:0:U
  DS:fsinfo:COUNTER:25:0:U
  DS:pathconf:COUNTER:25:0:U
  DS:commit:COUNTER:25:0:U

=item Network latency / Ping (F<ping-I<E<lt>hostnameE<gt>>.rrd>)

  DS:ping:GAUGE:25:0:65535

=item Processes (F<processes.rrd>)

  DS:running:GAUGE:25:0:65535
  DS:sleeping:GAUGE:25:0:65535
  DS:zombies:GAUGE:25:0:65535
  DS:stopped:GAUGE:25:0:65535
  DS:paging:GAUGE:25:0:65535
  DS:blocked:GAUGE:25:0:65535

=item lm_sensors (F<sensors-I<E<lt>chipE<gt>>-I<E<lt>featureE<gt>>.rrd>)

  DS:value:GAUGE:25:U:U

=item Serial port traffic (F<serial-I<E<lt>numE<gt>>.rrd>)

  DS:incoming:COUNTER:25:0:U
  DS:outgoing:COUNTER:25:0:U

=item Swap usage (F<swap.rrd>)

  DS:used:GAUGE:25:0:1099511627776
  DS:free:GAUGE:25:0:1099511627776
  DS:cached:GAUGE:25:0:1099511627776
  DS:resv:GAUGE:25:0:1099511627776

=item Tape drive usage (F<tape-I<E<lt>nameE<gt>>.rrd>)

  DS:rcount:COUNTER:25:0:
  DS:rmerged:COUNTER:25:0:U
  DS:rbytes:COUNTER:25:0:U
  DS:rtime:COUNTER:25:0:U
  DS:wcount:COUNTER:25:0:U
  DS:wmerged:COUNTER:25:0:U
  DS:wbytes:COUNTER:25:0:U
  DS:wtime:COUNTER:25:0:U

=item Network traffic (F<traffic-I<E<lt>nameE<gt>>.rrd>)

  DS:incoming:COUNTER:25:0:U
  DS:outgoing:COUNTER:25:0:U

=item Users (F<users.rrd>)

  DS:users:GAUGE:25:0:65535

=item VServer load (F<vserver-I<E<lt>xidE<gt>>/load.rrd>)

  DS:shortterm:GAUGE:25:0:100
  DS:midterm:GAUGE:25:0:100
  DS:longterm:GAUGE:25:0:100

=item VServer threads (F<vserver-I<E<lt>xidE<gt>>/threads.rrd>)

  DS:total:GAUGE:25:0:65535
  DS:running:GAUGE:25:0:65535
  DS:uninterruptible:GAUGE:25:0:65535
  DS:onhold:GAUGE:25:0:65535

=item VServer network traffic (F<vserver-I<E<lt>xidE<gt>>/traffic-I<E<lt>nameE<gt>>.rrd>)

  DS:incoming:COUNTER:25:0:9223372036854775807
  DS:outgoing:COUNTER:25:0:9223372036854775807
  DS:failed:COUNTER:25:0:9223372036854775807

=item VServer processes (F<vserver-I<E<lt>xidE<gt>>/vs_processes.rrd>)

  DS:total:GAUGE:25:0:65535

=item VServer memory usage (F<vserver-I<E<lt>xidE<gt>>/vs_memory.rrd>)

  DS:vm:GAUGE:25:0:9223372036854775807
  DS:vml:GAUGE:25:0:9223372036854775807
  DS:rss:GAUGE:25:0:9223372036854775807
  DS:anon:GAUGE:25:0:9223372036854775807

=back

=head1 SEE ALSO

L<collectd.conf(5)>, L<rrdtool(1)>, L<sensors(1)>, L<hddtemp(8)>,
L<kstat(3KSTAT)>

=head1 AUTHOR

Florian Forster E<lt>octo@verplant.orgE<gt>

=cut