line which sets this option, though, so that default installations will have
this setting enabled.
+=item B<PreCacheChain> I<ChainName>
+
+=item B<PostCacheChain> I<ChainName>
+
+Configure the name of the "pre-cache chain" and the "post-cache chain". Please
+see L<FILTER CONFIGURATION> below on information on chains and how these
+setting change the daemon's behavior.
+
=back
=head1 PLUGIN OPTIONS
inet localhost port 8053;
};
+The configuration follows the grouping that can be seen when looking at the
+data with an XSLT compatible viewer, such as a modern web browser. It's
+probably a good idea to make yourself familiar with the provided values, so you
+can understand what the collected statistics actually mean.
+
+Synopsis:
+
+ <Plugin "bind">
+ URL "http://localhost:8053/"
+ OpCodes true
+ QTypes true
+
+ ServerStats true
+ ZoneMaintStats true
+ ResolverStats false
+ MemoryStats true
+
+ <View "_default">
+ QTypes true
+ ResolverStats true
+ CacheRRSets true
+
+ Zone "127.in-addr.arpa/IN"
+ </View>
+ </Plugin>
+
The bind plugin accepts the following configuration options:
=over 4
URL from which to retrieve the XML data. If not specified,
C<http://localhost:8053/> will be used.
-=item B<DNSSEC> I<true>|I<false>
-
=item B<OpCodes> I<true>|I<false>
-=item B<Queries> I<true>|I<false>
+When enabled, statistics about the I<"OpCodes">, for example the number of
+C<QUERY> packets, are collected.
+
+Default: Enabled.
+
+=item B<QTypes> I<true>|I<false>
+
+When enabled, the number of I<incoming> queries by query types (for example
+C<A>, C<MX>, C<AAAA>) is collected.
-=item B<QueryResults> I<true>|I<false>
+Default: Enabled.
-=item B<RCode> I<true>|I<false>
+=item B<ServerStats> I<true>|I<false>
-=item B<Rejects> I<true>|I<false>
+Collect global server statistics, such as requests received over IPv4 and IPv6,
+successful queries, and failed updates.
-=item B<Requests> I<true>|I<false>
+Default: Enabled.
-=item B<Resolver> I<true>|I<false>
+=item B<ZoneMaintStats> I<true>|I<false>
+
+Collect zone maintenance statistics, mostly information about notifications
+(zone updates) and zone transfers.
+
+Default: Enabled.
+
+=item B<ResolverStats> I<true>|I<false>
+
+Collect resolver statistics, i.E<nbsp>e. statistics about outgoing requests
+(e.E<nbsp>g. queries over IPv4, lame servers). Since the global resolver
+counters apparently were removed in BIND 9.5.1 and 9.6.0, this is disabled by
+default. Use the B<ResolverStats> option within a B<View "_default"> block
+instead for the same functionality.
+
+Default: Disabled.
+
+=item B<MemoryStats>
+
+Collect global memory statistics.
+
+Default: Enabled.
+
+=item B<View> I<Name>
+
+Collect statistics about a specific I<"view">. BIND can behave different,
+mostly depending on the source IP-address of the request. These different
+configurations are called "views". If you don't use this feature, you most
+likely are only interested in the C<_default> view.
+
+Within a E<lt>B<View>E<nbsp>I<name>E<gt> block, you can specify which
+information you want to collect about a view. If no B<View> block is
+configured, no detailed view statistics will be collected.
+
+=over 4
-=item B<Responses> I<true>|I<false>
+=item B<QTypes> I<true>|I<false>
-=item B<RRQueriesIn> I<true>|I<false>
+If enabled, the number of I<outgoing> queries by query type (e.E<nbsp>g. C<A>,
+C<MX>) is collected.
-=item B<Updates> I<true>|I<false>
+Default: Enabled.
-=item B<ZoneMaintenance> I<true>|I<false>
+=item B<ResolverStats> I<true>|I<false>
-=item B<ZoneStats> I<true>|I<false>
+Collect resolver statistics, i.E<nbsp>e. statistics about outgoing requests
+(e.E<nbsp>g. queries over IPv4, lame servers).
-Enables or disables collection of specific counters.
-TODO: Options must be described in detail!
+Default: Enabled.
+
+=item B<CacheRRSets> I<true>|I<false>
+
+If enabled, the number of entries (I<"RR sets">) in the view's cache by query
+type is collected. Negative entries (queries which resulted in an error, for
+example names that do not exist) are reported with a leading exclamation mark,
+e.E<nbsp>g. "!A".
+
+Default: Enabled.
+
+=item B<Zone> I<Name>
+
+When given, collect detailed information about the given zone in the view. The
+information collected if very similar to the global B<ServerStats> information
+(see above).
+
+You can repeat this option to collect detailed information about multiple
+zones.
+
+By default no detailed zone information is collected.
+
+=back
=back
=back
+=head2 Plugin C<curl>
+
+The curl plugin uses the B<libcurl> (L<http://curl.haxx.se/>) to read web pages
+and the match infrastructure (the same code used by the tail plugin) to use
+regular expressions with the received data.
+
+The following example will read the current value of AMD stock from google's
+finance page and dispatch the value to collectd.
+
+ <Plugin curl>
+ <Page "stock_quotes">
+ URL "http://finance.google.com/finance?q=NYSE%3AAMD"
+ User "foo"
+ Password "bar"
+ <Match>
+ Regex "<span +class=\"pr\"[^>]*> *([0-9]*\\.[0-9]+) *</span>"
+ DSType "GaugeAverage"
+ # Note: `stock_value' is not a standard type.
+ Type "stock_value"
+ Instance "AMD"
+ </Match>
+ </Page>
+ </Plugin>
+
+In the B<Plugin> block, there may be one or more B<Page> blocks, each defining
+a web page and one or more "matches" to be performed on the returned data. The
+string argument to the B<Page> block is used as plugin instance.
+
+The following options are valid within B<Page> blocks:
+
+=over 4
+
+=item B<URL> I<URL>
+
+URL of the web site to retrieve. Since a regular expression will be used to
+extract information from this data, non-binary data is a big plus here ;)
+
+=item B<User> I<Name>
+
+Username to use if authorization is required to read the page.
+
+=item B<Password> I<Password>
+
+Password to use if authorization is required to read the page.
+
+=item B<VerifyPeer> B<true>|B<false>
+
+Enable or disable peer SSL certificate verification. See
+L<http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by default.
+
+=item B<VerifyHost> B<true>|B<false>
+
+Enable or disable peer host name verification. If enabled, the plugin checks if
+the C<Common Name> or a C<Subject Alternate Name> field of the SSL certificate
+matches the host name provided by the B<URL> option. If this identity check
+fails, the connection is aborted. Obviously, only works when connecting to a
+SSL enabled server. Enabled by default.
+
+=item B<CACert> I<file>
+
+File that holds one or more SSL certificates. If you want to use HTTPS you will
+possibly need this option. What CA certificates come bundled with C<libcurl>
+and are checked by default depends on the distribution you use.
+
+=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.
+
+=back
+
=head2 Plugin C<dbi>
This plugin uses the B<dbi> library (L<http://libdbi.sourceforge.net/>) to
<Plugin dbi>
<Query "out_of_stock">
Statement "SELECT category, COUNT(*) AS value FROM products WHERE in_stock = 0 GROUP BY category"
+ # Use with MySQL 5.0.0 or later
+ MinVersion 50000
<Result>
Type "gauge"
+ InstancePrefix "out_of_stock"
InstancesFrom "category"
ValuesFrom "value"
</Result>
Statement "select station, temperature, humidity from environment"
<Result>
Type "temperature"
+ # InstancePrefix "foo"
InstancesFrom "station"
ValuesFrom "temperature"
</Result>
use a more strict database server, you may have to select from a dummy table or
something.)
+=item B<MinVersion> I<Version>
+
+=item B<MaxVersion> I<Value>
+
+Only use this query for the specified database version. You can use these
+options to provide multiple queries with the same name but with a slightly
+different syntax. The plugin will use only those queries, where the specified
+minimum and maximum versions fit the version of the database in use.
+
+The database version is determined by C<dbi_conn_get_engine_version>, see the
+L<libdbi documentation|http://libdbi.sourceforge.net/docs/programmers-guide/reference-conn.html#DBI-CONN-GET-ENGINE-VERSION>
+for details. Basically, each part of the version is assumed to be in the range
+from B<00> to B<99> and all dots are removed. So version "4.1.2" becomes
+"40102", version "5.0.42" becomes "50042".
+
+B<Warning:> The plugin will use B<all> matching queries, so if you specify
+multiple queries with the same name and B<overlapping> ranges, weird stuff will
+happen. Don't to it! A valid example would be something along these lines:
+
+ MinVersion 40000
+ MaxVersion 49999
+ ...
+ MinVersion 50000
+ MaxVersion 50099
+ ...
+ MinVersion 50100
+ # No maximum
+
+In the above example, there are three ranges that don't overlap. The last one
+goes from version "5.1.0" to infinity, meaning "all later versions". Versions
+before "4.0.0" are not specified.
+
=item B<Type> I<Type>
The B<type> that's used for each line returned. See L<types.db(5)> for more
There must be exactly one B<Type> option inside each B<Result> block.
+=item B<InstancePrefix> I<prefix>
+
+Prepends I<prefix> followed by a dash I<("-")> to the type instance. See
+B<InstancesFrom> on how the rest of the type instance is built.
+
=item B<InstancesFrom> I<column0> [I<column1> ...]
Specifies the columns whose values will be used to create the "TypeInstance"
=back
+B<Note>: There is no need to notify the daemon after moving or removing the
+log file (e.E<nbsp>g. when rotating the logs). The plugin reopens the file
+for each line it writes.
+
=head2 Plugin C<mbmon>
The C<mbmon plugin> uses mbmon to retrieve temperature, voltage, etc.
Statement "SELECT category, COUNT(*) AS value FROM products WHERE in_stock = 0 GROUP BY category"
<Result>
Type "gauge"
+ # InstancePrefix "foo"
InstancesFrom "category"
ValuesFrom "value"
</Result>
The B<VServer> homepage can be found at L<http://linux-vserver.org/>.
+B<Note>: The traffic collected by this plugin accounts for the amount of
+traffic passing a socket which might be a lot less than the actual on-wire
+traffic (e.E<nbsp>g. due to headers and retransmission). If you want to
+collect on-wire traffic you could, for example, use the logging facilities of
+iptables to feed data for the guest IPs into the iptables plugin.
+
=head1 THRESHOLD CONFIGURATION
Starting with version C<4.3.0> collectd has support for B<monitoring>. By that
The configuration reflects this structure directly:
- <Chain "main">
+ PostCacheChain "PostCache"
+ <Chain "PostCache">
<Rule "ignore_mysql_show">
<Match "regex">
Plugin "^mysql$"
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.
+"show_". All other values will be sent to the C<rrdtool> write plugin via the
+default target of the chain. Since this chain is run after the value has been
+added to the cache, the MySQL C<show_*> command statistics will be available
+via the C<unixsock> plugin.
=head2 List of configuration options
=over 4
+=item B<PreCacheChain> I<ChainName>
+
+=item B<PostCacheChain> I<ChainName>
+
+Configure the name of the "pre-cache chain" and the "post-cache chain". The
+argument is the name of a I<chain> that should be executed before and/or after
+the values have been added to the cache.
+
+To understand the implications, it's important you know what is going on inside
+I<collectd>. The following diagram shows how values are passed from the
+read-plugins to the write-plugins:
+
+ +---------------+
+ ! Read-Plugin !
+ +-------+-------+
+ !
+ + - - - - V - - - - +
+ : +---------------+ :
+ : ! Pre-Cache ! :
+ : ! Chain ! :
+ : +-------+-------+ :
+ : ! :
+ : V :
+ : +-------+-------+ : +---------------+
+ : ! Cache !--->! Value Cache !
+ : ! insert ! : +---+---+-------+
+ : +-------+-------+ : ! !
+ : ! ,------------' !
+ : V V : V
+ : +-------+---+---+ : +-------+-------+
+ : ! Post-Cache +--->! Write-Plugins !
+ : ! Chain ! : +---------------+
+ : +---------------+ :
+ : :
+ : dispatch values :
+ + - - - - - - - - - +
+
+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
+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<unixsock> 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<value> match (see below). If you use the rate stored in
+the cache B<before> the new value is added, you will use the old, B<previous>
+rate. Write plugins may use this rate, too, see the C<csv> plugin, for example.
+The C<unixsock> plugin uses these rates too, to implement the C<GETVAL>
+command.
+
+Last but not last, the B<stop> target makes a difference: If the pre-cache
+chain returns the stop condition, the value will not be added to the cache and
+the post-cache chain will not be run.
+
=item B<Chain> I<Name>
Adds a new chain with a certain name. This name can be used to refer to a
Plugin "^foobar$"
</Match>
+=item B<timediff>
+
+Matches values that have a time which differs from the time on the server.
+
+This match is mainly intended for servers that receive values over the
+C<network> plugin and write them to disk using the C<rrdtool> plugin. RRDtool
+is very sensitive to the timestamp used when updating the RRD files. In
+particular, the time must be ever increasing. If a misbehaving client sends one
+packet with a timestamp far in the future, all further packets with a correct
+time will be ignored because of that one packet. What's worse, such corrupted
+RRD files are hard to fix.
+
+This match lets one match all values B<outside> a specified time range
+(relative to the server's time), so you can use the B<stop> target (see below)
+to ignore the value, for example.
+
+Available options:
+
+=over 4
+
+=item B<Future> I<Seconds>
+
+Matches all values that are I<ahead> of the server's time by I<Seconds> or more
+seconds. Set to zero for no limit. Either B<Future> or B<Past> must be
+non-zero.
+
+=item B<Past> I<Seconds>
+
+Matches all values that are I<behind> of the server's time by I<Seconds> or
+more seconds. Set to zero for no limit. Either B<Future> or B<Past> must be
+non-zero.
+
+=back
+
+Example:
+
+ <Match "timediff">
+ Future 300
+ Past 3600
+ </Match>
+
+This example matches all values that are five minutes or more ahead of the
+server or one hour (or more) lagging behind.
+
=item B<value>
Matches the actual value of data sources against given minimumE<nbsp>/ maximum
B<Chain> block, it will behave as it used to. This is equivalent to the
following configuration:
- <Chain "main">
+ <Chain "PostCache">
Target "write"
</Chain>
-If you specify a B<Chain> block anywhere, the B<write> target will not be added
+If you specify a B<PostCacheChain>, 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!
+suggest to add the above snippet as default target to your "PostCache" chain.
=head2 Examples
Ignore all values, where the hostname does not contain a dot, i.E<nbsp>e. can't
be an FQDN.
- <Chain "main">
+ <Chain "PreCache">
<Rule "no_fqdn">
<Match "regex">
Host "^[^\.]*$"
projects / collectd.git / blobdiff