=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:
+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
+appart from loading, querying and submitting to plugins. For a description of
+available plugins please see L</PLUGINS> below.
+
+=head1 OPTIONS
+
+Most of collectd's configuration is done using using a configfile. See
+L<collectd.conf(5)> for an in-depth description of all options.
=over 4
-=item
+=item B<-C> I<E<lt>config-fileE<gt>>
-CPU utilization (I<cpu>)
+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
+=item B<-P> I<E<lt>pid-fileE<gt>>
-Disk and partition usage/throughput (I<disk>)
+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<PIDFile>
+config-option.
-=item
+=item B<-f>
-Harddisk temperatures (I<hddtemp>)
+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
+=item B<-h>
-System load averages (I<load>)
+Output usage information and exit.
-=item
+=back
-Memory usage (I<memory>)
+=head1 PLUGINS
-=item
+As noted above, the real power of collectd lies within it's plugins. There are
+two big groups of plugins, B<input> and B<output> plugins:
-NFS utilization (I<nfs>, Linux only)
+=over 4
=item
-Network latency (I<ping>)
+Input plugins are queried periodically. They somehow aquire 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<cpu plugin>
+reads the current cpu-counters of time spent in the various modes (user,
+system, nice, ...) and dispatches these counters to the daemon.
=item
-Number of processes (I<processes>, Linux only)
+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
+=back
-lm_sensors information (I<sensors>, Linux only)
+Of course not all plugins fit neatly into one of the two above categories. The
+C<network plugin>, for example, is able to send (i.E<nbsp>e. "write") B<and>
+receive (i.E<nbsp>e. "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 if
+the network receive part as working asynchronous if it helps.
-=item
+In addition to the above, there are "logging plugins". Right now those are the
+C<logfile plugin> and the C<syslog plugin>. With these plugins collectd can
+provide information about issues and significant situations to the user.
+Several loglevels let you suppress uninteresting messages.
-Serial port traffic (I<serial>, Linux only)
+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<collectd-exec(5)>, L<collectd-unixsock(5)>,
+...
-=item
+=head1 SPECIAL PLUGINS
-Swap usage (I<swap>)
+=head2 apache
-=item
+This module connects to an Apache or lighttpd 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. Under Apache, the use of C<ExtendedStatus on> is mandatory.
-Tape drive usage (I<tape>, Solaris only)
+ ExtendedStatus on
+ <IfModule mod_status.c>
+ <Location /mod_status>
+ SetHandler server-status
+ </Location>
+ </IfModule>
-=item
+This plugin requires further configuration. Please read L<collectd.conf(5)>.
-Network traffic (I<traffic>)
+=head2 cpufreq
-=item
+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.
-Number of users logged into the system (I<users>)
+=head2 email
-=back
+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:
-=head1 OPTIONS
+E-Mail type (e.g. "ham", "spam", "virus", ...) and size (bytes):
-=over 4
+ e:<type>:<size>
-=item B<-c>
+If C<size> is less than or equal to zero, C<size> is ignored.
-Start in client (transmitter) mode. Data will be sent to the multicast group.
-See L<"MODES">.
+Spam score:
-=item B<-d> I<E<lt>directoryE<gt>>
+ s:<value>
-Sets the directory collectd should work in. All F<.rrd>-files are created in
-this directory. Per default this is F</var/lib/collectd/>.
+Successful spam checks (e.g. "BAYES_99", "SUBJECT_DRUG_GAP_C", ...):
-=item B<-P> I<E<lt>directoryE<gt>>
+ c:<type1>[,<type2>,...]
-Sets the directory collectd should look for plugins in. Per default this is
-F</usr/lib/collectd>.
+Each line is limited to 256 characters (including the newline character).
+Longer lines will be ignored.
-=item B<-f>
+=head2 mysql
-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>.
+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.
-=item B<-h>
+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.
-Output usage information and exit.
+=head2 perl
-=item B<-l>
+The C<perl plugin> includes a Perl-interpreter in collectd and provides
+Perl-equivalents of the plugin-functions. This makes it possible to write
+plugins in Perl.
-Start in local mode. This is the default. No data will be sent or read to/from
-the network. Information will be read and written by the same process. See
-L<"MODES">.
+There are two more complex types you need to know about:
-=item B<-p> I<E<lt>hostE<gt>>
+=over 4
-Sets the host to ping periodically. This option may be given more than once to
-ping multiple hosts. If this option is not given at least once no host will be
-pinged.
+=item Data-Set
-=item B<-s>
+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:
-Start in server (receiver) mode. Data sent to the multicast group will be read
-and stored in RRD files. See L<"MODES">.
+ [{
+ name => 'data_source_name',
+ type => DS_TYPE_COUNTER || DS_TYPE_GAUGE
+ min => value || undef,
+ max => value || undef
+ }, ...]
-=back
+=item Value-List
-=head1 RRD FILES
+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:
-The RRD files are created automatically with the following RRAs:
+ {
+ values => [123, 0.5],
+ time => time (),
+ host => 'localhost',
+ plugin => 'myplugin',
+ plugin_instance => '',
+ type_instance => ''
+ }
- RRA:AVERAGE:0.2:6:1500
- RRA:AVERAGE:0.1:180:1680
- RRA:AVERAGE:0.1:2160:1520
- RRA:MIN:0.2:6:1500
- RRA:MIN:0.1:180:1680
- RRA:MIN:0.1:2160:1520
- RRA:MAX:0.2:6:1500
- RRA:MAX:0.1:180:1680
- RRA:MAX:0.1:2160:1520
+=back
-Since collectd uses a 10 second I<step> the RRAs contain the following
-timespans:
+The following functions provide the C-interface to Perl-modules:
- Resolution | Data points | Timespan
- -----------+-------------+----------
- 60 seconds | 1500 | 25 hours
- 30 minutes | 1680 | 35 days
- 6 hours | 1520 | 380 days
+=over 4
-The DS'es depend on the module creating the RRD files:
+=item B<plugin_register> (I<type>, I<name>, I<data>)
+
+Registers a callback-function or data-set.
+
+I<type> can be one of:
=over 4
-=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 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 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 TYPE_INIT
+
+=item TYPE_READ
+
+=item TYPE_WRITE
+
+=item TYPE_LOG
+
+=item TYPE_SHUTDOWN
+
+=item TYPE_DATASET
=back
-=head1 MODES
+I<name> is the name of the callback-function or the type of the data-set,
+depending on the value of I<type>. (Please note that the type of the data-set
+is the value passed as I<name> here and has nothing to do with the I<type>
+argument which simply tells B<plugin_register> what is being registered.)
+
+The last argument, I<data>, is either a function- or an array-reference. If
+I<type> is B<TYPE_DATASET>, then the I<data> 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<Data-Set> above.
-By default collectd starts in the so called I<local mode> which is not very
-interesting. It collects data and writes it into RRD files in
-F</var/lib/collectd>. There's nothing special so I won't discuss that in more
-detail..
+If the I<type> argument is any of the other types (B<TYPE_INIT>, B<TYPE_READ>,
+...) then I<data> is expected to be a function reference. These functions are
+called in the various stages of the daemon and are passed the following
+arguments:
-Please be aware that B<client-, local- and server-mode are mutual exclusive>. A
-later declaration overrides earlier ones. I<collectd -l -c -s> will start in
-server-mode. If you want statistics of the server too you will have to start a
-client process as well.
+=over 4
-Starting with version 3 collectd may send data over a network. As common with
-network stuff there are two modes: A I<sender> and a I<listener>. Since one
-usually has many senders and only a few listeners the sender is also called
-I<client> (using the option B<-c>) and the listener is called I<server> (using
-the option B<-s>).
+=item TYPE_INIT
-Communication happends using the (IPv4) multicast group B<239.192.74.66> and
-packets sent to the port B<25826/udp>. Every ten seconds the I<client> queries
-all the modules and sends the collected data to the multicast group. The
-I<server> subscribes to the multicast group upon startup and then waits for
-incoming packets. As it receives the packets it checks wether it has the
-neccessary module and, if found, writes the data to an RRD file, creating
-directories and files as needed.
+=item TYPE_READ
-The multicast group used is within the I<Organization Local Scope> as defined
-by L<RFC2365>. Addresses within that space are meant to be routed within an AS
-but not to the outside. However collectd cannot control this and won't try. So
-it's totally up to you to secure your net.
+=item TYPE_SHUTDOWN
-The UDP port used has been checked to not be assigned by the IANA.
+No arguments are passed
-On multi-homed machines you may need to add a route to the multicast net
-(B<224.0.0.0/4>) if multicast packages take the wrong interface. The listener
-on the other hand listens on B<all> interfaces.
+=item TYPE_WRITE
-=head1 SPECIAL MODULES
+The arguments passed are I<type>, I<data-set>, and I<value-list>. I<type> is a
+string. For the layout of I<data-set> and I<value-list> see above.
-=head2 cpufreq
+=item TYPE_LOG
-This module reads F</sys/devices/system/cpu/cpu0/cpufreq/cpuinfo_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.
+The arguments are I<log-level> and I<message>. The log level is small for
+important messages and high for less important messages. The least important
+level is B<LOG_DEBUG>, the most important level is B<LOG_ERR>. In between there
+are (from least to most important): B<LOG_INFO>, B<LOG_NOTICE>, and
+B<LOG_WARNING>. I<message> is simply a string B<without> a newline at the end.
+
+=back
+
+=item B<plugin_unregister> (I<type>, I<plugin>)
+
+Removes a callback or data-set from collectd's internal list of
+functionsE<nbsp>/ datasets.
+
+=item B<plugin_dispatch_values> (I<type>, I<value-list>)
+
+Submits a I<value-list> of type I<type> to the daemon. If the data-set I<type>
+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<plugin_log> (I<log-level>, I<message>)
+
+Submits a I<message> of level I<log-level> to collectd's logging mechanism.
+The message is passed to all log-callbacks that are registered with collectd.
+
+=back
=head2 sensors
The B<lm_sensors> homepage can be found at
L<http://secure.netroedge.com/~lm78/>.
+=head2 mbmon
+
+The B<mbmon> module uses mbmon to retrieve temperature, voltage, etc.
+
+collectd connects to B<localhost> (127.0.0.1), port B<411/tcp>.
+The B<Host> and B<Port> options can be used to change these
+default values. See L<collectd.conf(5)> for details. C<mbmon> has to be
+running to work correctly. If C<mbmon> is not running timeouts may appear
+which may interfere with other statistics..
+
+C<mbmon> 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<hddtemp> collectd connects to B<localhost> (127.0.0.1),
-port B<7634/tcp>. hddtemp has to be running to work correctly. If hddtemp is
-not running timeouts may appear which may interfere with other statistics..
+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 SEE ALSO
-L<rrdtool(1)>, L<sensors(1)>, L<hddtemp(8)>, L<kstat(3KSTAT)>
+L<collectd.conf(5)>,
+L<collectd-exec(5)>,
+L<collectd-unixsock(5)>,
+L<hddtemp(8)>,
+L<kstat(3KSTAT)>,
+L<mbmon(1)>,
+L<rrdtool(1)>,
+L<sensors(1)>,
+L<http://collectd.org/>
=head1 AUTHOR
projects / collectd.git / blobdiff