X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=src%2Fcollectd.conf.pod;h=d2e6843b858807c78ae9e9cd50a1e202fd3479ea;hb=9faff71de9d74939223192766c93e1d18c2d1186;hp=eee8c44dfb5a1918ab85246bc1d9346cd642bce6;hpb=50c381ea23f2107182c81bd982c057e9fc28a011;p=collectd.git

diff --git a/src/collectd.conf.pod b/src/collectd.conf.pod
index eee8c44d..d2e6843b 100644
--- a/src/collectd.conf.pod
+++ b/src/collectd.conf.pod
@@ -6,17 +6,20 @@ collectd.conf - Configuration for the system statistics collection daemon B<coll
 
 =head1 SYNOPSIS
 
-  BaseDir "/path/to/data/"
-  PIDFile "/path/to/pidfile/collectd.pid"
-  Server  "123.123.123.123" 12345
-
+  BaseDir "/var/lib/collectd"
+  PIDFile "/run/collectd.pid"
+  Interval 10.0
+  
   LoadPlugin cpu
   LoadPlugin load
-
+  
   <LoadPlugin df>
     Interval 3600
   </LoadPlugin>
-
+  <Plugin df>
+    ValuesPercentage true
+  </Plugin>
+  
   LoadPlugin ping
   <Plugin ping>
     Host "example.org"
@@ -28,7 +31,9 @@ collectd.conf - Configuration for the system statistics collection daemon B<coll
 This config file controls how the system statistics collection daemon
 B<collectd> behaves. The most significant option is B<LoadPlugin>, which
 controls which plugins to load. These plugins ultimately define collectd's
