X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=src%2Fcollectd.conf.pod;h=f6efce54870f387a41ebb6cf84be90126483f770;hb=c87da66245197f489bb0e9efffc23538cf07e70b;hp=038def1b516eb49014505b1754f5ad5cebdefad4;hpb=9925e12948defd5b09166aacc807fab2e9dc93e7;p=collectd.git diff --git a/src/collectd.conf.pod b/src/collectd.conf.pod index 038def1b..f6efce54 100644 --- a/src/collectd.conf.pod +++ b/src/collectd.conf.pod @@ -282,6 +282,161 @@ number. =back +=head2 Plugin C + +This plugin uses the "B" library (L) 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. + +Because the plugin is very generic, the configuration is a little more complex +than those of other plugins. It usually looks something like this: + + + + Statement "SELECT category, COUNT(*) AS value FROM products WHERE in_stock = 0 GROUP BY category" + Type "gauge" + InstancesFrom "category" + ValuesFrom "value" + + + Driver "mysql" + DriverOption "host" "localhost" + DriverOption "username" "collectd" + DriverOption "password" "aZo6daiw" + DriverOption "dbname" "prod_info" + SelectDB "prod_info" + Query "out_of_stock" + + + +The configuration above defines one query and one database. The query is then +linked to the database with the B option I the +BDatabaseE> block. You can have any number of queries and databases +and you can also use the B statement to split up the configuration +file in multiple, smaller files. However, the BQueryE> block I +precede the BDatabaseE> blocks, because the file is interpreted from +top to bottom! + +The following is a complete list of options: + +=head3 B blocks + +Query blocks define 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. + +=over 4 + +=item B I + +Sets the statement that should be executed on the server. This is B +interpreted by collectd, but simply passed to the database server. Therefore, +the SQL dialect that's used depends on the server collectd is connected to. + +The query has to return at least two columns, one for the instance and one +value. You cannot omit the instance, even if the statement is guaranteed to +always return exactly one line. In that case, you can usually specify something +like this: + + Statement "SELECT \"instance\", COUNT(*) AS value FROM table" + +(That works with MySQL but may not be valid SQL according to the spec. If you +use a more strict database server, you may have to select from a dummy table or +something.) + +=item B I + +The B that's used for each line returned. See L for more +details on how types are defined. In short: A type is a predefined layout of +data and the number of values and type of values has to match the type +definition. + +If you specify "temperature" here, you need exactly one gauge column. If you +specify "if_octets", you will need two counter columns. See the B +setting below. + +=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. + +The plugin itself does not check whether or not all built instances are +different. It's your responsibility to assure that each is unique. + +=item B I [I ...] + +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 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 actual data type in the columns is not that important. The plugin will +automatically cast the values to the right type if it know how to do that. So +it should be able to handle integer an floating point types, as well as strings +(if they include a number at the beginning). + +=back + +=head3 B blocks + +Database blocks define a connection to a database and which queries should be +sent to that database. Since the used "dbi" library can handle a wide variety +of databases, the configuration is very generic. If in doubt, refer to libdbi's +documentationE- we stick as close to the terminology used there. + +Each database needs a "name" as string argument in the starting tag of the +block. This name will be used as "PluginInstance" in the values submitted to +the daemon. Other than that, that name is not used. + +=over 4 + +=item B I + +Specifies the driver to use to connect to the database. In many cases those +drivers are named after the database they can connect to, but this is not a +technical necessity. These drivers are sometimes referred to as "DBD", +BataBase Briver, and some distributions ship them in separate +packages. Drivers for the "dbi" library are developed by the B +project at L. + +You need to give the driver name as expected by the "dbi" library here. You +should be able to find that in the documentation for each driver. If you +mistype the driver name, the plugin will dump a list of all known driver names +to the log. + +=item B I I + +Sets driver-specific options. What option a driver supports can be found in the +documentation for each driver, somewhere at +L. However, the options "host", +"username", "password", and "dbname" seem to be deEfacto standards. + +Unfortunately, drivers are not too keen to report errors when an unknown option +is passed to them, so invalid settings here may go unnoticed. This is not the +plugin's fault, it will report errors if it gets them from the libraryE/ +the driver. If a driver complains about an option, the plugin will dump a +complete list of all options understood by that driver to the log. + +=item B I + +In some cases, the database name you connect with is not the database name you +want to use for querying data. If this option is set, the plugin will "select" +(switch to) that database after the connection is established. + +=item B I + +Associates the query named I with this database connection. The +query needs to be defined I this statement, i.Ee. all query +blocks you want to refer to must be placed above the database block you want to +refer to them from. + +=back + =head2 Plugin C =over 4 @@ -493,6 +648,70 @@ note that there are 1000 bytes in a kilobyte, not 1024. =back +=head2 Plugin C + +This plugin allows you to filter 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 + + +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. + +=back + =head2 Plugin C To get values from B collectd connects to B (127.0.0.1), @@ -1039,9 +1258,18 @@ L. =head2 Plugin C +B See notes below. + The C plugin uses the B library from the B project L to read sensors connected via the onewire bus. +Currently only temperature sensors (sensors with the family code C<10>, +e.Eg. DS1820, DS18S20, DS1920) can be read. If you have other sensors you +would like to have included, please send a sort request to the mailing list. + +Hubs (the DS2409 chips) are working, but read the note, why this plugin is +experimental, below. + =over 4 =item B I @@ -1058,6 +1286,8 @@ with that version, the following configuration worked for us: Device "-s localhost:4304" +This directive is B and does not have a default value. + =item B I Selects sensors to collect or to ignore, depending on B, see @@ -1077,6 +1307,76 @@ interfaces are collected. =back +B The C plugin is experimental, because it doesn't yet +work with big setups. It works with one sensor being attached to one +controller, but as soon as you throw in a couple more senors and maybe a hub +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 +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:) + +=head2 Plugin C + +The "oracle" plugin uses the Oracle® Call Interface (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. + + + + Statement "SELECT category, COUNT(*) AS value FROM products WHERE in_stock = 0 GROUP BY category" + Type "gauge" + InstancesFrom "category" + ValuesFrom "value" + + + ConnectID "db01" + Username "oracle" + Password "secret" + Query "out_of_stock" + + + +=head3 B blocks + +The Query blocks are handled identically to the Query blocks of the "dbi" +plugin. Please see its documentation above for details on how to specify +queries. + +=head3 B blocks + +Database blocks define a connection to a database and which queries should be +sent to that database. Each database needs a "name" as string argument in the +starting tag of the block. This name will be used as "PluginInstance" in the +values submitted to the daemon. Other than that, that name is not used. + +=over 4 + +=item B I + +Defines the "database alias" or "service name" to connect to. Usually, these +names are defined in the file named C<$ORACLE_HOME/network/admin/tnsnames.ora>. + +=item B I + +Username used for authentication. + +=item B I + +Password used for authentication. + +=item B I + +Associates the query named I with this database connection. The +query needs to be defined I this statement, i.Ee. all query +blocks you want to refer to must be placed above the database block you want to +refer to them from. + +=back + =head2 Plugin C This plugin embeds a Perl-interpreter into collectd and provides an interface @@ -1450,9 +1750,9 @@ In this case please file a bug report with the collectd team. =item B I Configures the path to the UNIX domain socket to be used when connecting to the -daemon. By default C will be used for an -authoritative server and C will be used -for the recursor. +daemon. By default C<${localstatedir}/run/pdns.controlsocket> will be used for +an authoritative server and C<${localstatedir}/run/pdns_recursor.controlsocket> +will be used for the recursor. =back @@ -1478,6 +1778,56 @@ and minor and major pagefaults. =back +=head2 Plugin C + +The C plugin uses the RRDTool accelerator daemon, L, +to store values to RRD files in an efficient manner. The combination of the +C B and the C B is very similar to the +way the C plugin works (see below). The added abstraction layer +provides a number of benefits, though: Because the cache is not within +C anymore, it does not need to be flushed when C is to be +restarted. This results in much shorter (if any) gaps in graphs, especially +under heavy load. Also, the C command line utility is aware of the +daemon so that it can flush values to disk automatically when needed. This +allows to integrate automated flushing of values into graphing solutions much +more easily. + +There are disadvantages, though: The daemon may reside on a different host, so +it may not be possible for C to create the appropriate RRD files +anymore. And even if C runs on the same host, it may run in a +different base directory, so relative paths may do weird stuff if you're not +careful. + +So the B is to let C and C run +on the same host, communicating via a UNIX domain socket. The B +setting should be set to an absolute path, so that a changed base directory +does not result in RRD files being createdE/ expected in the wrong place. + +=over 4 + +=item B I
+ +Address of the daemon as understood by the C function of the RRD +library. See L for details. Example: + + + DaemonAddress "unix:/var/run/rrdcached.sock" + + +=item B I + +Set the base directory in which the RRD files reside. If this is a relative +path, it is relative to the working base directory of the C daemon! +Use of an absolute path is recommended. + +=item B B|B + +Enables or disables the creation of RRD files. If the daemon is not running +locally, or B is set to a relative path, this will not work as +expected. Default is B. + +=back + =head2 Plugin C You can use the settings B, B, B, and B to @@ -1561,8 +1911,8 @@ When collecting many statistics with collectd and the C plugin, you will run serious performance problems. The B setting and the internal update queue assert that collectd continues to work just fine even under heavy load, but the system may become very unresponsive and slow. This is -a problem especially if create graphs from the RRD files on the same machine, -for example using the C script included in the +a problem especially if you create graphs from the RRD files on the same +machine, for example using the C script included in the C directory. This setting is designed for very large setups. Setting this option to a value @@ -1651,7 +2001,7 @@ user using (extended) regular expressions, as described in L. Regex "\\" DSType "CounterInc" - Type "email_count" + Type "counter" Instance "local_user" @@ -1950,6 +2300,9 @@ hosts sends it's CPU statistics to the server every 60 seconds, a notification will be dispatched after about 120 seconds. It may take a little longer because the timeout is checked only once each B on the server. +When a value comes within range again or is received after it was missing, an +"OKAY-notification" is dispatched. + Here is a configuration example to get you started. Read below for more information. @@ -2060,6 +2413,7 @@ L, L, L, L, +L, L, L, L