=back
+=head2 Plugin C<bind>
+
+Starting with BIND 9.5.0, the most widely used DNS server software provides
+extensive statistics about queries, responses and lots of other information.
+The bind plugin retrieves this information that's encoded in XML and provided
+via HTTP and submits the values to collectd.
+
+To use this plugin, you first need to tell BIND to make this information
+available. This is done with the C<statistics-channels> configuration option:
+
+ statistics-channels {
+ inet localhost port 8053;
+ };
+
+The bind plugin accepts the following configuration options:
+
+=over 4
+
+=item B<URL> I<URL>
+
+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>
+
+=item B<QueryResults> I<true>|I<false>
+
+=item B<RCode> I<true>|I<false>
+
+=item B<Rejects> I<true>|I<false>
+
+=item B<Requests> I<true>|I<false>
+
+=item B<Resolver> I<true>|I<false>
+
+=item B<Responses> I<true>|I<false>
+
+=item B<RRQueriesIn> I<true>|I<false>
+
+=item B<Updates> I<true>|I<false>
+
+=item B<ZoneMaintenance> I<true>|I<false>
+
+=item B<ZoneStats> I<true>|I<false>
+
+Enables or disables collection of specific counters.
+TODO: Options must be described in detail!
+
+=back
+
=head2 Plugin C<cpufreq>
This plugin doesn't have any options. It reads
Set the directory to store CSV-files under. Per default CSV-files are generated
beneath the daemon's working directory, i.E<nbsp>e. the B<BaseDir>.
+The special strings B<stdout> and B<stderr> can be used to write to the standard
+output and standard error channels, respectively. This, of course, only makes
+much sense when collectd is running in foreground- or non-daemon-mode.
=item B<StoreRates> B<true|false>
=head2 Plugin C<dbi>
-This plugin uses the "B<dbi>" library (L<http://libdbi.sourceforge.net/>) to
-connect to various databases, execute SQL statements and read back the results.
-You can configure how each column is to be interpreted and the plugin will
-generate one data set from each row returned according to these rules.
+This plugin uses the B<dbi> library (L<http://libdbi.sourceforge.net/>) to
+connect to various databases, execute I<SQL> statements and read back the
+results. I<dbi> is an acronym for "database interface" in case you were
+wondering about the name. You can configure how each column is to be
+interpreted and the plugin will generate one or more data sets from each row
+returned according to these rules.
Because the plugin is very generic, the configuration is a little more complex
than those of other plugins. It usually looks something like this:
<Plugin dbi>
<Query "out_of_stock">
Statement "SELECT category, COUNT(*) AS value FROM products WHERE in_stock = 0 GROUP BY category"
- Type "gauge"
- InstancesFrom "category"
- ValuesFrom "value"
+ <Result>
+ Type "gauge"
+ InstancesFrom "category"
+ ValuesFrom "value"
+ </Result>
</Query>
<Database "product_information">
Driver "mysql"
</Database>
</Plugin>
-The configuration above defines one query and one database. The query is then
-linked to the database with the B<Query> option I<within> the
+The configuration above defines one query with one result and one database. The
+query is then linked to the database with the B<Query> option I<within> the
B<E<lt>DatabaseE<gt>> block. You can have any number of queries and databases
and you can also use the B<Include> statement to split up the configuration
file in multiple, smaller files. However, the B<E<lt>QueryE<gt>> block I<must>
=head3 B<Query> blocks
-Query blocks define SQL statements and how the returned data should be
+Query blocks define I<SQL> statements and how the returned data should be
interpreted. They are identified by the name that is given in the opening line
of the block. Thus the name needs to be unique. Other than that, the name is
-not used in collectd.
+not used in collectd.
+
+In each B<Query> block, there is one or more B<Result> blocks. B<Result> blocks
+define which column holds which value or instance information. You can use
+multiple B<Result> blocks to create multiple values from one returned row. This
+is especially useful, when queries take a long time and sending almost the same
+query again and again is not desirable.
+
+Example:
+
+ <Query "environment">
+ Statement "select station, temperature, humidity from environment"
+ <Result>
+ Type "temperature"
+ InstancesFrom "station"
+ ValuesFrom "temperature"
+ </Result>
+ <Result>
+ Type "humidity"
+ InstancesFrom "station"
+ ValuesFrom "humidity"
+ </Result>
+ </Query>
+
+The following options are accepted:
=over 4
specify "if_octets", you will need two counter columns. See the B<ValuesFrom>
setting below.
+There must be exactly one B<Type> option inside each B<Result> block.
+
=item B<InstancesFrom> I<column0> [I<column1> ...]
Specifies the columns whose values will be used to create the "TypeInstance"
The plugin itself does not check whether or not all built instances are
different. It's your responsibility to assure that each is unique.
+There must be at least one B<InstancesFrom> option inside each B<Result> block.
+
=item B<ValuesFrom> I<column0> [I<column1> ...]
Names the columns whose content is used as the actual data for the data sets
it should be able to handle integer an floating point types, as well as strings
(if they include a number at the beginning).
+There must be at least one B<ValuesFrom> option inside each B<Result> block.
+
=back
=head3 B<Database> blocks
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
+The "oracle" plugin uses the Oracle® Call Interface I<(OCI)> to connect to an
Oracle® Database and lets you execute SQL statements there. It is very similar
to the "dbi" plugin, because it was written around the same time. See the "dbi"
plugin's documentation above for details.
<Plugin oracle>
<Query "out_of_stock">
Statement "SELECT category, COUNT(*) AS value FROM products WHERE in_stock = 0 GROUP BY category"
- Type "gauge"
- InstancesFrom "category"
- ValuesFrom "value"
+ <Result>
+ Type "gauge"
+ InstancesFrom "category"
+ ValuesFrom "value"
+ </Result>
</Query>
<Database "product_information">
ConnectID "db01"
<Plugin postgresql>
<Query magic>
- Query "SELECT magic, spells FROM wizard WHERE host = $1;"
+ Statement "SELECT magic FROM wizard WHERE host = $1;"
Param hostname
- Column gauge magic
- Column counter spells
+ <Result>
+ Type gauge
+ InstancePrefix "magic"
+ ValuesFrom magic
+ </Result>
+ </Query>
+
+ <Query rt36_tickets>
+ Statement "SELECT COUNT(type) AS count, type \
+ FROM (SELECT CASE \
+ WHEN resolved = 'epoch' THEN 'open' \
+ ELSE 'resolved' END AS type \
+ FROM tickets) type \
+ GROUP BY type;"
+ <Result>
+ Type counter
+ InstancePrefix "rt36_tickets"
+ InstancesFrom "type"
+ ValuesFrom "count"
+ </Result>
</Query>
<Database foo>
KRBSrvName "kerberos_service_name"
Query magic
</Database>
+
<Database bar>
Service "service_name"
+ Query backend # predefined
+ Query rt36_tickets
</Database>
</Plugin>
The B<Query> block defines one database query which may later be used by a
database definition. It accepts a single mandatory argument which specifies
-the name of the query. The names of all queries have to be unique. The
-following configuration options are available to define the query:
+the name of the query. The names of all queries have to be unique (see the
+B<MinPGVersion> and B<MaxPGVersion> options below for an exception to this
+rule). The following configuration options are available to define the query:
+
+In each B<Query> block, there is one or more B<Result> blocks. B<Result>
+blocks define how to handle the values returned from the query. They define
+which column holds which value and how to dispatch that value to the daemon.
+Multiple B<Result> blocks may be used to extract multiple values from a single
+query.
=over 4
-=item B<Query> I<sql query>
+=item B<Statement> I<sql query statement>
-Specify the I<sql query> which the plugin should execute. The string may
-contain the tokens B<$1>, B<$2>, etc. which are used to reference the first,
-second, etc. parameter. The value of the parameters is specified by the
+Specify the I<sql query statement> which the plugin should execute. The string
+may contain the tokens B<$1>, B<$2>, etc. which are used to reference the
+first, second, etc. parameter. The value of the parameters is specified by the
B<Param> configuration option - see below for details. To include a literal
B<$> character followed by a number, surround it with single quotes (B<'>).
allowed. Note, however, that only a single command may be used. Semicolons are
allowed as long as a single non-empty command has been specified only.
+The returned lines will be handled separately one after another.
+
+=item B<Query> I<sql query statement>
+
+This is a deprecated synonym for B<Statement>. It will be removed in version 5
+of collectd.
+
=item B<Param> I<hostname>|I<database>|I<username>
Specify the parameters which should be passed to the SQL query. The parameters
Please note that parameters are only supported by PostgreSQL's protocol
version 3 and above which was introduced in version 7.4 of PostgreSQL.
+=item B<Type> I<type>
+
+The I<type> name to be used when dispatching the values. The type describes
+how to handle the data and where to store it. See L<types.db(5)> for more
+details on types and their configuration. The number and type of values (as
+selected by the B<ValuesFrom> option) has to match the type of the given name.
+
+This option is required inside a B<Result> block.
+
+=item B<InstancePrefix> I<prefix>
+
+=item B<InstancesFrom> I<column0> [I<column1> ...]
+
+Specify how to create the "TypeInstance" for each data set (i.E<nbsp>e. line).
+B<InstancePrefix> defines a static prefix that will be prepended to all type
+instances. B<InstancesFrom> defines the column names whose values will be used
+to create the type instance. Multiple values will be joined together using the
+hyphen (C<->) as separation character.
+
+The plugin itself does not check whether or not all built instances are
+different. It is your responsibility to assure that each is unique.
+
+Both options are optional. If none is specified, the type instance will be
+empty.
+
+=item B<ValuesFrom> I<column0> [I<column1> ...]
+
+Names the columns 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<Type> setting as explained 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 actual data type, as seen by PostgreSQL, is not that important as long as
+it represents numbers. The plugin will automatically cast the values to the
+right type if it know how to do that. For that, it uses the L<strtoll(3)> and
+L<strtod(3)> functions, so anything supported by those functions is supported
+by the plugin as well.
+
+This option is required inside a B<Result> block and may be specified multiple
+times. If multiple B<ValuesFrom> options are specified, the columns are read
+in the given order.
+
=item B<Column> I<type> [I<type instance>]
-Specify the I<type> and optional I<type instance> used to dispatch the value
-of each result column. Detailed information about types and their
-configuration can be found in L<types.db(5)>. The number and order of the
-B<Column> options has to match the columns of the query result.
+This is a deprecated alternative to a B<Result> block. It will be removed in
+version 5 of collectd. It is equivalent to the following B<Result> block:
+
+ <Result>
+ Type I<type>
+ InstancePrefix I<type instance>
+ ValuesFrom I<name of the x. column>
+ </Result>
+
+The order of the B<Column> options defines which columns of the query result
+should be used. The first option specifies the data found in the first column,
+the second option that of the second column, and so on.
=item B<MinPGVersion> I<version>
=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.
+no-match is returned and vice versa. Please note that the B<Invert> setting
+only effects how B<Min> and B<Max> are applied to a specific value. Especially
+the B<DataSource> and B<Satisfy> settings (see below) are not inverted.
+
+=item B<DataSource> I<DSName> [I<DSName> ...]
+
+Select one or more of the data sources. If no data source is configured, all
+data sources will be checked. If the type handled by the match does not have a
+data source of the specified name(s), this will always result in no match
+(independent of the B<Invert> setting).
+
+=item B<Satisfy> B<Any>|B<All>
+
+Specifies how checking with several data sources is performed. If set to
+B<Any>, the match succeeds if one of the data sources is in the configured
+range. If set to B<All> the match only succeeds if all data sources are within
+the configured range. Default is B<All>.
+
+Usually B<All> is used for positive matches, B<Any> is used for negative
+matches. This means that with B<All> you usually check that all values are in a
+"good" range, while with B<Any> you check if any value is within a "bad" range
+(or outside the "good" range).
=back
Example:
- # Match all values smaller than or equal to 100.
+ # Match all values smaller than or equal to 100. Matches only if all data
+ # sources are below 100.
+ <Match "value">
+ Max 100
+ Satisfy "All"
+ </Match>
+
+ # Match if the value of any data source is outside the range of 0 - 100.
<Match "value">
+ Min 0
Max 100
+ Invert true
+ Satisfy "Any"
</Match>
=back
projects / collectd.git / blobdiff