=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
-
-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>)
-
-=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
+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 B<-C> I<E<lt>config-fileE<gt>>
change B<collectd>'s behavior. The path may be relative to the current working
directory.
+=item B<-P> I<E<lt>pid-fileE<gt>>
+
+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 B<-f>
Don't fork to the background. I<collectd> will also B<not> close standard file
=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 two 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 collectd the data locally and send it's result 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.
-
-Please refer to L<collectd.conf(5)> for the configuration options and default
-values.
-
-=head1 SPECIAL PLUGINS
-
-=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.
-
-=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.
+=head1 PLUGINS
-=head2 sensors
+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:
-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/>.
+=over 4
-=head2 hddtemp
+=item
-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..
+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.
-The B<hddtemp> homepage can be found at
-L<http://www.guzu.net/linux/hddtemp.php>.
+=item
-=head2 vserver
+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.
-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.
+=back
-The B<VServer> homepage can be found at L<http://linux-vserver.org/>.
+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.
-=head1 RRD FILES
+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.
-The RRD files are created automatically with the following RRAs:
+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)>,
+...
- 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
+=head1 SPECIAL PLUGINS
-Since collectd uses a 10 second I<step> the RRAs contain the following
-timespans:
+=head2 perl
- Resolution | Data points | Timespan
- -----------+-------------+----------
- 60 seconds | 1500 | 25 hours
- 30 minutes | 1680 | 35 days
- 6 hours | 1520 | 380 days
+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.
-The DS'es depend on the module creating the RRD files:
+There are two more complex types you need to know about:
=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>)
+=item Data-Set
- 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
+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:
-=item Mountpoints (F<df-I<E<lt>pathE<gt>>.rrd>)
+ [{
+ name => 'data_source_name',
+ type => DS_TYPE_COUNTER || DS_TYPE_GAUGE
+ min => value || undef,
+ max => value || undef
+ }, ...]
- DS:used:GAUGE:25:0:U
- DS:free:GAUGE:25:0:U
+=item Value-List
-=item Diskstats (F<disk-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
+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:
- 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
+ {
+ values => [123, 0.5],
+ time => time (),
+ host => 'localhost',
+ plugin => 'myplugin',
+ plugin_instance => '',
+ type_instance => ''
+ }
-=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>)
+=back
- DS:used:GAUGE:25:0:9223372036854775807
- DS:free:GAUGE:25:0:9223372036854775807
- DS:buffers:GAUGE:25:0:9223372036854775807
- DS:cached:GAUGE:25:0:9223372036854775807
+The following functions provide the C-interface to Perl-modules:
-=item MySQL commands and handlers (F<mysql_commands-I<E<lt>commandE<gt>>.rrd> and F<mysql_handler-I<E<lt>handlerE<gt>>.rrd>)
+=over 4
- DS:value:COUNTER:25:0:U
+=item B<plugin_register> (I<type>, I<name>, I<data>)
-=item MySQL query cache (F<mysql_qcache.rrd>)
+Registers a callback-function or data-set.
- 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
+I<type> can be one of:
-=item MySQL threads (F<mysql_threads.rrd>)
+=over 4
- 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 TYPE_INIT
-=item NFSv2 Procedures (F<nfs2_procedures-I<(client|server)>.rrd>)
+=item TYPE_READ
- 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 TYPE_WRITE
-=item NFSv3 Procedures (F<nfs3_procedures-I<(client|server)>.rrd>)
+=item TYPE_LOG
- 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 TYPE_SHUTDOWN
-=item Network latency / Ping (F<ping-I<E<lt>hostnameE<gt>>.rrd>)
+=item TYPE_DATASET
- DS:ping:GAUGE:25:0:65535
+=back
-=item Processes (F<processes.rrd>)
+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.)
- 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
+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.
-=item lm_sensors (F<sensors-I<E<lt>chipE<gt>>-I<E<lt>featureE<gt>>.rrd>)
+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:
- DS:value:GAUGE:25:U:U
+=over 4
-=item Serial port traffic (F<serial-I<E<lt>numE<gt>>.rrd>)
+=item TYPE_INIT
- DS:incoming:COUNTER:25:0:U
- DS:outgoing:COUNTER:25:0:U
+=item TYPE_READ
-=item Swap usage (F<swap.rrd>)
+=item TYPE_SHUTDOWN
- DS:used:GAUGE:25:0:1099511627776
- DS:free:GAUGE:25:0:1099511627776
- DS:cached:GAUGE:25:0:1099511627776
- DS:resv:GAUGE:25:0:1099511627776
+No arguments are passed
-=item Tape drive usage (F<tape-I<E<lt>nameE<gt>>.rrd>)
+=item TYPE_WRITE
- 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
+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 Users (F<users.rrd>)
+=item TYPE_LOG
- DS:users:GAUGE:25:0:65535
+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.
-=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
+=back
-=item VServer network traffic (F<vserver-I<E<lt>xidE<gt>>/traffic-I<E<lt>nameE<gt>>.rrd>)
+=item B<plugin_unregister> (I<type>, I<plugin>)
- DS:incoming:COUNTER:25:0:9223372036854775807
- DS:outgoing:COUNTER:25:0:9223372036854775807
- DS:failed:COUNTER:25:0:9223372036854775807
+Removes a callback or data-set from collectd's internal list of
+functionsE<nbsp>/ datasets.
-=item VServer processes (F<vserver-I<E<lt>xidE<gt>>/vs_processes.rrd>)
+=item B<plugin_dispatch_values> (I<type>, I<value-list>)
- DS:total:GAUGE:25:0:65535
+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 VServer memory usage (F<vserver-I<E<lt>xidE<gt>>/vs_memory.rrd>)
+=item B<plugin_log> (I<log-level>, I<message>)
- DS:vm:GAUGE:25:0:9223372036854775807
- DS:vml:GAUGE:25:0:9223372036854775807
- DS:rss:GAUGE:25:0:9223372036854775807
- DS:anon:GAUGE:25:0:9223372036854775807
+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
=head1 SEE ALSO
-L<collectd.conf(5)>, L<rrdtool(1)>, L<sensors(1)>, L<hddtemp(8)>,
-L<kstat(3KSTAT)>
+L<collectd.conf(5)>,
+L<collectd-email(5)>,
+L<collectd-exec(5)>,
+L<collectd-unixsock(5)>,
+L<http://collectd.org/>
=head1 AUTHOR
projects / collectd.git / blobdiff