-behavior.
+behavior. If the B<AutoLoadPlugin> option has been enabled, the explicit
+B<LoadPlugin> lines may be omitted for all plugins with a configuration block,
+i.e. a C<E<lt>PluginE<nbsp>...E<gt>> block.
 
 The syntax of this config file is similar to the config file of the famous
 I<Apache> webserver. Each line contains either an option (a key and a list of
@@ -55,8 +60,9 @@ indenting the wrapped lines.
 The configuration is read and processed in order, i.e. from top to bottom. So
 the plugins are loaded in the order listed in this config file. It is a good
 idea to load any logging plugins first in order to catch messages from plugins
-during configuration. Also, the C<LoadPlugin> option B<must> occur B<before>
-the appropriate C<E<lt>Plugin ...E<gt>> block.
+during configuration. Also, unless B<AutoLoadPlugin> is enabled, the
+B<LoadPlugin> option I<must> occur I<before> the appropriate
+C<E<lt>B<Plugin> ...E<gt>> block.
 
 =head1 GLOBAL OPTIONS
 
@@ -140,6 +146,18 @@ B<E<lt>PluginE<nbsp>...E<gt>> block acts as if it was immediately preceded by a
 B<LoadPlugin> statement. B<LoadPlugin> statements are still required for
 plugins that don't provide any configuration, e.g. the I<Load plugin>.
 
+=item B<CollectInternalStats> B<false>|B<true>
+
+When set to B<true>, various statistics about the I<collectd> daemon will be
+collected, with "collectd" as the I<plugin name>. Defaults to B<false>.
+
+The "write_queue" I<plugin instance> reports the number of elements currently
+queued and the number of elements dropped off the queue by the
+B<WriteQueueLimitLow>/B<WriteQueueLimitHigh> mechanism.
+
+The "cache" I<plugin instance> reports the number of elements in the value list
+cache (the cache you can interact with using L<collectd-unixsock(5)>).
+
 =item B<Include> I<Path> [I<pattern>]
 
 If I<Path> points to a file, includes that file. If I<Path> points to a
@@ -212,6 +230,14 @@ B<Warning:> You should set this once and then never touch it again. If you do,
 I<you will have to delete all your RRD files> or know some serious RRDtool
 magic! (Assuming you're using the I<RRDtool> or I<RRDCacheD> plugin.)
 
+=item B<MaxReadInterval> I<Seconds>
+
+Read plugin doubles interval between queries after each failed attempt
+to get data.
+
+This options limits the maximum value of the interval. The default value is
+B<86400>.
+
 =item B<Timeout> I<Iterations>
 
 Consider a value list "missing" when no update has been read or received for
@@ -262,8 +288,11 @@ If B<WriteQueueLimitHigh> is set to non-zero and B<WriteQueueLimitLow> is
 unset, the latter will default to half of B<WriteQueueLimitHigh>.
 
 If you do not want to randomly drop values when the queue size is between
-I<LowNum> and I<HighNum>, set If B<WriteQueueLimitHigh> and
-B<WriteQueueLimitLow> to same value.
+I<LowNum> and I<HighNum>, set B<WriteQueueLimitHigh> and B<WriteQueueLimitLow>
+to the same value.
+
+Enabling the B<CollectInternalStats> option is of great help to figure out the
+values to set B<WriteQueueLimitHigh> and B<WriteQueueLimitLow> to.
 
 =item B<Hostname> I<Name>
 
@@ -952,6 +981,40 @@ Or you can figure it out from the path of the output data files.
 
 =back
 
+=head2 Plugin C<battery>
+
+The I<battery plugin> reports the remaining capacity, power and voltage of
+laptop batteries.
+
+=over 4
+
+=item B<ValuesPercentage> B<false>|B<true>
+
+When enabled, remaining capacity is reported as a percentage, e.g. "42%
+capacity remaining". Otherwise the capacity is stored as reported by the
+battery, most likely in "Wh". This option does not work with all input methods,
+in particular when only C</proc/pmu> is available on an old Linux system.
+Defaults to B<false>.
+
+=item B<ReportDegraded> B<false>|B<true>
+
+Typical laptop batteries degrade over time, meaning the capacity decreases with
+recharge cycles. The maximum charge of the previous charge cycle is tracked as
+"last full capacity" and used to determine that a battery is "fully charged".
+
+When this option is set to B<false>, the default, the I<battery plugin> will
+only report the remaining capacity. If the B<ValuesPercentage> option is
+enabled, the relative remaining capacity is calculated as the ratio of the
+"remaining capacity" and the "last full capacity". This is what most tools,
+such as the status bar of desktop environments, also do.
+
+When set to B<true>, the battery plugin will report three values: B<charged>
+(remaining capacity), B<discharged> (difference between "last full capacity"
+and "remaining capacity") and B<degraded> (difference between "design capacity"
+and "last full capacity").
+
+=back
+
 =head2 Plugin C<bind>
 
 Starting with BIND 9.5.0, the most widely used DNS server software provides
@@ -1144,29 +1207,53 @@ F</proc/sys/net/ipv4/netfilter> instead of F</proc/sys/net/netfilter/>.
 
 =head2 Plugin C<cpu>
 
-The I<CPU plugin> collects CPU usage metrics.
+The I<CPU plugin> collects CPU usage metrics. By default, CPU usage is reported
+as Jiffies, using the C<cpu> type. Two aggregations are available:
+
+=over 4
+
+=item
+
+Sum, per-state, over all CPUs installed in the system; and
+
+=item
+
+Sum, per-CPU, over all non-idle states of a CPU, creating an "active" state.
+
+=back
+
+The two aggregations can be combined, leading to I<collectd> only emitting a
+single "active" metric for the entire system. As soon as one of these
+aggregations (or both) is enabled, the I<cpu plugin> will report a percentage,
+rather than Jiffies. In addition, you can request individual, per-state,
+per-CPU metrics to be reported as percentage.
 
 The following configuration options are available:
 
 =over 4
 
-=item B<ReportActive> B<false>|B<true>
+=item B<ReportByState> B<true>|B<false>
 
-Reports non-idle CPU usage as the "active" value. Defaults to false.
+When set to B<true>, the default, reports per-state metrics, e.g. "system",
+"user" and "idle".
+When set to B<false>, aggregates (sums) all I<non-idle> states into one
+"active" metric.
 
-=item B<ReportByCpu> B<false>|B<true>
+=item B<ReportByCpu> B<true>|B<false>
 
-When true reports usage for all cores. When false, reports cpu usage
-aggregated over all cores.
-Defaults to true.
+When set to B<true>, the default, reports per-CPU (per-core) metrics.
+When set to B<false>, instead of reporting metrics for individual CPUs, only a
+global sum of CPU states is emitted.
 
 =item B<ValuesPercentage> B<false>|B<true>
 
-When true report percentage usage instead of tick values. Defaults to false.
+This option is only considered when both, B<ReportByCpu> and B<ReportByState>
+are set to B<true>. In this case, by default, metrics will be reported as
+Jiffies. By setting this option to B<true>, you can request percentage values
+in the un-aggregated (per-CPU, per-state) mode as well.
 
 =back
 
-
 =head2 Plugin C<cpufreq>
 
 This plugin doesn't have any options. It reads
@@ -3827,6 +3914,12 @@ behavior is to let the kernel choose the appropriate interface. Be warned
 that the manual selection of an interface for unicast traffic is only
 necessary in rare cases.
 
+=item B<ResolveInterval> I<Seconds>
+
+Sets the interval at which to re-resolve the DNS for the I<Host>. This is
+useful to force a regular DNS lookup to support a high availability setup. If
+not specified, re-resolves are never attempted.
+
 =back
 
 =item B<E<lt>Listen> I<Host> [I<Port>]B<E<gt>>
@@ -6660,7 +6753,7 @@ want to use authentication all three fields must be set.
 =head2 Plugin C<write_http>
 
 This output plugin submits values to an HTTP server using POST requests and
-encoding metircs with JSON or using the C<PUTVAL> command described in
+encoding metrics with JSON or using the C<PUTVAL> command described in
 L<collectd-unixsock(5)>. Each destination you want to post data to needs to
 have one B<URL> block, within which the destination can be configured further,
 for example by specifying authentication data.
@@ -6745,8 +6838,7 @@ Defaults to B<Command>.
 =item B<StoreRates> B<true|false>
 
 If set to B<true>, convert counter values to rates. If set to B<false> (the
-default) counter values are stored as is, i.E<nbsp>e. as an increasing integer
-number.
+default) counter values are stored as is, i.e. as an increasing integer number.
 
 =item B<BufferSize> I<Bytes>