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 perl
  91
  92 The C<perl plugin> includes a Perl-interpreter in collectd and provides
  93 Perl-equivalents of the plugin-functions. This makes it possible to write
  94 plugins in Perl.
  95
  96 There are two more complex types you need to know about:
  97
  98 =over 4
  99
 100 =item Data-Set
 101
 102 A data-set is a list of one or more data-sources. Each data-source defines a
 103 name, type, min- and max-value and the data-set wraps them up into one
 104 structure. The general layout looks like this:
 105
 106   [{
 107     name => 'data_source_name',
 108     type => DS_TYPE_COUNTER || DS_TYPE_GAUGE
 109     min  => value || undef,
 110     max  => value || undef
 111   }, ...]
 112
 113 =item Value-List
 114
 115 A value-list is one structure which features an array of values and fields to
 116 identify the values, i. e. time and host, plugin name and plugin-instance as
 117 well as a type and type-instance. Since the "type" is not included in the
 118 value-list but is passed as an extra argument, the general layout looks like
 119 this:
 120
 121   {
 122     values => [123, 0.5],
 123     time   => time (),
 124     host   => 'localhost',
 125     plugin => 'myplugin',
 126     plugin_instance => '',
 127     type_instance   => ''
 128   }
 129
 130 =back
 131
 132 The following functions provide the C-interface to Perl-modules:
 133
 134 =over 4
 135
 136 =item B<plugin_register> (I<type>, I<name>, I<data>)
 137
 138 Registers a callback-function or data-set.
 139
 140 I<type> can be one of:
 141
 142 =over 4
 143
 144 =item TYPE_INIT
 145
 146 =item TYPE_READ
 147
 148 =item TYPE_WRITE
 149
 150 =item TYPE_LOG
 151
 152 =item TYPE_SHUTDOWN
 153
 154 =item TYPE_DATASET
 155
 156 =back
 157
 158 I<name> is the name of the callback-function or the type of the data-set,
 159 depending on the value of I<type>. (Please note that the type of the data-set
 160 is the value passed as I<name> here and has nothing to do with the I<type>
 161 argument which simply tells B<plugin_register> what is being registered.)
 162
 163 The last argument, I<data>, is either a function- or an array-reference. If
 164 I<type> is B<TYPE_DATASET>, then the I<data> argument must be an
 165 array-reference which points to an array of hashes. Each hash describes one
 166 data-source. For the exact layout see B<Data-Set> above.
 167
 168 If the I<type> argument is any of the other types (B<TYPE_INIT>, B<TYPE_READ>,
 169 ...) then I<data> is expected to be a function reference. These functions are
 170 called in the various stages of the daemon and are passed the following
 171 arguments:
 172
 173 =over 4
 174
 175 =item TYPE_INIT
 176
 177 =item TYPE_READ
 178
 179 =item TYPE_SHUTDOWN
 180
 181 No arguments are passed
 182
 183 =item TYPE_WRITE
 184
 185 The arguments passed are I<type>, I<data-set>, and I<value-list>. I<type> is a
 186 string. For the layout of I<data-set> and I<value-list> see above.
 187
 188 =item TYPE_LOG
 189
 190 The arguments are I<log-level> and I<message>. The log level is small for
 191 important messages and high for less important messages. The least important
 192 level is B<LOG_DEBUG>, the most important level is B<LOG_ERR>. In between there
 193 are (from least to most important): B<LOG_INFO>, B<LOG_NOTICE>, and
 194 B<LOG_WARNING>. I<message> is simply a string B<without> a newline at the end.
 195
 196 =back
 197
 198 =item B<plugin_unregister> (I<type>, I<plugin>)
 199
 200 Removes a callback or data-set from collectd's internal list of
 201 functionsE<nbsp>/ datasets.
 202
 203 =item B<plugin_dispatch_values> (I<type>, I<value-list>)
 204
 205 Submits a I<value-list> of type I<type> to the daemon. If the data-set I<type>
 206 is found (and the number of values matches the number of data-sources) then the
 207 type, data-set and value-list is passed to all write-callbacks that are
 208 registered with the daemon.
 209
 210 =item B<plugin_log> (I<log-level>, I<message>)
 211
 212 Submits a I<message> of level I<log-level> to collectd's logging mechanism.
 213 The message is passed to all log-callbacks that are registered with collectd.
 214
 215 =back
 216
 217 =head1 SEE ALSO
 218
 219 L<collectd.conf(5)>,
 220 L<collectd-email(5)>,
 221 L<collectd-exec(5)>,
 222 L<collectd-unixsock(5)>,
 223 L<http://collectd.org/>
 224
 225 =head1 AUTHOR
 226
 227 Florian Forster E<lt>octo@verplant.orgE<gt>
 228
 229 =cut