X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=src%2Fcollectd.pod;h=2a326bb6fa544d2de91ac5bb3abfc5274d76e721;hb=4371ef7f98f6f51ea3df34d5e26e175d6b44a328;hp=96c3fcdb43632cb9460c64a138be11ce1ee63375;hpb=35248bcc734467e1f1ae39b4a6470849e57624bf;p=collectd.git diff --git a/src/collectd.pod b/src/collectd.pod index 96c3fcdb..8ea47ec8 100644 --- a/src/collectd.pod +++ b/src/collectd.pod @@ -1,3 +1,5 @@ +=encoding UTF-8 + =head1 NAME collectd - System statistics collection daemon @@ -8,116 +10,16 @@ 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 - -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 +collectd is a daemon that receives system statistics and makes them available +in a number of ways. The main daemon itself doesn't have any real functionality +apart from loading, querying and submitting to plugins. For a description of +available plugins please see L below. =head1 OPTIONS +Most of collectd's configuration is done using using a configfile. See +L for an in-depth description of all options. + =over 4 =item B<-C> Iconfig-fileE> @@ -126,6 +28,16 @@ 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<-t> + +Test the configuration only. The program immediately exits after parsing the +config file. A return code not equal to zero indicates an error. + +=item B<-T> + +Test the plugin read callbacks only. The program immediately exits after invoking +the read callbacks once. A return code not equal to zero indicates an error. + =item B<-P> Ipid-fileE> Specify an alternative pid file. This overwrites any settings in the config @@ -137,7 +49,7 @@ config-option. 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. +thought for 'supervising' init replacements such as I. =item B<-h> @@ -145,452 +57,84 @@ 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 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 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. +=head1 PLUGINS -The B homepage can be found at -L. +As noted above, the real power of collectd lies within it's plugins. A +(hopefully complete) list of plugins and short descriptions can be found in the +F file that is distributed with the sourcecode. If you're using a +package it's a good bet to search somewhere near F. -=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: +There are two big groups of plugins, B and B plugins: =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>) +=item * - DS:value:GAUGE:HEARTBEAT:U:U +Input plugins are queried periodically. They somehow acquire the current value +of whatever they where designed to work with and submit these values back to +the daemon, i. e. they "dispatch" the values. As an example, the C +reads the current cpu-counters of time spent in the various modes (user, +system, nice, ...) and dispatches these counters to the daemon. -=item Irq (FirqnumberE>.rrd>) +=item * - DS:value:COUNTER:HEARTBEAT:0:65535 +Output plugins get the dispatched values from the daemon and does something +with them. Common applications are writing to RRD-files, CSV-files or sending +the data over a network link to a remote box. -=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>) +=back - DS:shortterm:GAUGE:HEARTBEAT:0:100 - DS:midterm:GAUGE:HEARTBEAT:0:100 - DS:longterm:GAUGE:HEARTBEAT:0:100 +Of course not all plugins fit neatly into one of the two above categories. The +C, for example, is able to send (i.Ee. "write") B +receive (i.Ee. "dispatch") values. Also, it opens a socket upon +initialization and dispatches the values when it receives them and isn't +triggered at the same time the input plugins are being read. You can think of +the network receive part as working asynchronous if it helps. -=item VServer threads (FxidE>/threads.rrd>) +In addition to the above, there are "logging plugins". Right now those are the +C and the C. With these plugins collectd can +provide information about issues and significant situations to the user. +Several loglevels let you suppress uninteresting messages. - DS:total:GAUGE:HEARTBEAT:0:65535 - DS:running:GAUGE:HEARTBEAT:0:65535 - DS:uninterruptible:GAUGE:HEARTBEAT:0:65535 - DS:onhold:GAUGE:HEARTBEAT:0:65535 +Starting with version C<4.3.0> collectd has support for B. This is +done by checking thresholds defined by the user. If a value is out of range, a +notification will be dispatched to "notification plugins". See +L for more detailed information about threshold checking. -=item VServer network traffic (FxidE>/traffic-InameE>.rrd>) +Please note that some plugins, that provide other means of communicating with +the daemon, have manpages of their own to describe their functionality in more +detail. In particular those are L, L, +L, L, and L - DS:incoming:COUNTER:HEARTBEAT:0:9223372036854775807 - DS:outgoing:COUNTER:HEARTBEAT:0:9223372036854775807 - DS:failed:COUNTER:HEARTBEAT:0:9223372036854775807 +=head1 SIGNALS -=item VServer processes (FxidE>/vs_processes.rrd>) +B accepts the following signals: - DS:total:GAUGE:HEARTBEAT:0:65535 +=over 4 -=item VServer memory usage (FxidE>/vs_memory.rrd>) +=item B, B - DS:vm:GAUGE:HEARTBEAT:0:9223372036854775807 - DS:vml:GAUGE:HEARTBEAT:0:9223372036854775807 - DS:rss:GAUGE:HEARTBEAT:0:9223372036854775807 - DS:anon:GAUGE:HEARTBEAT:0:9223372036854775807 +These signals cause B to shut down all plugins and terminate. -=item Wireless link quality (FinterfaceE>.rrd>) +=item B - DS:quality:GAUGE:HEARTBEAT:0:U - DS:power:GAUGE:HEARTBEAT:U:0 - DS:noise:GAUGE:HEARTBEAT:U:0 +This signal causes B to signal all plugins to flush data from +internal caches. E.Eg. the C will write all pending data +to the RRD files. This is the same as using the C command of the +C. =back =head1 SEE ALSO -L, L, L, L, -L, -L +L, +L, +L, +L, +L, +L, +L, +L =head1 AUTHOR