X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=src%2Fcollectd.conf.pod;h=48b75bc82f9cfa6a32e263c950dc108bbd67c915;hb=04b395325b152a5ddf424d1a750f455a2f8229fb;hp=dd455889c4540b087071342daef6e76164377f9b;hpb=6597f3a6584704f92f824f3cf7bac3369102e8a0;p=collectd.git
diff --git a/src/collectd.conf.pod b/src/collectd.conf.pod
index dd455889..48b75bc8 100644
--- a/src/collectd.conf.pod
+++ b/src/collectd.conf.pod
@@ -529,7 +529,7 @@ than those of other plugins. It usually looks something like this:
MinVersion 50000
Type "gauge"
- InstancePrefix "out_of_stock"
+ InstancePrefix "out_of_stock"
InstancesFrom "category"
ValuesFrom "value"
@@ -653,20 +653,24 @@ There must be exactly one B option inside each B block.
=item B I
-Prepends I followed by a dash I<("-")> to the type instance. See
-B on how the rest of the type instance is built.
+Prepends I to the type instance. If B (see below) is not
+given, the string is simply copied. If B is given, I and
+all strings returned in the appropriate columns are concatenated together,
+separated by dashes I<("-")>.
=item B I [I ...]
-Specifies the columns whose values will be used to create the "TypeInstance"
-for each row. You need to specify at least one column for each query. If you
-specify more than one column, the value of all columns will be join together
-with the hyphen as separation character.
+Specifies the columns whose values will be used to create the "type-instance"
+for each row. If you specify more than one column, the value of all columns
+will be joined together with dashes I<("-")> as separation characters.
The plugin itself does not check whether or not all built instances are
-different. It's your responsibility to assure that each is unique.
+different. It's your responsibility to assure that each is unique. This is
+especially true, if you do not specify B: B have to make
+sure that only one row is returned in this case.
-There must be at least one B option inside each B block.
+If neither B nor B is given, the type-instance
+will be empty.
=item B I [I ...]
@@ -955,97 +959,6 @@ Controls whether or not to recurse into subdirectories. Enabled by default.
=back
-=head2 Plugin C
-
-This plugin allows you to filter and rewrite value lists based on
-Perl-compatible regular expressions whose syntax and semantics are as close as
-possible to those of the Perl 5 language. See L for details.
-
-
-
- Host "^mail\d+$"
- Plugin "^tcpconns$"
- TypeInstance "^SYN_"
-
- Action NoWrite
-
-
-
- Plugin "^sensors$"
- PluginInstance "^Some Weird Sensor Chip Name Prefix"
-
- SubstitutePluginInstance "foo"
-
-
-
-The configuration consists of one or more C blocks, each of which
-specifies a regular expression identifying a set of value lists and how to
-handle successful matches. A value list keeps the values of a single data-set
-and is identified by the tuple (host, plugin, plugin instance, type, type
-instance). The plugin and type instances are optional components. If they are
-missing they are treated as empty strings. Within those blocks, the following
-options are recognized:
-
-=over 4
-
-=item B I
-
-=item B I
-
-=item B I
-
-=item B I
-
-=item B I
-
-Specifies the regular expression for each component of the identifier. If any
-of these options is missing it is interpreted as a pattern which matches any
-string. All five components of a value list have to match the appropriate
-regular expression to trigger the specified action.
-
-=item B I|I|I
-
-Specify how to handle successful matches:
-
-=over 4
-
-=item B
-
-Do not send the value list to any output (a.k.a. write) plugins.
-
-=item B
-
-Skip threshold checking for this value list.
-
-=item B
-
-Completely ignore this value list.
-
-=back
-
-Two or more actions may be combined by specifying multiple B options.
-
-=item B I
-
-=item B I
-
-=item B I
-
-=item B I
-
-=item B I
-
-Upon a successful match, the matching substring will be replaced by the
-specified I text. These options require that an appropriate regex
-has been specified before, e.Eg. B requires that the
-B option has been specified before.
-
-B: It is not recommended to modify the type unless you really know what
-you are doing. The type is used to identify the data-set definition of the
-dispatched values.
-
-=back
-
=head2 Plugin C
To get values from B collectd connects to B (127.0.0.1),
@@ -1170,6 +1083,65 @@ and all other interrupts are collected.
=back
+=head2 Plugin C
+
+Synopsis:
+
+
+ JVMArg "-verbose:jni"
+ JVMArg "-Djava.class.path=/opt/collectd/lib/collectd/bindings/java"
+ LoadPlugin "org.collectd.java.Foobar"
+
+ # To be parsed by the plugin
+
+
+
+Available config options:
+
+=over 4
+
+=item B I
+
+Argument that is to be passed to the I (JVM). This works
+exactly the way the arguments to the I binary on the command line work.
+Execute C--help> for details.
+
+=item B I
+
+Instantiates a new I object. The following methods of this class are
+used when available:
+
+=over 4
+
+=item *
+
+public int B (org.collectd.api.OConfigItem ci)
+
+=item *
+
+public int B ()
+
+=item *
+
+public int B ()
+
+=item *
+
+public int B (org.collectd.protocol.ValueList vl)
+
+=item *
+
+public int B ()
+
+=back
+
+=item B I
+
+The entrie block is passed to the Java plugin as an
+I object.
+
+=back
+
=head2 Plugin C
This plugin allows CPU, disk and network load to be collected for virtualized
@@ -2445,7 +2417,7 @@ reduces IO-operations and thus lessens the load produced by updating the files.
The trade off is that the graphs kind of "drag behind" and that more memory is
used.
-=item B B
+=item B I
When collecting many statistics with collectd and the C plugin, you
will run serious performance problems. The B setting and the
@@ -2523,9 +2495,109 @@ debugging support.
=back
+=head2 Plugin C
+
+The C provides generic means to parse tabular data and dispatch
+user specified values. Values are selected based on column numbers. For
+example, this plugin may be used to get values from the Linux L
+filesystem or CSV (comma separated values) files.
+
+
+
+ Instance "slabinfo"
+ Separator " "
+
+ Type gauge
+ InstancePrefix "active_objs"
+ InstancesFrom 0
+ ValuesFrom 1
+
+
+ Type gauge
+ InstancePrefix "objperslab"
+ InstancesFrom 0
+ ValuesFrom 4
+
+
+
+
+The configuration consists of one or more B blocks, each of which
+configures one file to parse. Within each B block, there are one or
+more B blocks, which configure which data to select and how to
+interpret it.
+
+The following options are available inside a B block:
+
+=over 4
+
+=item B I
+
+If specified, I is used as the plugin instance. So, in the above
+example, the plugin name C would be used. If omitted, the
+filename of the table is used instead, with all special characters replaced
+with an underscore (C<_>).
+
+=item B I
+
+Any character of I is interpreted as a delimiter between the different
+columns of the table. A sequence of two or more contiguous delimiters in the
+table is considered to be a single delimiter, i.Ee. there cannot be any
+empty columns. The plugin uses the L function to parse the lines
+of a table - see its documentation for more details. This option is mandatory.
+
+A horizontal tab, newline and carriage return may be specified by C<\\t>,
+C<\\n> and C<\\r> respectively. Please note that the double backslashes are
+required because of collectd's config parsing.
+
+=back
+
+The following options are available inside a B block:
+
+=over 4
+
+=item B I
+
+Sets the type used to dispatch the values to the daemon. Detailed information
+about types and their configuration can be found in L. This
+option is mandatory.
+
+=item B I
+
+If specified, prepend I to the type instance. If omitted, only the
+B option is considered for the type instance.
+
+=item B I [I ...]
+
+If specified, the content of the given columns (identified by the column
+number starting at zero) will be used to create the type instance for each
+row. Multiple values (and the instance prefix) will be joined together with
+dashes (I<->) as separation character. If omitted, only the B
+option is considered for the type instance.
+
+The plugin itself does not check whether or not all built instances are
+different. Itâs your responsibility to assure that each is unique. This is
+especially true, if you do not specify B: B have to make
+sure that the table only contains one row.
+
+If neither B nor B is given, the type instance
+will be empty.
+
+=item B I [I ...]
+
+Specifies the columns (identified by the column numbers starting at zero)
+whose content is used as the actual data for the data sets that are dispatched
+to the daemon. How many such columns you need is determined by the B
+setting above. If you specify too many or not enough columns, the plugin will
+complain about that and no data will be submitted to the daemon. The plugin
+uses L and L to parse counter and gauge values
+respectively, so anything supported by those functions is supported by the
+plugin as well. This option is mandatory.
+
+=back
+
=head2 Plugin C
-The C plugins follows logfiles, just like L does, parses
+The C follows logfiles, just like L does, parses
each line and dispatches found values. What is matched can be configured by the
user using (extended) regular expressions, as described in L.
@@ -2951,16 +3023,16 @@ only one such notification is generated until the value appears again.
=head1 FILTER CONFIGURATION
-TODO: Update this entire section once development is done.
-
Starting with collectd 4.6 there is a powerful filtering infrastructure
-implemented in the daemon. The concept has mostly been copied from I,
-the packet filter infrastructure for Linux. We'll use a similar terminology, so
-that users that are familiar with iptables feel right at home.
+implemented in the daemon. The concept has mostly been copied from
+I, the packet filter infrastructure for Linux. We'll use a similar
+terminology, so that users that are familiar with iptables feel right at home.
=head2 Terminology
-The most important terms are:
+The following are the terms used in the remainder of the filter configuration
+documentation. For an ASCII-art schema of the mechanism, see
+L<"General structure"> below.
=over 4
@@ -2969,15 +3041,18 @@ The most important terms are:
A I is a criteria to select specific values. Examples are, of course, the
name of the value or it's current value.
+Matches are implemented in plugins which you have to load prior to using the
+match. The name of such plugins starts with the "match_" prefix.
+
=item B
A I is some action that is to be performed with data. Such actions
could, for example, be to change part of the value's identifier or to ignore
-the value completely. Built-in functions are B and B, see below.
+the value completely.
-Some targets, for example the built-in B target, signal that processing
-of a value should be stopped. In that case processing of the current chain will
-be aborted.
+Some of these targets are built into the daemon, see L<"Built-in targets">
+below. Other targets are implemented in plugins which you have to load prior to
+using the target. The name of such plugins starts with the "target_" prefix.
=item B
@@ -2986,18 +3061,14 @@ I. The target actions will be performed for all values for which B
matches apply. If the rule does not have any matches associated with it, the
target action will be performed for all values.
-If any target returns the stop condition, the processing will stop right away.
-This means that any targets following the current one will not be called after
-the stop condition has been returned.
-
=item B
A I is a list of rules and possibly default targets. The rules are tried
in order and if one matches, the associated target will be called. If a value
is handled by a rule, it depends on the target whether or not any subsequent
-rules are considered or if traversal of the chain is aborted. After all rules
-have been checked and no target returned the stop condition, the default
-targets will be executed.
+rules are considered or if traversal of the chain is aborted, see
+L<"Flow control"> below. After all rules have been checked, the default targets
+will be executed.
=back
@@ -3034,6 +3105,40 @@ The following shows the resulting structure:
! Target !
+---------+
+=head2 Flow control
+
+There are four ways to control which way a value takes through the filter
+mechanism:
+
+=over 4
+
+=item B
+
+The built-in B target can be used to "call" another chain, i.Ee.
+process the value with another chain. When the called chain finishes, usually
+the next target or rule after the jump is executed.
+
+=item B
+
+The stop condition, signaled for example by the built-in target B, causes
+all processing of the value to be stopped immediately.
+
+=item B
+
+Causes processing in the current chain to be aborted, but processing of the
+value generally will continue. This means that if the chain was called via
+B, the next target or rule after the jump will be executed. If the chain
+was not called by another chain, control will be returned to the daemon and it
+may pass the value to another chain.
+
+=item B
+
+Most targets will signal the B condition, meaning that processing
+should continue normally. There is no special built-in target for this
+condition.
+
+=back
+
=head2 Synopsis
The configuration reflects this structure directly:
@@ -3102,7 +3207,7 @@ read-plugins to the write-plugins:
: dispatch values :
+ - - - - - - - - - +
-After the values are passed from the read-plugins to the dispatch functions,
+After the values are passed from the "read" plugins to the dispatch functions,
the pre-cache chain is run first. The values are added to the internal cache
afterwards. The post-cache chain is run after the values have been added to the
cache. So why is it such a huge deal if chains are run before or after the
@@ -3110,10 +3215,10 @@ values have been added to this cache?
Targets that change the identifier of a value list should be executed before
the values are added to the cache, so that the name in the cache matches the
-name that is used in the write-plugins. The C plugin, too, uses this
-cache to receive a list of all available values. If you change the identifier
-after the value list has been added to the cache, this may easily lead to
-confusion, but it's not forbidden of course.
+name that is used in the "write" plugins. The C plugin, too, uses
+this cache to receive a list of all available values. If you change the
+identifier after the value list has been added to the cache, this may easily
+lead to confusion, but it's not forbidden of course.
The cache is also used to convert counter values to rates. These rates are, for
example, used by the C match (see below). If you use the rate stored in
@@ -3187,11 +3292,11 @@ plugins to be loaded:
=item B
-Signals the "return" condition. This causes the current chain to stop
-processing the value and returns control to the calling chain. The calling
-chain will continue processing targets and rules just after the B target
-(see below). This is very similar to the B target of iptables, see
-L.
+Signals the "return" condition, see the L<"Flow control"> section above. This
+causes the current chain to stop processing the value and returns control to
+the calling chain. The calling chain will continue processing targets and rules
+just after the B target (see below). This is very similar to the
+B target of iptables, see L.
This target does not have any options.
@@ -3201,9 +3306,9 @@ Example:
=item B
-Signals the "stop" condition, causing processing of the value to be aborted
-immediately. This is similar to the B target of iptables, see
-L.
+Signals the "stop" condition, see the L<"Flow control"> section above. This
+causes processing of the value to be aborted immediately. This is similar to
+the B target of iptables, see L.
This target does not have any options.
@@ -3213,7 +3318,7 @@ Example:
=item B
-Sends the value to write plugins.
+Sends the value to "write" plugins.
Available options:
@@ -3237,11 +3342,11 @@ Example:
=item B
-Starts processing the rules of another chain. If the end of that chain is
-reached, or a stop condition is encountered, processing will continue right
-after the B target, i.Ee. with the next target or the next rule.
-This is similar to the B<-j> command line option of iptables, see
-L.
+Starts processing the rules of another chain, see L<"Flow control"> above. If
+the end of that chain is reached, or a stop condition is encountered,
+processing will continue right after the B target, i.Ee. with the
+next target or the next rule. This is similar to the B<-j> command line option
+of iptables, see L.
Available options:
@@ -3572,7 +3677,6 @@ L,
L,
L,
L,
-L,
L,
L,
L,