![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/src/collectd.conf.pod b/src/collectd.conf.pod
index 113bedde8f6b7296a32ff6d81837bea4bb17679e..9b72b437ffb95cc8e4aa0b31d5ee8d82d5f63f10 100644 (file)
--- a/src/collectd.conf.pod
+++ b/src/collectd.conf.pod
=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"
+ InstancePrefix "out_of_stock"
+ 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"
+ # InstancePrefix "foo"
+ 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<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"
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
=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.
-=item B<Param> I<hostname>|I<database>|I<username>
+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>|I<interval>
Specify the parameters which should be passed to the SQL query. The parameters
are referred to in the SQL query as B<$1>, B<$2>, etc. in the same order as
The username used to connect to the database.
+=item I<interval>
+
+The interval collectd is using (as specified by the B<Interval> option).
+
=back
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>