=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 and lighttpd server statistics (I) =item Apple hardware sensors (I, Darwin only) =item Battery status (I) =item CPU utilization (I) =item Mountpoint usage (I) =item Disk and partition usage/throughput (I) =item DNS traffic (I) =item Email usage (I) =item Harddisk temperatures (I) =item Irq (I) =item System load averages (I) =item Motherboard monitor (I) =item Memory usage (I) =item MySQL statistics (I) =item NFS utilization (I, Linux only) =item Embedded Perl interpreter (I) =item Network latency (I) =item Number of processes (I, Linux only) =item lm_sensors information (I, Linux only) =item Serial port traffic (I, Linux only) =item Swap usage (I) =item Tape drive usage (I, Solaris only) =item Network traffic (I) =item Number of users logged into the system (I) =item System ressources used by VServers (I) =item Wireless network stats (I) =back =head1 OPTIONS =over 4 =item B<-C> Iconfig-fileE> Specify an alternative config file. This is the place to go when you wish to change B's behavior. The path may be relative to the current working directory. =item B<-P> Ipid-fileE> Specify an alternative pid file. This overwrites any settings in the config file. This is thought for init-scripts that require the PID-file in a certain directory to work correctly. For everyday-usage use the B config-option. =item B<-f> Don't fork to the background. I will also B close standard file descriptors, detach from the session nor write a pid file. This is mainly thought for 'supervisioning' init replacements such as I. =item B<-h> Output usage information and exit. =back =head1 MODES collectd can operate in four different operating modes. The modes are described below. The simplest mode is the so called B. Data is collected locally and written in RRD files that reside in I. This is the default mode when collectd is linked against C. The modes B and B are used to send data over a network and receive it again. In B the daemon collects the data locally and sends its results to one or more network addresses. No RRD files are written locally in this case. If collectd is not linked against C this is the default mode. If started in B 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, data is collected locally and written in text files that reside in I. Please refer to L for the configuration options and default values. =head1 SPECIAL PLUGINS =head2 apache This module connects to an Apache or lighttpd webserver and expects the output produced by B. If requires B to set up the HTTP connection and issue the request(s). The following is a sample config for the Apache webserver. Under Apache, the use of C is mandatory. ExtendedStatus on SetHandler server-status This plugin requires further configuration. Please read L. =head2 cpufreq This module reads F (for the first CPU installed) to get the current CPU frequency. If this file does not exist make sure B (L) or a similar tool is installed and an "cpu governor" (that's kernel module) is loaded. =head2 email This plugin collects data indirectly by providing a UNIX socket that external programs can connect to. A simple line based protocol is used to communicate with the plugin: E-Mail type (e.g. "ham", "spam", "virus", ...) and size (bytes): e:: If C is less than or equal to zero, C is ignored. Spam score: s: Successful spam checks (e.g. "BAYES_99", "SUBJECT_DRUG_GAP_C", ...): c:[,,...] Each line is limited to 256 characters (including the newline character). Longer lines will be ignored. =head2 exec The C plugin forks of an executable and reads back values that it writes to C. The executable is forked kind of as L does: It is forked once and not again until it exits. If it exited, it will be forked again after at most I seconds. It is perfectly legal for the executable to run for a long time and continuously write values to C. The forked executable is expected to print values to C. The expected format is as follows: =over 4 =item Each line beginning with a C<#> (hash mark) is ignored. =item Any other line must be of the form C,I,I>, where I is either B or B, I may not contain C<,> (comma), C (slash) and C<\0> (null byte) and I is either an integer (if I is B) or a floating-point number (if I is B). =back The values are always considered to be "fresh", i.Ee. the time is set to "now". When collectd exits it sends a B to all still running child-processes upon which they have to quit. =head2 mysql Requires B 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 and evaluates C, C and C which correspond to F, F and F. Also, the values of C are put in F and values of C are put in F. Please refer to the B, I<5.2.4. Server Status Variables> for an explanation of these values. =head2 perl The C includes a Perl-interpreter in collectd and provides Perl-equivalents of the plugin-functions. This makes it possible to write plugins in Perl. There are two more complex types you need to know about: =over 4 =item Data-Set A data-set is a list of one or more data-sources. Each data-source defines a name, type, min- and max-value and the data-set wraps them up into one structure. The general layout looks like this: [{ name => 'data_source_name', type => DS_TYPE_COUNTER || DS_TYPE_GAUGE min => value || undef, max => value || undef }, ...] =item Value-List A value-list is one structure which features an array of values and fields to identify the values, i. e. time and host, plugin name and plugin-instance as well as a type and type-instance. Since the "type" is not included in the value-list but is passed as an extra argument, the general layout looks like this: { values => [123, 0.5], time => time (), host => 'localhost', plugin => 'myplugin', plugin_instance => '', type_instance => '' } =back The following functions provide the C-interface to Perl-modules: =over 4 =item B (I, I, I) Registers a callback-function or data-set. I can be one of: =over 4 =item TYPE_INIT =item TYPE_READ =item TYPE_WRITE =item TYPE_LOG =item TYPE_SHUTDOWN =item TYPE_DATASET =back I is the name of the callback-function or the type of the data-set, depending on the value of I. (Please note that the type of the data-set is the value passed as I here and has nothing to do with the I argument which simply tells B what is being registered.) The last argument, I, is either a function- or an array-reference. If I is B, then the I argument must be an array-reference which points to an array of hashes. Each hash describes one data-source. For the exact layout see B above. If the I argument is any of the other types (B, B, ...) then I is expected to be a function reference. These functions are called in the various stages of the daemon and are passed the following arguments: =over 4 =item TYPE_INIT =item TYPE_READ =item TYPE_SHUTDOWN No arguments are passed =item TYPE_WRITE The arguments passed are I, I, and I. I is a string. For the layout of I and I see above. =item TYPE_LOG The arguments are I and I. The log level is small for important messages and high for less important messages. The least important level is B, the most important level is B. In between there are (from least to most important): B, B, and B. I is simply a string B a newline at the end. =back =item B (I, I) Removes a callback or data-set from collectd's internal list of functionsE/ datasets. =item B (I, I) Submits a I of type I to the daemon. If the data-set I is found (and the number of values matches the number of data-sources) then the type, data-set and value-list is passed to all write-callbacks that are registered with the daemon. =item B (I, I) Submits a I of level I to collectd's logging mechanism. The message is passed to all log-callbacks that are registered with collectd. =back =head2 sensors The B 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. Read L for details. The B homepage can be found at L. =head2 mbmon The B module uses mbmon to retrieve temperature, voltage, etc. collectd connects to B (127.0.0.1), port B<411/tcp>. The B and B options can be used to change these default values. See L for details. C has to be running to work correctly. If C is not running timeouts may appear which may interfere with other statistics.. C must be run with the -r option ("print TAG and Value format"); Debian's /etc/init.d/mbmon script already does this, other people will need to ensure that this is the case. =head2 hddtemp To get values from B collectd connects to B (127.0.0.1), port B<7634/tcp>. The B and B options can be used to change these default values. See L for details. C has to be running to work correctly. If C is not running timeouts may appear which may interfere with other statistics.. The B homepage can be found at L. =head2 vserver B 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 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 homepage can be found at L. =head1 RRD FILES The RRD files are created automatically. The size of the RRAs depend on the compile time settings of I and I. With the default values (I = B<10>, I = 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. Thus the RRAs contain the following timespans. If you've changed the I 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 Apache traffic (F) DS:count:COUNTER:HEARTBEAT:0:134217728 =item Apache requests (F) DS:count:COUNTER:HEARTBEAT:0:1048576 =item Apache scoreboard (FnameE>.rrd>) DS:count:GAUGE:HEARTBEAT:0:U =item Apple temperature sensor (FnameE>.rrd>) DS:value:GAUGE:HEARTBEAT:U:U =item Apple fanspeed sensor (FnameE>.rrd>) DS:value:GAUGE:HEARTBEAT:U:U =item Battery charge (FnameE>/charge.rrd>) DS:charge:GAUGE:HEARTBEAT:0:U =item Battery current (FnameE>/current.rrd>) DS:current:GAUGE:HEARTBEAT:U:U =item Battery voltage (FnameE>/voltage.rrd>) DS:voltage:GAUGE:HEARTBEAT:U:U =item CPU (FnumE>.rrd>) DS:user:COUNTER:HEARTBEAT:0:100 DS:nice:COUNTER:HEARTBEAT:0:100 DS:syst:COUNTER:HEARTBEAT:0:100 DS:idle:COUNTER:HEARTBEAT:0:100 DS:wait:COUNTER:HEARTBEAT:0:100 =item CPU frequency (FnumE>.rrd>) DS:value:GAUGE:HEARTBEAT:0:U =item Mountpoints (FpathE>.rrd>) DS:used:GAUGE:HEARTBEAT:0:U DS:free:GAUGE:HEARTBEAT:0:U =item Diskstats (FmajorE>-IminorE>.rrd>) DS:rcount:COUNTER:HEARTBEAT:0:U DS:rmerged:COUNTER:HEARTBEAT:0:U DS:rbytes:COUNTER:HEARTBEAT:0:U DS:rtime:COUNTER:HEARTBEAT:0:U DS:wcount:COUNTER:HEARTBEAT:0:U DS:wmerged:COUNTER:HEARTBEAT:0:U DS:wbytes:COUNTER:HEARTBEAT:0:U DS:wtime:COUNTER:HEARTBEAT:0:U =item Diskstats (FmajorE>-IminorE>.rrd>) DS:rcount:COUNTER:HEARTBEAT:0:U DS:rbytes:COUNTER:HEARTBEAT:0:U DS:wcount:COUNTER:HEARTBEAT:0:U DS:wbytes:COUNTER:HEARTBEAT:0:U =item E-Mail count (FtypeE>.rrd>) DS:count:GAUGE:HEARTBEAT:0:U =item E-Mail size (FtypeE>.rrd>) DS:size:GAUGE:HEARTBEAT:0:U =item HDD Temperature (FmajorE>-IminorE>.rrd>) DS:value:GAUGE:HEARTBEAT:U:U =item Irq (FirqnumberE>.rrd>) DS:value:COUNTER:HEARTBEAT:0:65535 =item System load (F) DS:shortterm:GAUGE:HEARTBEAT:0:100 DS:midterm:GAUGE:HEARTBEAT:0:100 DS:longterm:GAUGE:HEARTBEAT:0:100 =item Memory usage (F) DS:used:GAUGE:HEARTBEAT:0:9223372036854775807 DS:free:GAUGE:HEARTBEAT:0:9223372036854775807 DS:buffers:GAUGE:HEARTBEAT:0:9223372036854775807 DS:cached:GAUGE:HEARTBEAT:0:9223372036854775807 =item MySQL commands and handlers (FcommandE>.rrd> and FhandlerE>.rrd>) DS:value:COUNTER:HEARTBEAT:0:U =item MySQL query cache (F) DS:hits:COUNTER:HEARTBEAT:0:U DS:inserts:COUNTER:HEARTBEAT:0:U DS:not_cached:COUNTER:HEARTBEAT:0:U DS:lowmem_prunes:COUNTER:HEARTBEAT:0:U DS:queries_in_cache:GAUGE:HEARTBEAT:0:U =item MySQL threads (F) DS:running:GAUGE:HEARTBEAT:0:U DS:connected:GAUGE:HEARTBEAT:0:U DS:cached:GAUGE:HEARTBEAT:0:U DS:created:COUNTER:HEARTBEAT:0:U =item NFSv2 Procedures (F.rrd>) DS:null:COUNTER:HEARTBEAT:0:U DS:getattr:COUNTER:HEARTBEAT:0:U DS:setattr:COUNTER:HEARTBEAT:0:U DS:root:COUNTER:HEARTBEAT:0:U DS:lookup:COUNTER:HEARTBEAT:0:U DS:readlink:COUNTER:HEARTBEAT:0:U DS:read:COUNTER:HEARTBEAT:0:U DS:wrcache:COUNTER:HEARTBEAT:0:U DS:write:COUNTER:HEARTBEAT:0:U DS:create:COUNTER:HEARTBEAT:0:U DS:remove:COUNTER:HEARTBEAT:0:U DS:rename:COUNTER:HEARTBEAT:0:U DS:link:COUNTER:HEARTBEAT:0:U DS:symlink:COUNTER:HEARTBEAT:0:U DS:mkdir:COUNTER:HEARTBEAT:0:U DS:rmdir:COUNTER:HEARTBEAT:0:U DS:readdir:COUNTER:HEARTBEAT:0:U DS:fsstat:COUNTER:HEARTBEAT:0:U =item NFSv3 Procedures (F.rrd>) DS:null:COUNTER:HEARTBEAT:0:U DS:getattr:COUNTER:HEARTBEAT:0:U DS:setattr:COUNTER:HEARTBEAT:0:U DS:lookup:COUNTER:HEARTBEAT:0:U DS:access:COUNTER:HEARTBEAT:0:U DS:readlink:COUNTER:HEARTBEAT:0:U DS:read:COUNTER:HEARTBEAT:0:U DS:write:COUNTER:HEARTBEAT:0:U DS:create:COUNTER:HEARTBEAT:0:U DS:mkdir:COUNTER:HEARTBEAT:0:U DS:symlink:COUNTER:HEARTBEAT:0:U DS:mknod:COUNTER:HEARTBEAT:0:U DS:remove:COUNTER:HEARTBEAT:0:U DS:rmdir:COUNTER:HEARTBEAT:0:U DS:rename:COUNTER:HEARTBEAT:0:U DS:link:COUNTER:HEARTBEAT:0:U DS:readdir:COUNTER:HEARTBEAT:0:U DS:readdirplus:COUNTER:HEARTBEAT:0:U DS:fsstat:COUNTER:HEARTBEAT:0:U DS:fsinfo:COUNTER:HEARTBEAT:0:U DS:pathconf:COUNTER:HEARTBEAT:0:U DS:commit:COUNTER:HEARTBEAT:0:U =item Network latency / Ping (FhostnameE>.rrd>) DS:ping:GAUGE:HEARTBEAT:0:65535 =item Processes (F) DS:running:GAUGE:HEARTBEAT:0:65535 DS:sleeping:GAUGE:HEARTBEAT:0:65535 DS:zombies:GAUGE:HEARTBEAT:0:65535 DS:stopped:GAUGE:HEARTBEAT:0:65535 DS:paging:GAUGE:HEARTBEAT:0:65535 DS:blocked:GAUGE:HEARTBEAT:0:65535 =item lm_sensors fanspeed sensor (FinstE>.rrd> or FchipE>/fanspeed-IinstE>.rrd>) DS:value:GAUGE:HEARTBEAT:U:U =item lm_sensors temperature sensor (FinstE>.rrd> or FchipE>/temperature-IinstE>.rrd>) DS:value:GAUGE:HEARTBEAT:U:U =item lm_sensors voltage sensor (FinstE>.rrd> or FchipE>/voltage-IinstE>.rrd>) DS:voltage:GAUGE:HEARTBEAT:U:U =item Serial port traffic (FnumE>.rrd>) DS:incoming:COUNTER:HEARTBEAT:0:U DS:outgoing:COUNTER:HEARTBEAT:0:U =item Spam score (F) DS:score:GAUGE:HEARTBEAT:0:U =item Spam checks (FtypeE>.rrd>) DS:hits:GAUGE:HEARTBEAT:0:U =item Swap usage (F) DS:used:GAUGE:HEARTBEAT:0:1099511627776 DS:free:GAUGE:HEARTBEAT:0:1099511627776 DS:cached:GAUGE:HEARTBEAT:0:1099511627776 DS:resv:GAUGE:HEARTBEAT:0:1099511627776 =item Tape drive usage (FnameE>.rrd>) DS:rcount:COUNTER:HEARTBEAT:0: DS:rmerged:COUNTER:HEARTBEAT:0:U DS:rbytes:COUNTER:HEARTBEAT:0:U DS:rtime:COUNTER:HEARTBEAT:0:U DS:wcount:COUNTER:HEARTBEAT:0:U DS:wmerged:COUNTER:HEARTBEAT:0:U DS:wbytes:COUNTER:HEARTBEAT:0:U DS:wtime:COUNTER:HEARTBEAT:0:U =item Network traffic (FinterfaceE>.rrd>) DS:incoming:COUNTER:HEARTBEAT:0:U DS:outgoing:COUNTER:HEARTBEAT:0:U =item Interface packets (FinterfaceE>.rrd>) DS:rx:COUNTER:HEARTBEAT:0:U DS:tx:COUNTER:HEARTBEAT:0:U =item Interface errors (FinterfaceE>.rrd>) DS:rx:COUNTER:HEARTBEAT:0:U DS:tx:COUNTER:HEARTBEAT:0:U =item Users (F) DS:users:GAUGE:HEARTBEAT:0:65535 =item VServer load (FxidE>/load.rrd>) DS:shortterm:GAUGE:HEARTBEAT:0:100 DS:midterm:GAUGE:HEARTBEAT:0:100 DS:longterm:GAUGE:HEARTBEAT:0:100 =item VServer threads (FxidE>/threads.rrd>) DS:total:GAUGE:HEARTBEAT:0:65535 DS:running:GAUGE:HEARTBEAT:0:65535 DS:uninterruptible:GAUGE:HEARTBEAT:0:65535 DS:onhold:GAUGE:HEARTBEAT:0:65535 =item VServer network traffic (FxidE>/traffic-InameE>.rrd>) DS:incoming:COUNTER:HEARTBEAT:0:9223372036854775807 DS:outgoing:COUNTER:HEARTBEAT:0:9223372036854775807 DS:failed:COUNTER:HEARTBEAT:0:9223372036854775807 =item VServer processes (FxidE>/vs_processes.rrd>) DS:total:GAUGE:HEARTBEAT:0:65535 =item VServer memory usage (FxidE>/vs_memory.rrd>) DS:vm:GAUGE:HEARTBEAT:0:9223372036854775807 DS:vml:GAUGE:HEARTBEAT:0:9223372036854775807 DS:rss:GAUGE:HEARTBEAT:0:9223372036854775807 DS:anon:GAUGE:HEARTBEAT:0:9223372036854775807 =item Wireless link quality (FinterfaceE>.rrd>) DS:quality:GAUGE:HEARTBEAT:0:U DS:power:GAUGE:HEARTBEAT:U:0 DS:noise:GAUGE:HEARTBEAT:U:0 =back =head1 SEE ALSO L, L, L, L, L, L =head1 AUTHOR Florian Forster Eocto@verplant.orgE =cut