connection is interrupted for whatever reason it will try to re-connect. The
plugin will complaint loudly in case anything goes wrong.
-This plugin issues C<SHOW STATUS> and evaluates C<Bytes_{received,sent}>,
-C<Com_*> and C<Handler_*> which correspond to F<mysql_octets.rrd>,
-F<mysql_commands-*.rrd> and F<mysql_handler-*.rrd>. Also, the values of
-C<Qcache_*> are put in F<mysql_qcache.rrd> and values of C<Threads_*> are put
-in F<mysql_threads.rrd>. Please refer to the B<MySQL reference manual>,
-I<5.2.4. Server Status Variables> for an explanation of these values.
+This plugin issues the MySQL C<SHOW STATUS> command and collects information
+about MySQL network traffic, executed statements, requests, the query cache
+and threads by evaluating the C<Bytes_{received,sent}>, C<Com_*>,
+C<Handler_*>, C<Qcache_*> and C<Threads_*> return values. Please refer to the
+B<MySQL reference manual>, I<5.1.6. Server Status Variables> for an
+explanation of these values.
Use the following options to configure the plugin:
=item B<User> I<Username>
-Username to use when connecting to the database.
+Username to use when connecting to the database. The user does not have to be
+granted any privileges (which is synonym to granting the C<USAGE> privilege).
+Any existing MySQL user will do.
=item B<Password> I<Password>
or two, reading all values will take more than ten seconds (the default
interval). We will probably add some separate thread for reading the sensors
and some cache or something like that, but it's not done yet. We will try to
-maintain backwards compatibility in the future, but we can't probmise. So in
-short: If it works for you: Great! But kaap in mind that the config I<might>
+maintain backwards compatibility in the future, but we can't promise. So in
+short: If it works for you: Great! But keep in mind that the config I<might>
change, though this is unlikely. Oh, and if you want to help improving this
plugin, just send a short notice to the mailing list. ThanksE<nbsp>:)
+=head2 Plugin C<openvpn>
+
+The OpenVPN plugin reads a status file maintained by OpenVPN and gathers
+traffic statistics about connected clients.
+
+To set up OpenVPN to write to the status file periodically, use the
+B<--status> option of OpenVPN. Since OpenVPN can write two different formats,
+you need to set the required format, too. This is done by setting
+B<--status-version> to B<2>.
+
+So, in a nutshell you need:
+
+ openvpn $OTHER_OPTIONS \
+ --status "/var/run/openvpn-status" 10 \
+ --status-version 2
+
+Available options:
+
+=over 4
+
+=item B<StatusFile> I<File>
+
+Specifies the location of the status file.
+
+=back
+
=head2 Plugin C<oracle>
The "oracle" plugin uses the Oracle® Call Interface (OCI) to connect to an
(RSS), user- and system-time used, number of processes and number of threads,
and minor and major pagefaults.
+=item B<ProcessMatch> I<name> I<regex>
+
+Similar to the B<Process> option this allows to select more detailed
+statistics of processes matching the specified I<regex> (see L<regex(7)> for
+details). The statistics of all matching processes are summed up and
+dispatched to the daemon using the specified I<name> as an identifier. This
+allows to "group" several processes together. I<name> must not contain
+slashes.
+
=back
=head2 Plugin C<rrdcached>
<File "/var/log/exim4/mainlog">
Instance "exim"
<Match>
- Regex "S=([1-9][0-9]*)"
- DSType "CounterAdd"
- Type "ipt_bytes"
- Instance "total"
+ Regex "S=([1-9][0-9]*)"
+ DSType "CounterAdd"
+ Type "ipt_bytes"
+ Instance "total"
</Match>
<Match>
- Regex "\\<R=local_user\\>"
- DSType "CounterInc"
- Type "counter"
- Instance "local_user"
+ Regex "\\<R=local_user\\>"
+ DSType "CounterInc"
+ Type "counter"
+ Instance "local_user"
</Match>
</File>
</Plugin>
<Plugin "memory">
<Type "memory">
Instance "cached"
- WarningMin 100000000
+ WarningMin 100000000
</Type>
</Plugin>
</Host>
=back
+=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<iptables>,
+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:
+
+=over 4
+
+=item B<Match>
+
+A I<match> is a criteria to select specific values. Examples are, of course, the
+name of the value or it's current value.
+
+=item B<Target>
+
+A I<target> 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<write> and B<stop>, see below.
+
+Some targets, for example the built-in B<stop> target, signal that processing
+of a value should be stopped. In that case processing of the current chain will
+be aborted.
+
+=item B<Rule>
+
+The combination of any number of matches and at least one target is called a
+I<rule>. The target actions will be performed for all values for which B<all>
+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<Chain>
+
+A I<chain> 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.
+
+=back
+
+=head2 General structure
+
+The following shows the resulting structure:
+
+ +---------+
+ ! Chain !
+ +---------+
+ !
+ V
+ +---------+ +---------+ +---------+ +---------+
+ ! Rule !->! Match !->! Match !->! Target !
+ +---------+ +---------+ +---------+ +---------+
+ !
+ V
+ +---------+ +---------+ +---------+
+ ! Rule !->! Target !->! Target !
+ +---------+ +---------+ +---------+
+ !
+ V
+ :
+ :
+ !
+ V
+ +---------+ +---------+ +---------+
+ ! Rule !->! Match !->! Target !
+ +---------+ +---------+ +---------+
+ !
+ V
+ +---------+
+ ! Default !
+ ! Target !
+ +---------+
+
+=head2 Synopsis
+
+The configuration reflects this structure directly:
+
+ <Chain "main">
+ <Rule "ignore_mysql_show">
+ <Match "regex">
+ Plugin "^mysql$"
+ Type "^mysql_command$"
+ TypeInstance "^show_"
+ </Match>
+ <Target "stop">
+ </Target>
+ </Rule>
+ <Target "write">
+ Plugin "rrdtool"
+ </Target>
+ </Chain>
+
+The above configuration example will ignore all values where the plugin field
+is "mysql", the type is "mysql_command" and the type instance begins with
+"show_". All other values will be sent to the "rrdtool" write plugin via the
+default target of the chain.
+
+=head2 List of configuration options
+
+=over 4
+
+=item B<Chain> I<Name>
+
+Adds a new chain with a certain name. This name can be used to refer to a
+specific chain, for example to jump to it.
+
+Within the B<Chain> block, there can be B<Rule> blocks and B<Target> blocks.
+
+=item B<Rule> [I<Name>]
+
+Adds a new rule to the current chain. The name of the rule is optional and
+currently has no meaning for the daemon.
+
+Within the B<Rule> block, there may be any number of B<Match> blocks and there
+must be at least one B<Target> block.
+
+=item B<Match> I<Name>
+
+Adds a match to a B<Rule> block. The name specifies what kind of match should
+be performed. Available matches depend on the plugins that have been loaded.
+
+The arguments inside the B<Match> block are passed to the plugin implementing
+the match, so which arguments are valid here depends on the plugin being used.
+If you do not need any to pass any arguments to a match, you can use the
+shorter syntax:
+
+ Match "foobar"
+
+Which is equivalent to:
+
+ <Match "foobar">
+ </Match>
+
+=item B<Target> I<Name>
+
+Add a target to a rule or a default target to a chain. The name specifies what
+kind of target is to be added. Which targets are available depends on the
+plugins being loaded.
+
+The arguments inside the B<Target> block are passed to the plugin implementing
+the target, so which arguments are valid here depends on the plugin being used.
+If you do not need any to pass any arguments to a target, you can use the
+shorter syntax:
+
+ Target "stop"
+
+This is the same as writing:
+
+ <Target "stop">
+ </Target>
+
+=back
+
+=head2 Built-in targets
+
+The following targets are built into the core daemon and therefore need no
+plugins to be loaded:
+
+=over 4
+
+=item B<return>
+
+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<jump> target
+(see below). This is very similar to the B<RETURN> target of iptables, see
+L<iptables(8)>.
+
+This target does not have any options.
+
+Example:
+
+ Target "return"
+
+=item B<stop>
+
+Signals the "stop" condition, causing processing of the value to be aborted
+immediately. This is similar to the B<DROP> target of iptables, see
+L<iptables(8)>.
+
+This target does not have any options.
+
+Example:
+
+ Target "stop"
+
+=item B<write>
+
+Sends the value to write plugins.
+
+Available options:
+
+=over 4
+
+=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.
+
+=back
+
+If no plugin is explicitly specified, the values will be sent to all available
+write plugins.
+
+Example:
+
+ <Target "write">
+ Plugin "rrdtool"
+ </Target>
+
+=item B<jump>
+
+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<jump> target, i.E<nbsp>e. with the next target or the next rule.
+This is similar to the B<-j> command line option of iptables, see
+L<iptables(8)>.
+
+Available options:
+
+=over 4
+
+=item B<Chain> I<Name>
+
+Jumps to the chain I<Name>. This argument is required and may appear only once.
+
+=back
+
+Example:
+
+ <Target "jump">
+ Chain "foobar"
+ </Target>
+
+=back
+
+=head2 Available matches
+
+=over 4
+
+=item B<regex>
+
+Matches a value using regular expressions.
+
+Available options:
+
+=over 4
+
+=item B<Host> I<Regex>
+
+=item B<Plugin> I<Regex>
+
+=item B<PluginInstance> I<Regex>
+
+=item B<Type> I<Regex>
+
+=item B<TypeInstance> I<Regex>
+
+Match values where the given regular expressions match the various fields of
+the identifier of a value. If multiple regular expressions are given, B<all>
+regexen must match for a value to match.
+
+=back
+
+Example:
+
+ <Match "regex">
+ Host "customer[0-9]+"
+ Plugin "^foobar$"
+ </Match>
+
+=item B<value>
+
+Matches the actual value of data sources against given minimumE<nbsp>/ maximum
+values. If a data-set consists of more than one data-source, all data-sources
+must match the specified ranges for a positive match.
+
+Available options:
+
+=over 4
+
+=item B<Min> I<Value>
+
+Sets the smallest value which still results in a match. If unset, behaves like
+negative infinity.
+
+=item B<Max> I<Value>
+
+Sets the largest value which still results in a match. If unset, behaves like
+positive infinity.
+
+=item B<Invert> B<true>|B<false>
+
+Inverts the selection. If the B<Min> and B<Max> settings result in a match,
+no-match is returned and vice versa.
+
+=back
+
+Either B<Min> or B<Max>, but not both, may be unset.
+
+Example:
+
+ # Match all values smaller than or equal to 100.
+ <Match "value">
+ Max 100
+ </Match>
+
+=back
+
+=head2 Available targets
+
+=over 4
+
+=item B<notification>
+
+Creates and dispatches a notification.
+
+Available options:
+
+=over 4
+
+=item B<Message> I<String>
+
+This required option sets the message of the notification. The following
+placeholders will be replaced by an appropriate value:
+
+=over 4
+
+=item B<%{host}>
+
+=item B<%{plugin}>
+
+=item B<%{plugin_instance}>
+
+=item B<%{type}>
+
+=item B<%{type_instance}>
+
+These placeholders are replaced by the identifier field of the same name.
+
+=item B<%{ds:>I<name>B<}>
+
+These placeholders are replaced by a (hopefully) human readable representation
+of the current rate of this data source. If you changed the instance name
+(using the B<set> or B<replace> targets, see below), it may not be possible to
+convert counter values to rates.
+
+=back
+
+Please note that these placeholders are B<case sensitive>!
+
+=item B<Severity> B<"FATAL">|B<"WARNING">|B<"OKAY">
+
+Sets the severity of the message. If omitted, the severity B<"WARNING"> is
+used.
+
+=back
+
+Example:
+
+ <Target "notification">
+ Message "Oops, the %{type_instance} temperature is currently %{ds:value}!"
+ Severity "WARNING"
+ </Target>
+
+=item B<replace>
+
+Replaces parts of the identifier using regular expressions.
+
+Available options:
+
+=over 4
+
+=item B<Host> I<Regex> I<Replacement>
+
+=item B<Plugin> I<Regex> I<Replacement>
+
+=item B<PluginInstance> I<Regex> I<Replacement>
+
+=item B<TypeInstance> I<Regex> I<Replacement>
+
+Match the appropriate field with the given regular expression I<Regex>. If the
+regular expression matches, that part that matches is replaced with
+I<Replacement>. If multiple places of the input buffer match a given regular
+expression, only the first occurrence will be replaced.
+
+You can specify each option multiple times to use multiple regular expressions
+one after another.
+
+=back
+
+Example:
+
+ <Target "replace">
+ # Replace "example.net" with "example.com"
+ Host "\\<example.net\\>" "example.com"
+
+ # Strip "www." from hostnames
+ Host "\\<www\\." ""
+ </Target>
+
+=item B<set>
+
+Sets part of the identifier of a value to a given string.
+
+Available options:
+
+=over 4
+
+=item B<Host> I<String>
+
+=item B<Plugin> I<String>
+
+=item B<PluginInstance> I<String>
+
+=item B<TypeInstance> I<String>
+
+Set the appropriate field to the given string. The strings for plugin instance
+and type instance may be empty, the strings for host and plugin may not be
+empty. It's currently not possible to set the type of a value this way.
+
+=back
+
+Example:
+
+ <Target "set">
+ PluginInstance "coretemp"
+ TypeInstance "core3"
+ </Target>
+
+=back
+
+=head2 Backwards compatibility
+
+If you use collectd with an old configuration, i.E<nbsp>e. one without a
+B<Chain> block, it will behave as it used to. This is equivalent to the
+following configuration:
+
+ <Chain "main">
+ Target "write"
+ </Chain>
+
+If you specify a B<Chain> block anywhere, the B<write> target will not be added
+anywhere and you will have to make sure that it is called where appropriate. We
+suggest to add the above snippet as default target to your main chain.
+
+TODO: Notifications will be implemented using chains, too. Describe that here!
+
+=head2 Examples
+
+Ignore all values, where the hostname does not contain a dot, i.E<nbsp>e. can't
+be an FQDN.
+
+ <Chain "main">
+ <Rule "no_fqdn">
+ <Match "regex">
+ Host "^[^\.]*$"
+ </Match>
+ Target "stop"
+ </Rule>
+ Target "write"
+ </Chain>
+
=head1 SEE ALSO
L<collectd(1)>,
L<collectd-unixsock(5)>,
L<types.db(5)>,
L<hddtemp(8)>,
+L<iptables(8)>,
L<kstat(3KSTAT)>,
L<mbmon(1)>,
L<pcre(3)>,
L<psql(1)>,
+L<regex(7)>,
L<rrdtool(1)>,
L<sensors(1)>
projects / collectd.git / blobdiff