X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=src%2Fcollectd.conf.pod;h=55aa69b60345e7650781ff13ac1959529db312ba;hb=ef7fec0c4e0bbbabb356e6a570ac6297ee06eb80;hp=5d07ee5288f8d14e514af0782cf542670b3306c2;hpb=568420ac172981edccb8587cc9651952fe350365;p=collectd.git diff --git a/src/collectd.conf.pod b/src/collectd.conf.pod index 5d07ee52..55aa69b6 100644 --- a/src/collectd.conf.pod +++ b/src/collectd.conf.pod @@ -646,6 +646,101 @@ description see above. Valid multipliers here are C (byte), C (kilobyte), C (megabyte), C (gigabyte), C (terabyte), and C

(petabyte). Please note that there are 1000 bytes in a kilobyte, not 1024. +=item B I|I + +Controls whether or not to recurse into subdirectories. Enabled by default. + +=back + +=head2 Plugin C + +This plugin allows you to filter and rewrite 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 + + + + Plugin "^sensors$" + PluginInstance "^Some Weird Sensor Chip Name Prefix" + + SubstitutePluginInstance "foo" + + + +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. + +=item B I + +=item B I + +=item B I + +=item B I + +=item B I + +Upon a successful match, the matching substring will be replaced by the +specified I text. These options require that an appropriate regex +has been specified before, e.Eg. B requires that the +B option has been specified before. + +B: It is not recommended to modify the type unless you really know what +you are doing. The type is used to identify the data-set definition of the +dispatched values. + =back =head2 Plugin C @@ -924,12 +1019,12 @@ database when started and keeps the connection up as long as possible. When the 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 and evaluates C, -C and C which correspond to F, -F and F. Also, the values of -C are put in F and values of C are put -in F. Please refer to the B, -I<5.2.4. Server Status Variables> for an explanation of these values. +This plugin issues the MySQL C command and collects information +about MySQL network traffic, executed statements, requests, the query cache +and threads by evaluating the C, C, +C, C and C return values. Please refer to the +B, I<5.1.6. Server Status Variables> for an +explanation of these values. Use the following options to configure the plugin: @@ -941,7 +1036,9 @@ Hostname of the database server. Defaults to B. =item B I -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 privilege). +Any existing MySQL user will do. =item B I @@ -952,6 +1049,23 @@ Password needed to log into the database. Select this database. Defaults to I which is a perfectly reasonable option for what this plugin does. +=item B I + +TCP-port to connect to. The port must be specified in its numeric form, but it +must be passed as a string nonetheless. For example: + + Port "3306" + +If B is set to B (the default), this setting has no effect. +See the documentation for the C function for details. + +=item B I + +Specifies the path to the UNIX domain socket of the MySQL server. This option +only has any effect, if B is set to B (the default). +Otherwise, use the B option above. See the documentation for the +C function for details. + =back =head2 Plugin C @@ -1254,6 +1368,65 @@ 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 @@ -1653,6 +1826,15 @@ collected for these selected processes are size of the resident segment size (RSS), user- and system-time used, number of processes and number of threads, and minor and major pagefaults. +=item B I I + +Similar to the B option this allows to select more detailed +statistics of processes matching the specified I (see L for +details). The statistics of all matching processes are summed up and +dispatched to the daemon using the specified I as an identifier. This +allows to "group" several processes together. I must not contain +slashes. + =back =head2 Plugin C @@ -1870,16 +2052,16 @@ user using (extended) regular expressions, as described in L. Instance "exim" - 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" - Regex "\\" - DSType "CounterInc" - Type "counter" - Instance "local_user" + Regex "\\" + DSType "CounterInc" + Type "counter" + Instance "local_user" @@ -2210,7 +2392,7 @@ information. Instance "cached" - WarningMin 100000000 + WarningMin 100000000 @@ -2280,6 +2462,393 @@ only one such notification is generated until the value appears again. =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, +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 + +A I is a criteria to select specific values. Examples are, of course, the +name of the value or it's current value. + +=item B + +A I 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 and B, see below. + +Some targets, for example the built-in B target, signal that processing +of a value should be stopped. In that case processing of the current chain will +be aborted. + +=item B + +The combination of any number of matches and at least one target is called a +I. The target actions will be performed for all values for which B +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 + +A I 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: + + + + + Plugin "^mysql$" + Type "^mysql_command$" + TypeInstance "^show_" + + + + + + Plugin "rrdtool" + + + +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 I + +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 block, there can be B blocks and B blocks. + +=item B [I] + +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 block, there may be any number of B blocks and there +must be at least one B block. + +=item B I + +Adds a match to a B 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 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: + + + + +=item B I + +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 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: + + + + +=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 + +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 target +(see below). This is very similar to the B target of iptables, see +L. + +This target does not have any options. + +Example: + + Target "return" + +=item B + +Signals the "stop" condition, causing processing of the value to be aborted +immediately. This is similar to the B target of iptables, see +L. + +This target does not have any options. + +Example: + + Target "stop" + +=item B + +Sends the value to write plugins. + +Available options: + +=over 4 + +=item B I + +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: + + + Plugin "rrdtool" + + +=item B + +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 target, i.Ee. with the next target or the next rule. +This is similar to the B<-j> command line option of iptables, see +L. + +Available options: + +=over 4 + +=item B I + +Jumps to the chain I. This argument is required and may appear only once. + +=back + +Example: + + + Chain "foobar" + + +=back + +=head2 Available matches + +=over 4 + +=item B + +Matches a value using regular expressions. + +Available options: + +=over 4 + +=item B I + +=item B I + +=item B I + +=item B I + +=item B I + +Match values where the given regular expressions match the various fields of +the identifier of a value. If multiple regular expressions are given, B +regexen must match for a value to match. + +=back + +Example: + + + Host "customer[0-9]+" + Plugin "^foobar$" + + +=item B + +Matches the actual value of data sources against given minimumE/ 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 I + +Sets the smallest value which still results in a match. If unset, behaves like +negative infinity. + +=item B I + +Sets the largest value which still results in a match. If unset, behaves like +positive infinity. + +=item B B|B + +Inverts the selection. If the B and B settings result in a match, +no-match is returned and vice versa. + +=back + +Either B or B, but not both, may be unset. + +Example: + + # Match all values smaller than or equal to 100. + + Max 100 + + +=back + +=head2 Available targets + +=over 4 + +=item B + +Sets part of the identifier of a value to a given string. + +Available options: + +=over 4 + +=item B I + +=item B I + +=item B I + +=item B I + +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: + + + PluginInstance "coretemp" + TypeInstance "core3" + + +=back + +=head2 Backwards compatibility + +If you use collectd with an old configuration, i.Ee. one without a +B block, it will behave as it used to. This is equivalent to the +following configuration: + + + Target "write" + + +If you specify a B block anywhere, the B 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.Ee. can't +be an FQDN. + + + + + Host "^[^\.]*$" + + Target "stop" + + Target "write" + + =head1 SEE ALSO L, @@ -2288,9 +2857,12 @@ L, L, L, L, +L, L, L, +L, L, +L, L, L