+=encoding UTF-8
+
=head1 NAME
collectd.conf - Configuration for the system statistics collection daemon B<collectd>
Include "/etc/collectd.d/*.conf"
+Starting with version 5.3, this may also be a block in which further options
+affecting the behavior of B<Include> may be specified. The following option is
+currently allowed:
+
+ <Include "/etc/collectd.d">
+ Filter "*.conf"
+ </Include>
+
+=over 4
+
+=item B<Filter> I<pattern>
+
If the C<fnmatch> function is available on your system, a shell-like wildcard
I<pattern> may be specified to filter which files to include. This may be used
in combination with recursively including a directory to easily be able to
arbitrarily mix configuration files and other documents (e.g. README files).
-The following statement is similar to the example above but includes all files
+The given example is similar to the first example above but includes all files
matching C<*.conf> in any subdirectory of C</etc/collectd.d>:
Include "/etc/collectd.d" "*.conf"
+=back
+
If more than one files are included by a single B<Include> option, the files
will be included in lexicographical order (as defined by the C<strcmp>
function). Thus, you can e.E<nbsp>g. use numbered prefixes to specify the
default value is B<5>, but you may want to increase this if you have more than
five plugins that may take relatively long to write to.
+=item B<WriteQueueLimitHigh> I<HighNum>
+
+=item B<WriteQueueLimitLow> I<LowNum>
+
+Metrics are read by the I<read threads> and then put into a queue to be handled
+by the I<write threads>. If one of the I<write plugins> is slow (e.g. network
+timeouts, I/O saturation of the disk) this queue will grow. In order to avoid
+running into memory issues in such a case, you can limit the size of this
+queue.
+
+By default, there is no limit and memory may grow indefinitely. This is most
+likely not an issue for clients, i.e. instances that only handle the local
+metrics. For servers it is recommended to set this to a non-zero value, though.
+
+You can set the limits using B<WriteQueueLimitHigh> and B<WriteQueueLimitLow>.
+Each of them takes a numerical argument which is the number of metrics in the
+queue. If there are I<HighNum> metrics in the queue, any new metrics I<will> be
+dropped. If there are less than I<LowNum> metrics in the queue, all new metrics
+I<will> be enqueued. If the number of metrics currently in the queue is between
+I<LowNum> and I<HighNum>, the metric is dropped with a probability that is
+proportional to the number of metrics in the queue (i.e. it increases linearly
+until it reaches 100%.)
+
+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.
+
=item B<Hostname> I<Name>
Sets the hostname that identifies a host. If you omit this setting, the
=back
+=head2 Plugin C<aquaero>
+
+This plugin collects the value of the available sensors in an
+I<AquaeroE<nbsp>5> board. AquaeroE<nbsp>5 is a water-cooling controller board,
+manufactured by Aqua Computer GmbH L<http://www.aquacomputer.de/>, with a USB2
+connection for monitoring and configuration. The board can handle multiple
+temperature sensors, fans, water pumps and water level sensors and adjust the
+output settings such as fan voltage or power used by the water pump based on
+the available inputs using a configurable controller included in the board.
+This plugin collects all the available inputs as well as some of the output
+values chosen by this controller. The plugin is based on the I<libaquaero5>
+library provided by I<aquatools-ng>.
+
+=over 4
+
+=item B<Device> I<DevicePath>
+
+Device path of the AquaeroE<nbsp>5's USB HID (human interface device), usually
+in the form C</dev/usb/hiddevX>. If this option is no set the plugin will try
+to auto-detect the Aquaero 5 USB device based on vendor-ID and product-ID.
+
+=back
+
=head2 Plugin C<ascent>
This plugin collects information about an Ascent server, a free server for the
=head2 Plugin C<curl_json>
-The B<curl_json plugin> uses B<libcurl> (L<http://curl.haxx.se/>) and
-B<libyajl> (L<http://www.lloydforge.org/projects/yajl/>) to retrieve JSON data
-via cURL. This can be used to collect values from CouchDB documents (which are
-stored JSON notation), for example.
+The B<curl_json plugin> collects values from JSON data to be parsed by
+B<libyajl> (L<http://www.lloydforge.org/projects/yajl/>) retrieved via
+either B<libcurl> (L<http://curl.haxx.se/>) or read directly from a
+unix socket. The former can be used, for example, to collect values
+from CouchDB documents (which are stored JSON notation), and the
+latter to collect values from a uWSGI stats socket.
-The following example will collect several values from the built-in `_stats'
-runtime statistics module of CouchDB
+The following example will collect several values from the built-in
+C<_stats> runtime statistics module of I<CouchDB>
(L<http://wiki.apache.org/couchdb/Runtime_Statistics>).
<Plugin curl_json>
</URL>
</Plugin>
-In the B<Plugin> block, there may be one or more B<URL> blocks, each defining
-a URL to be fetched via HTTP (using libcurl) and one or more B<Key> blocks.
-The B<Key> string argument must be in a path format, which is used to collect a
-value from a JSON map object. If a path element of B<Key> is the
-I<*>E<nbsp>wildcard, the values for all keys will be collectd.
+This example will collect data directly from a I<uWSGI> "Stats Server" socket.
+
+ <Plugin curl_json>
+ <Sock "/var/run/uwsgi.stats.sock">
+ Instance "uwsgi"
+ <Key "workers/*/requests">
+ Type "http_requests"
+ </Key>
+
+ <Key "workers/*/apps/*/requests">
+ Type "http_requests"
+ </Key>
+ </Sock>
+ </Plugin>
+
+In the B<Plugin> block, there may be one or more B<URL> blocks, each
+defining a URL to be fetched via HTTP (using libcurl) or B<Sock>
+blocks defining a unix socket to read JSON from directly. Each of
+these blocks may have one or more B<Key> blocks.
+
+The B<Key> string argument must be in a path format. Each component is
+used to match the key from a JSON map or the index of an JSON
+array. If a path component of a B<Key> is a I<*>E<nbsp>wildcard, the
+values for all map keys or array indices will be collectd.
The following options are valid within B<URL> blocks:
many small files are stored on the disk. This is a usual scenario for mail
transfer agents and web caches.
+=item B<ValuesAbsolute> B<true>|B<false>
+
+Enables or disables reporting of free and used disk space in 1K-blocks.
+Defaults to B<true>.
+
+=item B<ValuesPercentage> B<false>|B<true>
+
+Enables or disables reporting of free and used disk space in percentage.
+Defaults to B<false>.
+
+This is useful for deploying I<collectd> on the cloud, where machines with
+different disk size may exist. Then it is more practical to configure
+thresholds based on relative disk size.
+
=back
=head2 Plugin C<disk>
=back
++=head2 Plugin C<load>
+
+The I<Load plugin> collects the system load. These numbers give a rough overview
+over the utilization of a machine. The system load is defined as the number of
+runnable tasks in the run-queue and is provided by many operating systems as a
+one, five or fifteen minute average.
+
+The following configuration options are available:
+
+=over 4
+
+=item B<ReportRelative> B<false>|B<true>
+
+When enabled, system load divided by number of available CPU cores is reported
+for intervals 1 min, 5 min and 15 min. Defaults to false.
+
+=back
+
+
=head2 Plugin C<logfile>
=over 4
Temperature vddg
Temperature vddq
IgnoreSelectedTemperature true
-
+
ShowPower true
Power total0
Power total1
- IgnoreSelectedPower true
+ IgnoreSelectedPower true
</Plugin>
The following options are valid inside the B<PluginE<nbsp>mic> block:
=item fout
-Fan Out
+Fan Out
=item vccp
=item total0
-Total power utilization averaged over Time Window 0 (uWatts).
+Total power utilization averaged over Time Window 0 (uWatts).
=item total1
-Total power utilization averaged over Time Window 0 (uWatts).
+Total power utilization averaged over Time Window 0 (uWatts).
=item inst
=item imax
-Max instantaneous power (uWatts).
+Max instantaneous power (uWatts).
=item pcie
-PCI-E connector power (uWatts).
+PCI-E connector power (uWatts).
=item c2x3
-2x3 connector power (uWatts).
+2x3 connector power (uWatts).
=item c2x4
-2x4 connector power (uWatts).
+2x4 connector power (uWatts).
=item vccp
-Core rail (uVolts).
+Core rail (uVolts).
=item vddg
-Uncore rail (uVolts).
+Uncore rail (uVolts).
=item vddq
-Memory subsystem rail (uVolts).
+Memory subsystem rail (uVolts).
=back
=back
+=head2 Plugin C<memory>
+
+The I<memory plugin> provides the following configuration options:
+
+=over 4
+
+=item B<ValuesAbsolute> B<true>|B<false>
+
+Enables or disables reporting of physical memory usage in absolute numbers,
+i.e. bytes. Defaults to B<true>.
+
+=item B<ValuesPercentage> B<false>|B<true>
+
+Enables or disables reporting of physical memory usage in percentages, e.g.
+percent of physical memory used. Defaults to B<false>.
+
+This is useful for deploying I<collectd> in a heterogeneous environment in
+which the sizes of physical memory vary.
+
+=back
+
=head2 Plugin C<modbus>
The B<modbus plugin> connects to a Modbus "slave" via Modbus/TCP and reads
=back
+=head2 Plugin C<sigrok>
+
+The I<sigrok plugin> uses I<libsigrok> to retrieve measurements from any device
+supported by the L<sigrok|http://sigrok.org/> project.
+
+B<Synopsis>
+
+ <Plugin sigrok>
+ LogLevel 3
+ <Device "AC Voltage">
+ Driver "fluke-dmm"
+ MinimumInterval 10
+ Conn "/dev/ttyUSB2"
+ </Device>
+ <Device "Sound Level">
+ Driver "cem-dt-885x"
+ Conn "/dev/ttyUSB1"
+ </Device>
+ </Plugin>
+
+=over 4
+
+=item B<LogLevel> B<0-5>
+
+The I<sigrok> logging level to pass on to the I<collectd> log, as a number
+between B<0> and B<5> (inclusive). These levels correspond to C<None>,
+C<Errors>, C<Warnings>, C<Informational>, C<Debug >and C<Spew>, respectively.
+The default is B<2> (C<Warnings>). The I<sigrok> log messages, regardless of
+their level, are always submitted to I<collectd> at its INFO log level.
+
+=item E<lt>B<Device> I<Name>E<gt>
+
+A sigrok-supported device, uniquely identified by this section's options. The
+I<Name> is passed to I<collectd> as the I<plugin instance>.
+
+=item B<Driver> I<DriverName>
+
+The sigrok driver to use for this device.
+
+=item B<Conn> I<ConnectionSpec>
+
+If the device cannot be auto-discovered, or more than one might be discovered
+by the driver, I<ConnectionSpec> specifies the connection string to the device.
+It can be of the form of a device path (e.g.E<nbsp>C</dev/ttyUSB2>), or, in
+case of a non-serial USB-connected device, the USB I<VendorID>B<.>I<ProductID>
+separated by a period (e.g.E<nbsp>C<0403.6001>). A USB device can also be
+specified as I<Bus>B<.>I<Address> (e.g.E<nbsp>C<1.41>).
+
+=item B<SerialComm> I<SerialSpec>
+
+For serial devices with non-standard port settings, this option can be used
+to specify them in a form understood by I<sigrok>, e.g.E<nbsp>C<9600/8n1>.
+This should not be necessary; drivers know how to communicate with devices they
+support.
+
+=item B<MinimumInterval> I<Seconds>
+
+Specifies the minimum time between measurement dispatches to I<collectd>, in
+seconds. Since some I<sigrok> supported devices can acquire measurements many
+times per second, it may be necessary to throttle these. For example, the
+I<RRD plugin> cannot process writes more than once per second.
+
+The default B<MinimumInterval> is B<0>, meaning measurements received from the
+device are always dispatched to I<collectd>. When throttled, unused
+measurements are discarded.
+
+=back
+
=head2 Plugin C<snmp>
Since the configuration of the C<snmp plugin> is a little more complicated than
other plugins, its documentation has been moved to an own manpage,
L<collectd-snmp(5)>. Please see there for details.
+=head2 Plugin C<statsd>
+
+The I<statsd plugin> listens to a UDP socket, reads "events" in the statsd
+protocol and dispatches rates or other aggregates of these numbers
+periodically.
+
+The plugin implements the I<Counter>, I<Timer>, I<Gauge> and I<Set> types which
+are dispatched as the I<collectd> types C<derive>, C<latency>, C<gauge> and
+C<objects> respectively.
+
+The following configuration options are valid:
+
+=over 4
+
+=item B<Host> I<Host>
+
+Bind to the hostname / address I<Host>. By default, the plugin will bind to the
+"any" address, i.e. accept packets sent to any of the hosts addresses.
+
+=item B<Port> I<Port>
+
+UDP port to listen to. This can be either a service name or a port number.
+Defaults to C<8125>.
+
+=item B<DeleteCounters> B<false>|B<true>
+
+=item B<DeleteTimers> B<false>|B<true>
+
+=item B<DeleteGauges> B<false>|B<true>
+
+=item B<DeleteSets> B<false>|B<true>
+
+These options control what happens if metrics are not updated in an interval.
+If set to B<False>, the default, metrics are dispatched unchanged, i.e. the
+rate of counters and size of sets will be zero, timers report C<NaN> and gauges
+are unchanged. If set to B<True>, the such metrics are not dispatched and
+removed from the internal cache.
+
+=item B<TimerPercentile> I<Percent>
+
+Calculate and dispatch the configured percentile, i.e. compute the latency, so
+that I<Percent> of all reported timers are smaller than or equal to the
+computed latency. This is useful for cutting off the long tail latency, as it's
+often done in I<Service Level Agreements> (SLAs).
+
+If not specified, no percentile is calculated / dispatched.
+
+=back
+
=head2 Plugin C<swap>
The I<Swap plugin> collects information about used and available swap space. On
When enabled, the I<swap I/O> is reported in bytes. When disabled, the default,
I<swap I/O> is reported in pages. This option is available under Linux only.
+=item B<ValuesAbsolute> B<true>|B<false>
+
+Enables or disables reporting of absolute swap metrics, i.e. number of I<bytes>
+available and used. Defaults to B<true>.
+
+=item B<ValuesPercentage> B<false>|B<true>
+
+Enables or disables reporting of relative swap metrics, i.e. I<percent>
+available and free. Defaults to B<false>.
+
+This is useful for deploying I<collectd> in a heterogeneous environment, where
+swap sizes differ and you want to specify generic thresholds or similar.
+
=back
=head2 Plugin C<syslog>
=head2 Plugin C<varnish>
-The Varnish plugin collects information about Varnish, an HTTP accelerator.
+The I<varnish plugin> collects information about Varnish, an HTTP accelerator.
+
+Synopsis:
+
+ <Plugin "varnish">
+ <Instance "example">
+ CollectCache true
+ CollectConnections true
+ CollectBackend true
+ CollectSHM true
+ CollectESI false
+ CollectFetch false
+ CollectHCB false
+ CollectSMA false
+ CollectSMS false
+ CollectSM false
+ CollectTotals false
+ CollectWorkers false
+ </Instance>
+ </Plugin>
+
+The configuration consists of one or more E<lt>B<Instance>E<nbsp>I<Name>E<gt>
+blocks. I<Name> is the parameter passed to "varnishd -n". If left empty, it
+will collectd statistics from the default "varnishd" instance (this should work
+fine in most cases).
+
+Inside each E<lt>B<Instance>E<gt> blocks, the following options are recognized:
=over 4
The C<write_graphite> plugin writes data to I<Graphite>, an open-source metrics
storage and graphing project. The plugin connects to I<Carbon>, the data layer
-of I<Graphite>, and sends data via the "line based" protocol (per default using
-portE<nbsp>2003). The data will be sent in blocks of at most 1428 bytes to
-minimize the number of network packets.
+of I<Graphite>, via I<TCP> or I<UDP> and sends data via the "line based"
+protocol (per default using portE<nbsp>2003). The data will be sent in blocks
+of at most 1428 bytes to minimize the number of network packets.
Synopsis:
<Node "example">
Host "localhost"
Port "2003"
+ Protocol "tcp"
+ LogSendErrors true
Prefix "collectd"
</Node>
</Plugin>
Service name or port number to connect to. Defaults to C<2003>.
+=item B<Protocol> I<String>
+
+Protocol to use when connecting to I<Graphite>. Defaults to C<tcp>.
+
+=item B<LogSendErrors> B<false>|B<true>
+
+If set to B<true> (the default), logs errors when sending data to I<Graphite>.
+If set to B<false>, it will not log the errors. This is especially useful when
+using Protocol UDP since many times we want to use the "fire-and-forget"
+approach and logging errors fills syslog with unneeded messages.
+
=item B<Prefix> I<String>
When set, I<String> is added in front of the host name. Dots and whitespace are
Protocol UDP
StoreRates true
AlwaysAppendDS false
- Delay 10
+ TTLFactor 2.0
</Node>
Tag "foobar"
+ Attribute "foo" "bar"
</Plugin>
The following options are understood by the I<write_riemann plugin>:
identifies a metric in I<Riemann>. If set to B<false> (the default), this is
only done when there is more than one DS.
+=item B<TTLFactor> I<Factor>
+
+I<Riemann> events have a I<Time to Live> (TTL) which specifies how long each
+event is considered active. I<collectd> populates this field based on the
+metrics interval setting. This setting controls the factor with which the
+interval is multiplied to set the TTL. The default value is B<2.0>. Unless you
+know exactly what you're doing, you should only increase this setting from its
+default value.
+
=back
=item B<Tag> I<String>
Add the given string as an additional tag to the metric being sent to
I<Riemann>.
+=item B<Attribute> I<String> I<String>
+
+Consider the two given strings to be the key and value of an additional
+attribute for each metric being sent out to I<Riemann>.
+
=back
=head1 THRESHOLD CONFIGURATION
Here is a configuration example to get you started. Read below for more
information.
- <Threshold>
+ <Plugin threshold>
<Type "foo">
WarningMin 0.00
WarningMax 1000.00
</Type>
</Plugin>
</Host>
- </Threshold>
+ </Plugin>
There are basically two types of configuration statements: The C<Host>,
C<Plugin>, and C<Type> blocks select the value for which a threshold should be
projects / collectd.git / blobdiff