src/collectd.pod

   1 =encoding UTF-8
   2
   3 =head1 NAME
   4
   5 collectd - System statistics collection daemon
   6
   7 =head1 SYNOPSIS
   8
   9 collectd I<[options]>
  10
  11 =head1 DESCRIPTION
  12
  13 collectd is a daemon that receives system statistics and makes them available
  14 in a number of ways. The main daemon itself doesn't have any real functionality
  15 apart from loading, querying and submitting to plugins. For a description of
  16 available plugins please see L</PLUGINS> below.
  17
  18 =head1 OPTIONS
  19
  20 Most of collectd's configuration is done using using a configfile. See
  21 L<collectd.conf(5)> for an in-depth description of all options.
  22
  23 =over 4
  24
  25 =item B<-C> I<E<lt>config-fileE<gt>>
  26
  27 Specify an alternative config file. This is the place to go when you wish to
  28 change B<collectd>'s behavior. The path may be relative to the current working
  29 directory.
  30
  31 =item B<-t>
  32
  33 Test the configuration only. The program immediately exits after parsing the
  34 config file. A return code not equal to zero indicates an error.
  35
  36 =item B<-T>
  37
  38 Test the plugin read callbacks only. The program immediately exits after invoking
  39 the read callbacks once. A return code not equal to zero indicates an error.
  40
  41 =item B<-P> I<E<lt>pid-fileE<gt>>
  42
  43 Specify an alternative pid file. This overwrites any settings in the config
  44 file. This is thought for init-scripts that require the PID-file in a certain
  45 directory to work correctly. For everyday-usage use the B<PIDFile>
  46 config-option.
  47
  48 =item B<-B>
  49
  50 If set, collectd will I<not> try to create its base directory. If the base
  51 directory does not exist, it will exit rather than trying to create the
  52 directory.
  53
  54 =item B<-f>
  55
  56 Don't fork to the background. I<collectd> will also B<not> close standard file
  57 descriptors, detach from the session nor write a pid file. This is mainly
  58 thought for 'supervising' init replacements such as I<runit>. If using
  59 I<upstart> or I<systemd> though, starting with version 5.5.0 I<collectd> is
  60 able to notify these two init replacements, and B<does> require forking to the
  61 background for process supervision. The F<contrib/> directory has sample
  62 I<upstart> and I<systemd> configuration files.
  63
  64 =item B<-h>
  65
  66 Output usage information and exit.
  67
  68 =back
  69
  70 =head1 PLUGINS
  71
  72 As noted above, the real power of collectd lies within it's plugins. A
  73 (hopefully complete) list of plugins and short descriptions can be found in the
  74 F<README> file that is distributed with the sourcecode. If you're using a
  75 package it's a good bet to search somewhere near F</usr/share/doc/collectd>.
  76
  77 There are two big groups of plugins, B<input> and B<output> plugins:
  78
  79 =over 4
  80
  81 =item *
  82
  83 Input plugins are queried periodically. They somehow acquire the current value
  84 of whatever they where designed to work with and submit these values back to
  85 the daemon, i. e. they "dispatch" the values. As an example, the C<cpu plugin>
  86 reads the current cpu-counters of time spent in the various modes (user,
  87 system, nice, ...) and dispatches these counters to the daemon.
  88
  89 =item *
  90
  91 Output plugins get the dispatched values from the daemon and does something
  92 with them. Common applications are writing to RRD-files, CSV-files or sending
  93 the data over a network link to a remote box.
  94
  95 =back
  96
  97 Of course not all plugins fit neatly into one of the two above categories. The
  98 C<network plugin>, for example, is able to send (i.E<nbsp>e. "write") B<and>
  99 receive (i.E<nbsp>e. "dispatch") values. Also, it opens a socket upon
 100 initialization and dispatches the values when it receives them and isn't
 101 triggered at the same time the input plugins are being read. You can think of
 102 the network receive part as working asynchronous if it helps.
 103
 104 In addition to the above, there are "logging plugins". Right now those are the
 105 C<logfile plugin> and the C<syslog plugin>. With these plugins collectd can
 106 provide information about issues and significant situations to the user.
 107 Several loglevels let you suppress uninteresting messages.
 108
 109 Starting with version C<4.3.0> collectd has support for B<monitoring>. This is
 110 done by checking thresholds defined by the user. If a value is out of range, a
 111 notification will be dispatched to "notification plugins". See
 112 L<collectd.conf(5)> for more detailed information about threshold checking.
 113
 114 Please note that some plugins, that provide other means of communicating with
 115 the daemon, have manpages of their own to describe their functionality in more
 116 detail. In particular those are L<collectd-email(5)>, L<collectd-exec(5)>,
 117 L<collectd-perl(5)>, L<collectd-snmp(5)>, and L<collectd-unixsock(5)>
 118
 119 =head1 SIGNALS
 120
 121 B<collectd> accepts the following signals:
 122
 123 =over 4
 124
 125 =item B<SIGINT>, B<SIGTERM>
 126
 127 These signals cause B<collectd> to shut down all plugins and terminate.
 128
 129 =item B<SIGUSR1>
 130
 131 This signal causes B<collectd> to signal all plugins to flush data from
 132 internal caches. E.E<nbsp>g. the C<rrdtool plugin> will write all pending data
 133 to the RRD files. This is the same as using the C<FLUSH -1> command of the
 134 C<unixsock plugin>.
 135
 136 =back
 137
 138 =head1 SEE ALSO
 139
 140 L<collectd.conf(5)>,
 141 L<collectd-email(5)>,
 142 L<collectd-exec(5)>,
 143 L<collectd-perl(5)>,
 144 L<collectd-snmp(5)>,
 145 L<collectd-unixsock(5)>,
 146 L<types.db(5)>,
 147 L<http://collectd.org/>
 148
 149 =head1 AUTHOR
 150
 151 Florian Forster E<lt>octo@collectd.orgE<gt>
 152
 153 =cut