3 collectd - System statistics collection daemon
11 collectd is a daemon that receives system statistics and makes them available
12 in a number of ways. The main daemon itself doesn't have any real functionality
13 appart from loading, querying and submitting to plugins. For a description of
14 available plugins please see L</PLUGINS> below.
18 Most of collectd's configuration is done using using a configfile. See
19 L<collectd.conf(5)> for an in-depth description of all options.
23 =item B<-C> I<E<lt>config-fileE<gt>>
25 Specify an alternative config file. This is the place to go when you wish to
26 change B<collectd>'s behavior. The path may be relative to the current working
29 =item B<-P> I<E<lt>pid-fileE<gt>>
31 Specify an alternative pid file. This overwrites any settings in the config
32 file. This is thought for init-scripts that require the PID-file in a certain
33 directory to work correctly. For everyday-usage use the B<PIDFile>
38 Don't fork to the background. I<collectd> will also B<not> close standard file
39 descriptors, detach from the session nor write a pid file. This is mainly
40 thought for 'supervisioning' init replacements such as I<runit>.
44 Output usage information and exit.
50 As noted above, the real power of collectd lies within it's plugins. There are
51 two big groups of plugins, B<input> and B<output> plugins:
57 Input plugins are queried periodically. They somehow aquire the current value
58 of whatever they where designed to work with and submit these values back to
59 the daemon, i. e. they "dispatch" the values. As an example, the C<cpu plugin>
60 reads the current cpu-counters of time spent in the various modes (user,
61 system, nice, ...) and dispatches these counters to the daemon.
65 Output plugins get the dispatched values from the daemon and does something
66 with them. Common applications are writing to RRD-files, CSV-files or sending
67 the data over a network link to a remote box.
71 Of course not all plugins fit neatly into one of the two above categories. The
72 C<network plugin>, for example, is able to send (i.E<nbsp>e. "write") B<and>
73 receive (i.E<nbsp>e. "dispatch") values. Also, it opens a socket upon
74 initialization and dispatches the values when it receives them and isn't
75 triggered at the same time the input plugins are being read. You can think if
76 the network receive part as working asynchronous if it helps.
78 In addition to the above, there are "logging plugins". Right now those are the
79 C<logfile plugin> and the C<syslog plugin>. With these plugins collectd can
80 provide information about issues and significant situations to the user.
81 Several loglevels let you suppress uninteresting messages.
83 =head1 SPECIAL PLUGINS
87 This module connects to an Apache or lighttpd webserver and expects the output
88 produced by B<mod_status.c>. If requires B<libcurl> to set up the HTTP
89 connection and issue the request(s). The following is a sample config for the
90 Apache webserver. Under Apache, the use of C<ExtendedStatus on> is mandatory.
93 <IfModule mod_status.c>
94 <Location /mod_status>
95 SetHandler server-status
99 This plugin requires further configuration. Please read L<collectd.conf(5)>.
103 This module reads F</sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq> (for
104 the first CPU installed) to get the current CPU frequency. If this file does
105 not exist make sure B<cpufreqd> (L<http://cpufreqd.sourceforge.net/>) or a
106 similar tool is installed and an "cpu governor" (that's kernel module) is
111 This plugin collects data indirectly by providing a UNIX socket that external
112 programs can connect to. A simple line based protocol is used to communicate
115 E-Mail type (e.g. "ham", "spam", "virus", ...) and size (bytes):
119 If C<size> is less than or equal to zero, C<size> is ignored.
125 Successful spam checks (e.g. "BAYES_99", "SUBJECT_DRUG_GAP_C", ...):
127 c:<type1>[,<type2>,...]
129 Each line is limited to 256 characters (including the newline character).
130 Longer lines will be ignored.
134 The C<exec> plugin forks of an executable and reads back values that it writes
135 to C<STDOUT>. The executable is forked kind of as L<init> does: It is forked
136 once and not again until it exits. If it exited, it will be forked again after
137 at most I<Interval> seconds. It is perfectly legal for the executable to run
138 for a long time and continuously write values to C<STDOUT>.
140 The forked executable is expected to print values to C<STDOUT>. The expected
141 format is as follows:
147 Each line beginning with a C<#> (hash mark) is ignored.
151 Any other line must be of the form C<I<type>,I<type-instance>,I<value>>, where
152 I<type> is either B<counter> or B<gauge>, I<type-instance> may not contain
153 C<,> (comma), C</> (slash) and C<\0> (null byte) and I<value> is either an
154 integer (if I<type> is B<counter>) or a floating-point number (if I<type> is
159 The values are always considered to be "fresh", i.E<nbsp>e. the time is set to
162 When collectd exits it sends a B<SIGTERM> to all still running
163 child-processes upon which they have to quit.
167 Requires B<mysqlclient> to be installed. It connects to the database when
168 started and keeps the connection up as long as possible. When the connection is
169 interrupted for whatever reason it will try to re-connect. The syslog will
170 contain loud complaints in case anything goes wrong.
172 This plugin issues C<SHOW STATUS> and evaluates C<Bytes_{received,sent}>,
173 C<Com_*> and C<Handler_*> which correspond to F<traffic-mysql.rrd>,
174 F<mysql_commands-*.rrd> and F<mysql_handler-*.rrd>. Also, the values of
175 C<Qcache_*> are put in F<mysql_qcache.rrd> and values of C<Threads_*> are put
176 in F<mysql_threads.rrd>. Please refer to the B<MySQL reference manual>,
177 I<5.2.4. Server Status Variables> for an explanation of these values.
181 The C<perl plugin> includes a Perl-interpreter in collectd and provides
182 Perl-equivalents of the plugin-functions. This makes it possible to write
185 There are two more complex types you need to know about:
191 A data-set is a list of one or more data-sources. Each data-source defines a
192 name, type, min- and max-value and the data-set wraps them up into one
193 structure. The general layout looks like this:
196 name => 'data_source_name',
197 type => DS_TYPE_COUNTER || DS_TYPE_GAUGE
198 min => value || undef,
199 max => value || undef
204 A value-list is one structure which features an array of values and fields to
205 identify the values, i. e. time and host, plugin name and plugin-instance as
206 well as a type and type-instance. Since the "type" is not included in the
207 value-list but is passed as an extra argument, the general layout looks like
211 values => [123, 0.5],
214 plugin => 'myplugin',
215 plugin_instance => '',
221 The following functions provide the C-interface to Perl-modules:
225 =item B<plugin_register> (I<type>, I<name>, I<data>)
227 Registers a callback-function or data-set.
229 I<type> can be one of:
247 I<name> is the name of the callback-function or the type of the data-set,
248 depending on the value of I<type>. (Please note that the type of the data-set
249 is the value passed as I<name> here and has nothing to do with the I<type>
250 argument which simply tells B<plugin_register> what is being registered.)
252 The last argument, I<data>, is either a function- or an array-reference. If
253 I<type> is B<TYPE_DATASET>, then the I<data> argument must be an
254 array-reference which points to an array of hashes. Each hash describes one
255 data-source. For the exact layout see B<Data-Set> above.
257 If the I<type> argument is any of the other types (B<TYPE_INIT>, B<TYPE_READ>,
258 ...) then I<data> is expected to be a function reference. These functions are
259 called in the various stages of the daemon and are passed the following
270 No arguments are passed
274 The arguments passed are I<type>, I<data-set>, and I<value-list>. I<type> is a
275 string. For the layout of I<data-set> and I<value-list> see above.
279 The arguments are I<log-level> and I<message>. The log level is small for
280 important messages and high for less important messages. The least important
281 level is B<LOG_DEBUG>, the most important level is B<LOG_ERR>. In between there
282 are (from least to most important): B<LOG_INFO>, B<LOG_NOTICE>, and
283 B<LOG_WARNING>. I<message> is simply a string B<without> a newline at the end.
287 =item B<plugin_unregister> (I<type>, I<plugin>)
289 Removes a callback or data-set from collectd's internal list of
290 functionsE<nbsp>/ datasets.
292 =item B<plugin_dispatch_values> (I<type>, I<value-list>)
294 Submits a I<value-list> of type I<type> to the daemon. If the data-set I<type>
295 is found (and the number of values matches the number of data-sources) then the
296 type, data-set and value-list is passed to all write-callbacks that are
297 registered with the daemon.
299 =item B<plugin_log> (I<log-level>, I<message>)
301 Submits a I<message> of level I<log-level> to collectd's logging mechanism.
302 The message is passed to all log-callbacks that are registered with collectd.
308 The B<sensors> module uses lm_sensors to retrieve sensor-values. This means
309 that all the needed modules have to be loaded and lm_sensors has to be
310 configured (most likely by editing F</etc/sensors.conf>. Read
311 L<sensors.conf(5)> for details.
313 The B<lm_sensors> homepage can be found at
314 L<http://secure.netroedge.com/~lm78/>.
318 The B<mbmon> module uses mbmon to retrieve temperature, voltage, etc.
320 collectd connects to B<localhost> (127.0.0.1), port B<411/tcp>.
321 The B<Host> and B<Port> options can be used to change these
322 default values. See L<collectd.conf(5)> for details. C<mbmon> has to be
323 running to work correctly. If C<mbmon> is not running timeouts may appear
324 which may interfere with other statistics..
326 C<mbmon> must be run with the -r option ("print TAG and Value format");
327 Debian's /etc/init.d/mbmon script already does this, other people
328 will need to ensure that this is the case.
332 To get values from B<hddtemp> collectd connects to B<localhost> (127.0.0.1),
333 port B<7634/tcp>. The B<Host> and B<Port> options can be used to change these
334 default values. See L<collectd.conf(5)> for details. C<hddtemp> has to be
335 running to work correctly. If C<hddtemp> is not running timeouts may appear
336 which may interfere with other statistics..
338 The B<hddtemp> homepage can be found at
339 L<http://www.guzu.net/linux/hddtemp.php>.
343 B<VServer> support is only available for Linux. It cannot yet be found in a
344 vanilla kernel, though. To make use of this plugin you need a kernel that has
345 B<VServer> support built in, i.e. you need to apply the patches and compile
346 your own kernel, which will then provide the /proc/virtual filesystem that is
347 required by this plugin.
349 The B<VServer> homepage can be found at L<http://linux-vserver.org/>.
353 L<collectd.conf(5)>, L<rrdtool(1)>, L<sensors(1)>, L<hddtemp(8)>,
356 L<http://collectd.org/>
360 Florian Forster E<lt>octo@verplant.orgE<gt>