Merge branch 'collectd-5.4' into collectd-5.5

[collectd.git] / src / collectd.conf.pod

diff --git a/src/collectd.conf.pod b/src/collectd.conf.pod
index a7a5816..e5a5c75 100644 (file)
--- a/src/collectd.conf.pod
+++ b/src/collectd.conf.pod
@@ -150,12 +150,27 @@ plugins that don't provide any configuration, e.g. the I<Load plugin>.
 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>.
 
 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 following metrics are reported:

 
 

-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)>).
+=over 4
+
+=item C<collectd-write_queue/queue_length>
+
+The number of metrics currently in the write queue. You can limit the queue
+length with the B<WriteQueueLimitLow> and B<WriteQueueLimitHigh> options.
+
+=item C<collectd-write_queue/derive-dropped>
+
+The number of metrics dropped due to a queue length limitation.
+If this value is non-zero, your system can't handle all incoming metrics and
+protects itself against overload by dropping metrics.
+
+=item C<collectd-cache/cache_size>
+
+The number of elements in the metric cache (the cache you can interact with
+using L<collectd-unixsock(5)>).
+
+=back

 
 =item B<Include> I<Path> [I<pattern>]
 
 
 =item B<Include> I<Path> [I<pattern>]
 


@@ -184,9 +199,7 @@ 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 given example is similar to the first example above but includes all files
 in combination with recursively including a directory to easily be able to
 arbitrarily mix configuration files and other documents (e.g. README 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"
+matching C<*.conf> in any subdirectory of C</etc/collectd.d>.

 
 =back
 
 
 =back
 


@@ -382,13 +395,13 @@ There are a couple of limitations you should be aware of:
 
 =over 4
 
 
 =over 4
 

-=item
+=item *

 
 The I<Type> cannot be left unspecified, because it is not reasonable to add
 apples to oranges. Also, the internal lookup structure won't work if you try
 to group by type.
 
 
 The I<Type> cannot be left unspecified, because it is not reasonable to add
 apples to oranges. Also, the internal lookup structure won't work if you try
 to group by type.
 

-=item
+=item *

 
 There must be at least one unspecified, ungrouped field. Otherwise nothing
 will be aggregated.
 
 There must be at least one unspecified, ungrouped field. Otherwise nothing
 will be aggregated.


@@ -463,19 +476,19 @@ This will create the files:
 
 =over 4
 
 
 =over 4
 

-=item
+=item *

 
 foo.example.com/cpu-even-average/cpu-idle
 
 
 foo.example.com/cpu-even-average/cpu-idle
 

-=item
+=item *

 
 foo.example.com/cpu-even-average/cpu-system
 
 
 foo.example.com/cpu-even-average/cpu-system
 

-=item
+=item *

 
 foo.example.com/cpu-even-average/cpu-user
 
 
 foo.example.com/cpu-even-average/cpu-user
 

-=item
+=item *

 
 ...
 
 
 ...
 


@@ -501,7 +514,7 @@ are disabled by default.
 
 =head2 Plugin C<amqp>
 
 
 =head2 Plugin C<amqp>
 

-The I<AMQMP plugin> can be used to communicate with other instances of
+The I<AMQP plugin> can be used to communicate with other instances of

 I<collectd> or third party applications using an AMQP message broker. Values
 are sent to or received from the broker, which handles routing, queueing and
 possibly filtering or messages.
 I<collectd> or third party applications using an AMQP message broker. Values
 are sent to or received from the broker, which handles routing, queueing and
 possibly filtering or messages.


@@ -1345,11 +1358,11 @@ as Jiffies, using the C<cpu> type. Two aggregations are available:
 
 =over 4
 
 
 =over 4
 

-=item
+=item *

 
 Sum, per-state, over all CPUs installed in the system; and
 
 
 Sum, per-state, over all CPUs installed in the system; and
 

-=item
+=item *

 
 Sum, per-CPU, over all non-idle states of a CPU, creating an "active" state.
 
 
 Sum, per-CPU, over all non-idle states of a CPU, creating an "active" state.
 


@@ -1546,7 +1559,7 @@ setting accordingly to prevent this from blocking other plugins.
 =head2 Plugin C<curl_json>
 
 The B<curl_json plugin> collects values from JSON data to be parsed by
 =head2 Plugin C<curl_json>
 
 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
+B<libyajl> (L<https://lloyd.github.io/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
 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


@@ -2264,6 +2277,27 @@ expected from them. This is documented in great detail in L<collectd-exec(5)>.
 
 =back
 
 
 =back
 

+=head2 Plugin C<fhcount>
+
+The C<fhcount> plugin provides statistics about used, unused and total number of
+file handles on Linux.
+
+The I<fhcount plugin> provides the following configuration options:
+
+=over 4
+
+=item B<ValuesAbsolute> B<true>|B<false>
+
+Enables or disables reporting of file handles usage in absolute numbers,
+e.g. file handles used. Defaults to B<true>.
+
+=item B<ValuesPercentage> B<false>|B<true>
+
+Enables or disables reporting of file handles usage in percentages, e.g.
+percent of file handles used. Defaults to B<false>.
+
+=back
+

 =head2 Plugin C<filecount>
 
 The C<filecount> plugin counts the number of files in a certain directory (and
 =head2 Plugin C<filecount>
 
 The C<filecount> plugin counts the number of files in a certain directory (and


@@ -2468,7 +2502,7 @@ a more detailed description see B<IgnoreSelected> below.
 
 =item B<IgnoreSelected> I<true>|I<false>
 
 
 =item B<IgnoreSelected> I<true>|I<false>
 

-If no configuration if given, the B<traffic>-plugin will collect data from
+If no configuration if given, the B<interface>-plugin will collect data from

 all interfaces. This may not be practical, especially for loopback- and
 similar interfaces. Thus, you can use the B<Interface>-option to pick the
 interfaces you're interested in. Sometimes, however, it's easier/preferred
 all interfaces. This may not be practical, especially for loopback- and
 similar interfaces. Thus, you can use the B<Interface>-option to pick the
 interfaces you're interested in. Sometimes, however, it's easier/preferred


@@ -2477,6 +2511,23 @@ do that: By setting B<IgnoreSelected> to I<true> the effect of
 B<Interface> is inverted: All selected interfaces are ignored and all
 other interfaces are collected.
 
 B<Interface> is inverted: All selected interfaces are ignored and all
 other interfaces are collected.
 

+It is possible to use regular expressions to match interface names, if the
+name is surrounded by I</.../> and collectd was compiled with support for
+regexps. This is useful if there's a need to collect (or ignore) data
+for a group of interfaces that are similarly named, without the need to
+explicitly list all of them (especially useful if the list is dynamic).
+Example:
+
+ Interface "lo"
+ Interface "/^veth/"
+ Interface "/^tun[0-9]+/"
+ IgnoreSelected "true"
+
+This will ignore the loopback interface, all interfaces with names starting
+with I<veth> and all interfaces with names starting with I<tun> followed by
+at least one digit.
+
+

 =back
 
 =head2 Plugin C<ipmi>
 =back
 
 =head2 Plugin C<ipmi>


@@ -2517,9 +2568,13 @@ a notification is sent.
 
 =item B<Chain> I<Table> I<Chain> [I<Comment|Number> [I<Name>]]
 
 
 =item B<Chain> I<Table> I<Chain> [I<Comment|Number> [I<Name>]]
 

-Select the rules to count. If only I<Table> and I<Chain> are given, this plugin
-will collect the counters of all rules which have a comment-match. The comment
-is then used as type-instance.
+=item B<Chain6> I<Table> I<Chain> [I<Comment|Number> [I<Name>]]
+
+Select the iptables/ip6tables filter rules to count packets and bytes from.
+
+If only I<Table> and I<Chain> are given, this plugin will collect the counters
+of all rules which have a comment-match. The comment is then used as
+type-instance.

 
 If I<Comment> or I<Number> is given, only the rule with the matching comment or
 the I<n>th rule will be collected. Again, the comment (or the number) will be
 
 If I<Comment> or I<Number> is given, only the rule with the matching comment or
 the I<n>th rule will be collected. Again, the comment (or the number) will be


@@ -4250,6 +4305,18 @@ Default: C<Collectd notify: %s@%s>
 
 =head2 Plugin C<ntpd>
 
 
 =head2 Plugin C<ntpd>
 

+The C<ntpd> plugin collects per-peer ntp data such as time offset and time
+dispersion.
+
+For talking to B<ntpd>, it mimics what the B<ntpdc> control program does on
+the wire - using B<mode 7> specific requests. This mode is deprecated with
+newer B<ntpd> releases (4.2.7p230 and later). For the C<ntpd> plugin to work
+correctly with them, the ntp daemon must be explicitly configured to
+enable B<mode 7> (which is disabled by default). Refer to the I<ntp.conf(5)>
+manual page for details.
+
+Available configuration options for the C<ntpd> plugin:
+

 =over 4
 
 =item B<Host> I<Hostname>
 =over 4
 
 =item B<Host> I<Hostname>


@@ -5392,6 +5459,9 @@ collected for these selected processes are size of the resident segment size
 (RSS), user- and system-time used, number of processes and number of threads,
 io data (where available) and minor and major pagefaults.
 
 (RSS), user- and system-time used, number of processes and number of threads,
 io data (where available) and minor and major pagefaults.
 

+Some platforms have a limit on the length of process names. I<Name> must stay
+below this limit.
+

 =item B<ProcessMatch> I<name> I<regex>
 
 Similar to the B<Process> option this allows to select more detailed
 =item B<ProcessMatch> I<name> I<regex>
 
 Similar to the B<Process> option this allows to select more detailed


@@ -6587,6 +6657,79 @@ Default: B<1978>
 
 =back
 
 
 =back
 

+=head2 Plugin C<turbostat>
+
+The I<Turbostat plugin> reads CPU frequency and C-state residency on modern
+Intel processors by using the new Model Specific Registers.
+
+=over 4
+
+=item B<CoreCstates> I<Bitmask(Integer)>
+
+Bitmask of the list of core C states supported by the processor.
+This option should only be used if the automated detection fails.
+Default value extracted from the cpu model and family.
+
+Currently supported C-states (by this plugin): 3, 6, 7
+
+Example: (1<<3)+(1<<6)+(1<<7) = 392 for all states
+
+=item B<PackageCstates> I<Bitmask(Integer)>
+
+Bitmask of the list of pacages C states supported by the processor.
+This option should only be used if the automated detection fails.
+Default value extracted from the cpu model and family.
+
+Currently supported C-states (by this plugin): 2, 3, 6, 7, 8, 9, 10
+
+Example: (1<<2)+(1<<3)+(1<<6)+(1<<7) = 396 for states 2, 3, 6 and 7
+
+=item B<SystemManagementInterrupt> I<true>|I<false>
+
+Boolean enabling the collection of the I/O System-Management Interrupt
+counter'. This option should only be used if the automated detection
+fails or if you want to disable this feature.
+
+=item B<DigitalTemperatureSensor> I<true>|I<false>
+
+Boolean enabling the collection of the temperature of each core.
+This option should only be used if the automated detectionfails or 
+if you want to disable this feature.
+
+=item B<DigitalTemperatureSensor> I<true>|I<false>
+
+Boolean enabling the collection of the temperature of each package.
+This option should only be used if the automated detectionfails or 
+if you want to disable this feature.
+
+=item B<TCCActivationTemp> I<Temperature>
+
+Thermal Control Circuit Activation Temperature of the installed
+CPU. This temperature is used when collecting the temperature of
+cores or packages. This option should only be used if the automated
+detection fails. Default value extracted from B<MSR_IA32_TEMPERATURE_TARGET>
+
+=item B<RunningAveragePowerLimit> I<Bitmask(Integer)>
+
+Bitmask of the list of elements to be thermally monitored. This option
+should only be used if the automated detection fails or if you want to
+disable some collections. The different bits of this bitmask accepted
+by this plugin are:
+
+=over 4
+
+=item 0 ('1'): Package
+
+=item 1 ('2'): DRAM
+
+=item 2 ('4'): Cores
+
+=item 3 ('8'): Embedded graphic device
+
+=back
+
+=back
+

 =head2 Plugin C<unixsock>
 
 =over 4
 =head2 Plugin C<unixsock>
 
 =over 4


@@ -6627,20 +6770,20 @@ The following methods are used to find the machine's UUID, in order:
 
 =over 4
 
 
 =over 4
 

-=item
+=item *

 
 Check I</etc/uuid> (or I<UUIDFile>).
 
 
 Check I</etc/uuid> (or I<UUIDFile>).
 

-=item
+=item *

 
 Check for UUID from HAL (L<http://www.freedesktop.org/wiki/Software/hal>) if
 present.
 
 
 Check for UUID from HAL (L<http://www.freedesktop.org/wiki/Software/hal>) if
 present.
 

-=item
+=item *

 
 Check for UUID from C<dmidecode> / SMBIOS.
 
 
 Check for UUID from C<dmidecode> / SMBIOS.
 

-=item
+=item *

 
 Check for UUID from Xen hypervisor.
 
 
 Check for UUID from Xen hypervisor.
 


@@ -6882,6 +7025,10 @@ You can also specify combinations of these fields. For example B<name uuid>
 means to concatenate the guest name and UUID (with a literal colon character
 between, thus I<"foo:1234-1234-1234-1234">).
 
 means to concatenate the guest name and UUID (with a literal colon character
 between, thus I<"foo:1234-1234-1234-1234">).
 

+At the moment of writing (collectd-5.5), hostname string is limited to 62
+characters. In case when combination of fields exceeds 62 characters,
+hostname will be truncated without a warning.
+

 =item B<InterfaceFormat> B<name>|B<address>
 
 When the virt plugin logs interface data, it sets the name of the collected
 =item B<InterfaceFormat> B<name>|B<address>
 
 When the virt plugin logs interface data, it sets the name of the collected


@@ -6900,6 +7047,10 @@ by the hypervisor, which is equal to setting B<name>.
 
 B<uuid> means use the guest's UUID.
 
 
 B<uuid> means use the guest's UUID.
 

+You can also specify combinations of these fields. For example B<name uuid>
+means to concatenate the guest name and UUID (with a literal colon character
+between, thus I<"foo:1234-1234-1234-1234">).
+

 =back
 
 =head2 Plugin C<vmem>
 =back
 
 =head2 Plugin C<vmem>


@@ -7372,7 +7523,7 @@ Synopsis:
 
 Values are submitted to I<Sorted Sets>, using the metric name as the key, and
 the timestamp as the score. Retrieving a date range can then be done using the
 
 Values are submitted to I<Sorted Sets>, using the metric name as the key, and
 the timestamp as the score. Retrieving a date range can then be done using the

-C<ZRANGEBYSCORE> I<Redis> command. Additionnally, all the identifiers of these
+C<ZRANGEBYSCORE> I<Redis> command. Additionally, all the identifiers of these

 I<Sorted Sets> are kept in a I<Set> called C<collectd/values> and can be
 retrieved using the C<SMEMBERS> I<Redis> command. See
 L<http://redis.io/commands#sorted_set> and L<http://redis.io/commands#set> for
 I<Sorted Sets> are kept in a I<Set> called C<collectd/values> and can be
 retrieved using the C<SMEMBERS> I<Redis> command. See
 L<http://redis.io/commands#sorted_set> and L<http://redis.io/commands#set> for


@@ -7390,9 +7541,9 @@ options are available:
 =item B<Node> I<Nodename>
 
 The B<Node> block identifies a new I<Redis> node, that is a new I<Redis>
 =item B<Node> I<Nodename>
 
 The B<Node> block identifies a new I<Redis> node, that is a new I<Redis>

-instance running in an specified host and port. The name for node is a
+instance running on a specified host and port. The node name is a

 canonical identifier which is used as I<plugin instance>. It is limited to
 canonical identifier which is used as I<plugin instance>. It is limited to

-64E<nbsp>characters in length.
+51E<nbsp>characters in length.

 
 =item B<Host> I<Hostname>
 
 
 =item B<Host> I<Hostname>
 


@@ -7488,7 +7639,7 @@ C<ds_type:derive:rate>.
 
 =item B<AlwaysAppendDS> B<false>|B<true>
 
 
 =item B<AlwaysAppendDS> B<false>|B<true>
 

-If set the B<true>, append the name of the I<Data Source> (DS) to the
+If set to B<true>, append the name of the I<Data Source> (DS) to the

 "service", i.e. the field that, together with the "host" field, uniquely
 identifies a metric in I<Riemann>. If set to B<false> (the default), this is
 only done when there is more than one DS.
 "service", i.e. the field that, together with the "host" field, uniquely
 identifies a metric in I<Riemann>. If set to B<false> (the default), this is
 only done when there is more than one DS.