src/collectd.pod

   1 =head1 NAME
   2
   3 collectd - System statistics collection daemon
   4
   5 =head1 SYNOPSIS
   6
   7 collectd I<[options]>
   8
   9 =head1 DESCRIPTION
  10
  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.
  15
  16 =head1 OPTIONS
  17
  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.
  20
  21 =over 4
  22
  23 =item B<-C> I<E<lt>config-fileE<gt>>
  24
  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
  27 directory.
  28
  29 =item B<-P> I<E<lt>pid-fileE<gt>>
  30
  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>
  34 config-option.
  35
  36 =item B<-f>
  37
  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>.
  41
  42 =item B<-h>
  43
  44 Output usage information and exit.
  45
  46 =back
  47
  48 =head1 PLUGINS
  49
  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:
  52
  53 =over 4
  54
  55 =item
  56
  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.
  62
  63 =item
  64
  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.
  68
  69 =back
  70
  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.
  77
  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.
  82
  83 =head1 SPECIAL PLUGINS
  84
  85 =head2 apache
  86
  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.
  91
  92   ExtendedStatus on
  93   <IfModule mod_status.c>
  94     <Location /mod_status>
  95       SetHandler server-status
  96     </Location>
  97   </IfModule>
  98
  99 This plugin requires further configuration. Please read L<collectd.conf(5)>.
 100
 101 =head2 cpufreq
 102
 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
 107 loaded.
 108
 109 =head2 email
 110
 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
 113 with the plugin:
 114
 115 E-Mail type (e.g. "ham", "spam", "virus", ...) and size (bytes):
 116
 117   e:<type>:<size>
 118
 119 If C<size> is less than or equal to zero, C<size> is ignored.
 120
 121 Spam score:
 122
 123   s:<value>
 124
 125 Successful spam checks (e.g. "BAYES_99", "SUBJECT_DRUG_GAP_C", ...):
 126
 127   c:<type1>[,<type2>,...]
 128
 129 Each line is limited to 256 characters (including the newline character).
 130 Longer lines will be ignored.
 131
 132 =head2 exec
 133
 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>.
 139
 140 The forked executable is expected to print values to C<STDOUT>. The expected
 141 format is as follows:
 142
 143 =over 4
 144
 145 =item
 146
 147 Each line beginning with a C<#> (hash mark) is ignored.
 148
 149 =item
 150
 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
 155 B<gauge>).
 156
 157 =back
 158
 159 The values are always considered to be "fresh", i.E<nbsp>e. the time is set to
 160 "now".
 161
 162 When collectd exits it sends a B<SIGTERM> to all still running
 163 child-processes upon which they have to quit.
 164
 165 =head2 mysql
 166
 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.
 171
 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.
 178
 179 =head2 perl
 180
 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
 183 plugins in Perl.
 184
 185 There are two more complex types you need to know about:
 186
 187 =over 4
 188
 189 =item Data-Set
 190
 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:
 194
 195   [{
 196     name => 'data_source_name',
 197     type => DS_TYPE_COUNTER || DS_TYPE_GAUGE
 198     min  => value || undef,
 199     max  => value || undef
 200   }, ...]
 201
 202 =item Value-List
 203
 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
 208 this:
 209
 210   {
 211     values => [123, 0.5],
 212     time   => time (),
 213     host   => 'localhost',
 214     plugin => 'myplugin',
 215     plugin_instance => '',
 216     type_instance   => ''
 217   }
 218
 219 =back
 220
 221 The following functions provide the C-interface to Perl-modules:
 222
 223 =over 4
 224
 225 =item B<plugin_register> (I<type>, I<name>, I<data>)
 226
 227 Registers a callback-function or data-set.
 228
 229 I<type> can be one of:
 230
 231 =over 4
 232
 233 =item TYPE_INIT
 234
 235 =item TYPE_READ
 236
 237 =item TYPE_WRITE
 238
 239 =item TYPE_LOG
 240
 241 =item TYPE_SHUTDOWN
 242
 243 =item TYPE_DATASET
 244
 245 =back
 246
 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.)
 251
 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.
 256
 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
 260 arguments:
 261
 262 =over 4
 263
 264 =item TYPE_INIT
 265
 266 =item TYPE_READ
 267
 268 =item TYPE_SHUTDOWN
 269
 270 No arguments are passed
 271
 272 =item TYPE_WRITE
 273
 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.
 276
 277 =item TYPE_LOG
 278
 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.
 284
 285 =back
 286
 287 =item B<plugin_unregister> (I<type>, I<plugin>)
 288
 289 Removes a callback or data-set from collectd's internal list of
 290 functionsE<nbsp>/ datasets.
 291
 292 =item B<plugin_dispatch_values> (I<type>, I<value-list>)
 293
 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.
 298
 299 =item B<plugin_log> (I<log-level>, I<message>)
 300
 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.
 303
 304 =back
 305
 306 =head2 sensors
 307
 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.
 312
 313 The B<lm_sensors> homepage can be found at
 314 L<http://secure.netroedge.com/~lm78/>.
 315
 316 =head2 mbmon
 317
 318 The B<mbmon> module uses mbmon to retrieve temperature, voltage, etc.
 319
 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..
 325
 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.
 329
 330 =head2 hddtemp
 331
 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..
 337
 338 The B<hddtemp> homepage can be found at
 339 L<http://www.guzu.net/linux/hddtemp.php>.
 340
 341 =head2 vserver
 342
 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.
 348
 349 The B<VServer> homepage can be found at L<http://linux-vserver.org/>.
 350
 351 =head1 SEE ALSO
 352
 353 L<collectd.conf(5)>, L<rrdtool(1)>, L<sensors(1)>, L<hddtemp(8)>,
 354 L<mbmon(1)>,
 355 L<kstat(3KSTAT)>,
 356 L<http://collectd.org/>
 357
 358 =head1 AUTHOR
 359
 360 Florian Forster E<lt>octo@verplant.orgE<gt>
 361
 362 =cut