=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"
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
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
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
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
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>
# StoreRates false
# GraphitePrefix "collectd."
# GraphiteEscapeChar "_"
+ # GraphiteSeparateInstances false
+ # GraphiteAlwaysAppendDS false
</Publish>
# Receive values from an AMQP broker
metric parts (host, plugin, type).
Default is "_" (I<Underscore>).
+=item B<GraphiteSeparateInstances> B<true>|B<false>
+
+If set to B<true>, the plugin instance and type instance will be in their own
+path component, for example C<host.cpu.0.cpu.idle>. If set to B<false> (the
+default), the plugin and plugin instance (and likewise the type and type
+instance) are put into one component, for example C<host.cpu-0.cpu-idle>.
+
+=item B<GraphiteAlwaysAppendDS> B<true>|B<false>
+
+If set to B<true>, append the name of the I<Data Source> (DS) to the "metric"
+identifier. If set to B<false> (the default), this is only done when there is
+more than one DS.
+
=back
=head2 Plugin C<apache>
=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
=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
URL "http://finance.google.com/finance?q=NYSE%3AAMD"
User "foo"
Password "bar"
+ Digest false
+ VerifyPeer true
+ VerifyHost true
+ CACert "/path/to/ca.crt"
+ Header "X-Custom-Header: foobar"
+ Post "foo=bar"
+
+ MeasureResponseTime false
+ MeasureResponseCode false
+
<Match>
Regex "<span +class=\"pr\"[^>]*> *([0-9]*\\.[0-9]+) *</span>"
DSType "GaugeAverage"
Measure response time for the request. If this setting is enabled, B<Match>
blocks (see below) are optional. Disabled by default.
+=item B<MeasureResponseCode> B<true>|B<false>
+
+Measure response code for the request. If this setting is enabled, B<Match>
+blocks (see below) are optional. Disabled by default.
+
=item B<E<lt>MatchE<gt>>
One or more B<Match> blocks that define how to match information in the data
returned by C<libcurl>. The C<curl> plugin uses the same infrastructure that's
used by the C<tail> plugin, so please see the documentation of the C<tail>
-plugin below on how matches are defined. If the B<MeasureResponseTime> option
-is set to B<true>, B<Match> blocks are optional.
+plugin below on how matches are defined. If the B<MeasureResponseTime> or
+B<MeasureResponseCode> options are set to B<true>, B<Match> blocks are
+optional.
=back
VerifyPeer true
VerifyHost true
CACert "/path/to/ca.crt"
+ Header "X-Custom-Header: foobar"
+ Post "foo=bar"
<XPath "table[@id=\"magic_level\"]/tr">
Type "magic_level"
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>>
=item B<AlwaysAppendDS> B<false>|B<true>
+If set to B<true>, append the name of the I<Data Source> (DS) to the "metric"
+identifier. If set to B<false> (the default), this is only done when there is
+more than one DS.
+
+=back
+
+=head2 Plugin C<write_tsdb>
+
+The C<write_tsdb> plugin writes data to I<OpenTSDB>, a scalable open-source
+time series database. The plugin connects to a I<TSD>, a masterless, no shared
+state daemon that ingests metrics and stores them in HBase. The plugin uses
+I<TCP> over the "line based" protocol with a default port 4242. The data will
+be sent in blocks of at most 1428 bytes to minimize the number of network
+packets.
+
+Synopsis:
+
+ <Plugin write_tsdb>
+ <Node "example">
+ Host "tsd-1.my.domain"
+ Port "4242"
+ HostTags "status=production"
+ </Node>
+ </Plugin>
+
+The configuration consists of one or more E<lt>B<Node>E<nbsp>I<Name>E<gt>
+blocks. Inside the B<Node> blocks, the following options are recognized:
+
+=over 4
+
+=item B<Host> I<Address>
+
+Hostname or address to connect to. Defaults to C<localhost>.
+
+=item B<Port> I<Service>
+
+Service name or port number to connect to. Defaults to C<4242>.
+
+
+=item B<HostTags> I<String>
+
+When set, I<HostTags> is added to the end of the metric. It is intended to be
+used for name=value pairs that the TSD will tag the metric with. Dots and
+whitespace are I<not> escaped in this string.
+
+=item B<StoreRates> B<false>|B<true>
+
+If set to B<true>, convert counter values to rates. If set to B<false>
+(the default) counter values are stored as is, as an increasing
+integer number.
+
+=item B<AlwaysAppendDS> B<false>|B<true>
+
If set the B<true>, append the name of the I<Data Source> (DS) to the "metric"
identifier. If set to B<false> (the default), this is only done when there is
more than one DS.
=head2 Plugin C<write_http>
-This output plugin submits values to an http server by POST them using the
-PUTVAL plain-text protocol. Each destination you want to post data to needs to
+This output plugin submits values to an HTTP server using POST requests and
+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.
<URL "http://example.com/post-collectd">
User "collectd"
Password "weCh3ik0"
+ Format JSON
</URL>
</Plugin>
=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>
+
+Sets the send buffer size to I<Bytes>. By increasing this buffer, less HTTP
+requests will be generated, but more metrics will be batched / metrics are
+cached for longer before being sent, introducing additional delay until they
+are available on the server side. I<Bytes> must be at least 1024 and cannot
+exceed the size of an C<int>, i.e. 2E<nbsp>GByte.
+Defaults to C<4096>.
=back
an easy and straight forward exchange format.
If set to B<Graphite>, values are encoded in the I<Graphite> format, which is
-"<metric> <value> <timestamp>\n".
+C<E<lt>metricE<gt> E<lt>valueE<gt> E<lt>timestampE<gt>\n>.
=item B<StoreRates> B<true>|B<false>
=item B<GraphitePrefix> (B<Format>=I<Graphite> only)
-A prefix can be added in the metric name when outputting in the I<Graphite> format.
-It's added before the I<Host> name.
-Metric name will be "<prefix><host><postfix><plugin><type><name>"
+A prefix can be added in the metric name when outputting in the I<Graphite>
+format. It's added before the I<Host> name.
+Metric name will be
+C<E<lt>prefixE<gt>E<lt>hostE<gt>E<lt>postfixE<gt>E<lt>pluginE<gt>E<lt>typeE<gt>E<lt>nameE<gt>>
=item B<GraphitePostfix> (B<Format>=I<Graphite> only)
-A postfix can be added in the metric name when outputting in the I<Graphite> format.
-It's added after the I<Host> name.
-Metric name will be "<prefix><host><postfix><plugin><type><name>"
+A postfix can be added in the metric name when outputting in the I<Graphite>
+format. It's added after the I<Host> name.
+Metric name will be
+C<E<lt>prefixE<gt>E<lt>hostE<gt>E<lt>postfixE<gt>E<lt>pluginE<gt>E<lt>typeE<gt>E<lt>nameE<gt>>
=item B<GraphiteEscapeChar> (B<Format>=I<Graphite> only)
Specify a character to replace dots (.) in the host part of the metric name.
In I<Graphite> metric name, dots are used as separators between different
metric parts (host, plugin, type).
-Default is "_" (I<Underscore>).
+Default is C<_> (I<Underscore>).
=item B<GraphiteSeparateInstances> B<false>|B<true>
=item B<EventServicePrefix> I<String>
Add the given string as a prefix to the event service name.
-if B<EventServicePrefix> not set or set to an empty string (""),
+If B<EventServicePrefix> not set or set to an empty string (""),
no prefix will be used.
=back
=item B<Plugin> I<Name>
Name of the write plugin to which the data should be sent. This option may be
-given multiple times to send the data to more than one write plugin.
+given multiple times to send the data to more than one write plugin. If the
+plugin supports multiple instances, the plugin's instance(s) must also be
+specified.
=back
If no plugin is explicitly specified, the values will be sent to all available
write plugins.
-Example:
+Single-instance plugin example:
<Target "write">
Plugin "rrdtool"
</Target>
+Multi-instance plugin example:
+
+ <Plugin "write_graphite">
+ <Node "foo">
+ ...
+ </Node>
+ <Node "bar">
+ ...
+ </Node>
+ </Plugin>
+ ...
+ <Target "write">
+ Plugin "write_graphite/foo"
+ </Target>
+
=item B<jump>
Starts processing the rules of another chain, see L<"Flow control"> above. If