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
+apart from loading, querying and submitting to plugins. For a description of
available plugins please see L</PLUGINS> below.
=head1 OPTIONS
change B<collectd>'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<-P> I<E<lt>pid-fileE<gt>>
Specify an alternative pid file. This overwrites any settings in the config
=head1 PLUGINS
-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:
+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<README> file that is distributed with the sourcecode. If you're using a
+package it's a good bet to search somewhere near F</usr/share/doc/collectd>.
+
+There are two big groups of plugins, B<input> and B<output> plugins:
=over 4
provide information about issues and significant situations to the user.
Several loglevels let you suppress uninteresting messages.
-=head1 SPECIAL PLUGINS
-
-=head2 apache
-
-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.
-
- 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 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:<type>:<size>
-
-If C<size> is less than or equal to zero, C<size> is ignored.
-
-Spam score:
-
- s:<value>
-
-Successful spam checks (e.g. "BAYES_99", "SUBJECT_DRUG_GAP_C", ...):
-
- c:<type1>[,<type2>,...]
-
-Each line is limited to 256 characters (including the newline character).
-Longer lines will be ignored.
-
-=head2 exec
-
-The C<exec> plugin forks of an executable and reads back values that it writes
-to C<STDOUT>. The executable is forked kind of as L<init> does: It is forked
-once and not again until it exits. If it exited, it will be forked again after
-at most I<Interval> seconds. It is perfectly legal for the executable to run
-for a long time and continuously write values to C<STDOUT>.
-
-The forked executable is expected to print values to C<STDOUT>. 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<type>,I<type-instance>,I<value>>, where
-I<type> is either B<counter> or B<gauge>, I<type-instance> may not contain
-C<,> (comma), C</> (slash) and C<\0> (null byte) and I<value> is either an
-integer (if I<type> is B<counter>) or a floating-point number (if I<type> is
-B<gauge>).
-
-=back
-
-The values are always considered to be "fresh", i.E<nbsp>e. the time is set to
-"now".
-
-When collectd exits it sends a B<SIGTERM> to all still running
-child-processes upon which they have to quit.
-
-=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 perl
-
-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.
-
-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<plugin_register> (I<type>, I<name>, I<data>)
-
-Registers a callback-function or data-set.
-
-I<type> 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<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.
-
-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:
-
-=over 4
-
-=item TYPE_INIT
-
-=item TYPE_READ
-
-=item TYPE_SHUTDOWN
-
-No arguments are passed
-
-=item TYPE_WRITE
-
-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.
-
-=item TYPE_LOG
-
-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<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 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>. 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/>.
+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-email(5)>, L<collectd-exec(5)>,
+L<collectd-perl(5)>, and L<collectd-unixsock(5)>
=head1 SEE ALSO
-L<collectd.conf(5)>, L<rrdtool(1)>, L<sensors(1)>, L<hddtemp(8)>,
-L<mbmon(1)>,
-L<kstat(3KSTAT)>,
+L<collectd.conf(5)>,
+L<collectd-email(5)>,
+L<collectd-exec(5)>,
+L<collectd-perl(5)>,
+L<collectd-unixsock(5)>,
L<http://collectd.org/>
=head1 AUTHOR
projects / collectd.git / blobdiff