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 Please note that some plugins, that provide other means of communicating with
84 the daemon, have manpages of their own to describe their functionality in more
85 detail. In particular those are L<collectd-exec(5)>, L<collectd-unixsock(5)>,
88 =head1 SPECIAL PLUGINS
92 This plugin collects data indirectly by providing a UNIX socket that external
93 programs can connect to. A simple line based protocol is used to communicate
96 E-Mail type (e.g. "ham", "spam", "virus", ...) and size (bytes):
100 If C<size> is less than or equal to zero, C<size> is ignored.
106 Successful spam checks (e.g. "BAYES_99", "SUBJECT_DRUG_GAP_C", ...):
108 c:<type1>[,<type2>,...]
110 Each line is limited to 256 characters (including the newline character).
111 Longer lines will be ignored.
115 The C<perl plugin> includes a Perl-interpreter in collectd and provides
116 Perl-equivalents of the plugin-functions. This makes it possible to write
119 There are two more complex types you need to know about:
125 A data-set is a list of one or more data-sources. Each data-source defines a
126 name, type, min- and max-value and the data-set wraps them up into one
127 structure. The general layout looks like this:
130 name => 'data_source_name',
131 type => DS_TYPE_COUNTER || DS_TYPE_GAUGE
132 min => value || undef,
133 max => value || undef
138 A value-list is one structure which features an array of values and fields to
139 identify the values, i. e. time and host, plugin name and plugin-instance as
140 well as a type and type-instance. Since the "type" is not included in the
141 value-list but is passed as an extra argument, the general layout looks like
145 values => [123, 0.5],
148 plugin => 'myplugin',
149 plugin_instance => '',
155 The following functions provide the C-interface to Perl-modules:
159 =item B<plugin_register> (I<type>, I<name>, I<data>)
161 Registers a callback-function or data-set.
163 I<type> can be one of:
181 I<name> is the name of the callback-function or the type of the data-set,
182 depending on the value of I<type>. (Please note that the type of the data-set
183 is the value passed as I<name> here and has nothing to do with the I<type>
184 argument which simply tells B<plugin_register> what is being registered.)
186 The last argument, I<data>, is either a function- or an array-reference. If
187 I<type> is B<TYPE_DATASET>, then the I<data> argument must be an
188 array-reference which points to an array of hashes. Each hash describes one
189 data-source. For the exact layout see B<Data-Set> above.
191 If the I<type> argument is any of the other types (B<TYPE_INIT>, B<TYPE_READ>,
192 ...) then I<data> is expected to be a function reference. These functions are
193 called in the various stages of the daemon and are passed the following
204 No arguments are passed
208 The arguments passed are I<type>, I<data-set>, and I<value-list>. I<type> is a
209 string. For the layout of I<data-set> and I<value-list> see above.
213 The arguments are I<log-level> and I<message>. The log level is small for
214 important messages and high for less important messages. The least important
215 level is B<LOG_DEBUG>, the most important level is B<LOG_ERR>. In between there
216 are (from least to most important): B<LOG_INFO>, B<LOG_NOTICE>, and
217 B<LOG_WARNING>. I<message> is simply a string B<without> a newline at the end.
221 =item B<plugin_unregister> (I<type>, I<plugin>)
223 Removes a callback or data-set from collectd's internal list of
224 functionsE<nbsp>/ datasets.
226 =item B<plugin_dispatch_values> (I<type>, I<value-list>)
228 Submits a I<value-list> of type I<type> to the daemon. If the data-set I<type>
229 is found (and the number of values matches the number of data-sources) then the
230 type, data-set and value-list is passed to all write-callbacks that are
231 registered with the daemon.
233 =item B<plugin_log> (I<log-level>, I<message>)
235 Submits a I<message> of level I<log-level> to collectd's logging mechanism.
236 The message is passed to all log-callbacks that are registered with collectd.
244 L<collectd-unixsock(5)>,
245 L<http://collectd.org/>
249 Florian Forster E<lt>octo@verplant.orgE<gt>