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 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)>,
  86 ...
  87
  88 =head1 SPECIAL PLUGINS
  89
  90 =head2 apache
  91
  92 This module connects to an Apache or lighttpd webserver and expects the output
  93 produced by B<mod_status.c>. If requires B<libcurl> to set up the HTTP
  94 connection and issue the request(s). The following is a sample config for the
  95 Apache webserver. Under Apache, the use of C<ExtendedStatus on> is mandatory.
  96
  97   ExtendedStatus on
  98   <IfModule mod_status.c>
  99     <Location /mod_status>
 100       SetHandler server-status
 101     </Location>
 102   </IfModule>
 103
 104 This plugin requires further configuration. Please read L<collectd.conf(5)>.
 105
 106 =head2 cpufreq
 107
 108 This module reads F</sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq> (for
 109 the first CPU installed) to get the current CPU frequency. If this file does
 110 not exist make sure B<cpufreqd> (L<http://cpufreqd.sourceforge.net/>) or a
 111 similar tool is installed and an "cpu governor" (that's kernel module) is
 112 loaded.
 113
 114 =head2 email
 115
 116 This plugin collects data indirectly by providing a UNIX socket that external
 117 programs can connect to. A simple line based protocol is used to communicate
 118 with the plugin:
 119
 120 E-Mail type (e.g. "ham", "spam", "virus", ...) and size (bytes):
 121
 122   e:<type>:<size>
 123
 124 If C<size> is less than or equal to zero, C<size> is ignored.
 125
 126 Spam score:
 127
 128   s:<value>
 129
 130 Successful spam checks (e.g. "BAYES_99", "SUBJECT_DRUG_GAP_C", ...):
 131
 132   c:<type1>[,<type2>,...]
 133
 134 Each line is limited to 256 characters (including the newline character).
 135 Longer lines will be ignored.
 136
 137 =head2 mysql
 138
 139 Requires B<mysqlclient> to be installed. It connects to the database when
 140 started and keeps the connection up as long as possible. When the connection is
 141 interrupted for whatever reason it will try to re-connect. The syslog will
 142 contain loud complaints in case anything goes wrong.
 143
 144 This plugin issues C<SHOW STATUS> and evaluates C<Bytes_{received,sent}>,
 145 C<Com_*> and C<Handler_*> which correspond to F<traffic-mysql.rrd>,
 146 F<mysql_commands-*.rrd> and F<mysql_handler-*.rrd>. Also, the values of
 147 C<Qcache_*> are put in F<mysql_qcache.rrd> and values of C<Threads_*> are put
 148 in F<mysql_threads.rrd>. Please refer to the B<MySQL reference manual>,
 149 I<5.2.4. Server Status Variables> for an explanation of these values.
 150
 151 =head2 perl
 152
 153 The C<perl plugin> includes a Perl-interpreter in collectd and provides
 154 Perl-equivalents of the plugin-functions. This makes it possible to write
 155 plugins in Perl.
 156
 157 There are two more complex types you need to know about:
 158
 159 =over 4
 160
 161 =item Data-Set
 162
 163 A data-set is a list of one or more data-sources. Each data-source defines a
 164 name, type, min- and max-value and the data-set wraps them up into one
 165 structure. The general layout looks like this:
 166
 167   [{
 168     name => 'data_source_name',
 169     type => DS_TYPE_COUNTER || DS_TYPE_GAUGE
 170     min  => value || undef,
 171     max  => value || undef
 172   }, ...]
 173
 174 =item Value-List
 175
 176 A value-list is one structure which features an array of values and fields to
 177 identify the values, i. e. time and host, plugin name and plugin-instance as
 178 well as a type and type-instance. Since the "type" is not included in the
 179 value-list but is passed as an extra argument, the general layout looks like
 180 this:
 181
 182   {
 183     values => [123, 0.5],
 184     time   => time (),
 185     host   => 'localhost',
 186     plugin => 'myplugin',
 187     plugin_instance => '',
 188     type_instance   => ''
 189   }
 190
 191 =back
 192
 193 The following functions provide the C-interface to Perl-modules:
 194
 195 =over 4
 196
 197 =item B<plugin_register> (I<type>, I<name>, I<data>)
 198
 199 Registers a callback-function or data-set.
 200
 201 I<type> can be one of:
 202
 203 =over 4
 204
 205 =item TYPE_INIT
 206
 207 =item TYPE_READ
 208
 209 =item TYPE_WRITE
 210
 211 =item TYPE_LOG
 212
 213 =item TYPE_SHUTDOWN
 214
 215 =item TYPE_DATASET
 216
 217 =back
 218
 219 I<name> is the name of the callback-function or the type of the data-set,
 220 depending on the value of I<type>. (Please note that the type of the data-set
 221 is the value passed as I<name> here and has nothing to do with the I<type>
 222 argument which simply tells B<plugin_register> what is being registered.)
 223
 224 The last argument, I<data>, is either a function- or an array-reference. If
 225 I<type> is B<TYPE_DATASET>, then the I<data> argument must be an
 226 array-reference which points to an array of hashes. Each hash describes one
 227 data-source. For the exact layout see B<Data-Set> above.
 228
 229 If the I<type> argument is any of the other types (B<TYPE_INIT>, B<TYPE_READ>,
 230 ...) then I<data> is expected to be a function reference. These functions are
 231 called in the various stages of the daemon and are passed the following
 232 arguments:
 233
 234 =over 4
 235
 236 =item TYPE_INIT
 237
 238 =item TYPE_READ
 239
 240 =item TYPE_SHUTDOWN
 241
 242 No arguments are passed
 243
 244 =item TYPE_WRITE
 245
 246 The arguments passed are I<type>, I<data-set>, and I<value-list>. I<type> is a
 247 string. For the layout of I<data-set> and I<value-list> see above.
 248
 249 =item TYPE_LOG
 250
 251 The arguments are I<log-level> and I<message>. The log level is small for
 252 important messages and high for less important messages. The least important
 253 level is B<LOG_DEBUG>, the most important level is B<LOG_ERR>. In between there
 254 are (from least to most important): B<LOG_INFO>, B<LOG_NOTICE>, and
 255 B<LOG_WARNING>. I<message> is simply a string B<without> a newline at the end.
 256
 257 =back
 258
 259 =item B<plugin_unregister> (I<type>, I<plugin>)
 260
 261 Removes a callback or data-set from collectd's internal list of
 262 functionsE<nbsp>/ datasets.
 263
 264 =item B<plugin_dispatch_values> (I<type>, I<value-list>)
 265
 266 Submits a I<value-list> of type I<type> to the daemon. If the data-set I<type>
 267 is found (and the number of values matches the number of data-sources) then the
 268 type, data-set and value-list is passed to all write-callbacks that are
 269 registered with the daemon.
 270
 271 =item B<plugin_log> (I<log-level>, I<message>)
 272
 273 Submits a I<message> of level I<log-level> to collectd's logging mechanism.
 274 The message is passed to all log-callbacks that are registered with collectd.
 275
 276 =back
 277
 278 =head2 sensors
 279
 280 The B<sensors> module uses lm_sensors to retrieve sensor-values. This means
 281 that all the needed modules have to be loaded and lm_sensors has to be
 282 configured (most likely by editing F</etc/sensors.conf>. Read
 283 L<sensors.conf(5)> for details.
 284
 285 The B<lm_sensors> homepage can be found at
 286 L<http://secure.netroedge.com/~lm78/>.
 287
 288 =head2 mbmon
 289
 290 The B<mbmon> module uses mbmon to retrieve temperature, voltage, etc.
 291
 292 collectd connects to B<localhost> (127.0.0.1), port B<411/tcp>.
 293 The B<Host> and B<Port> options can be used to change these
 294 default values. See L<collectd.conf(5)> for details. C<mbmon> has to be
 295 running to work correctly. If C<mbmon> is not running timeouts may appear
 296 which may interfere with other statistics..
 297
 298 C<mbmon> must be run with the -r option ("print TAG and Value format");
 299 Debian's /etc/init.d/mbmon script already does this, other people
 300 will need to ensure that this is the case.
 301
 302 =head2 hddtemp
 303
 304 To get values from B<hddtemp> collectd connects to B<localhost> (127.0.0.1),
 305 port B<7634/tcp>. The B<Host> and B<Port> options can be used to change these
 306 default values. See L<collectd.conf(5)> for details. C<hddtemp> has to be
 307 running to work correctly. If C<hddtemp> is not running timeouts may appear
 308 which may interfere with other statistics..
 309
 310 The B<hddtemp> homepage can be found at
 311 L<http://www.guzu.net/linux/hddtemp.php>.
 312
 313 =head2 vserver
 314
 315 B<VServer> support is only available for Linux. It cannot yet be found in a
 316 vanilla kernel, though. To make use of this plugin you need a kernel that has
 317 B<VServer> support built in, i.e. you need to apply the patches and compile
 318 your own kernel, which will then provide the /proc/virtual filesystem that is
 319 required by this plugin.
 320
 321 The B<VServer> homepage can be found at L<http://linux-vserver.org/>.
 322
 323 =head1 SEE ALSO
 324
 325 L<collectd.conf(5)>,
 326 L<collectd-exec(5)>,
 327 L<collectd-unixsock(5)>,
 328 L<hddtemp(8)>,
 329 L<kstat(3KSTAT)>,
 330 L<mbmon(1)>,
 331 L<rrdtool(1)>,
 332 L<sensors(1)>,
 333 L<http://collectd.org/>
 334
 335 =head1 AUTHOR
 336
 337 Florian Forster E<lt>octo@verplant.orgE<gt>
 338
 339 =cut