Revision as of 07:50, 16 July 2009

Starting with version 4.6.0, collectd includes a powerful value processing infrastructure called chains, filter, or filter chain. This infrastructure makes it possible to send values only to a specific write plugin (send some values over the network but write other values to local files only, for example), ignore specific values and so on.

Much of the mechanism and terminology has been borrowed from ip_tables. Each value is submitted to a chain which controls in great detail what should happen with those values. Similar to ip_tables, chains are called during multiple phases of the processing of a value. Currently there are only two such places, but this can be extended as the need arises.

Mechanism and terminology

The two concepts at the center of the whole mechanism are "matches" and "targets": A match selects only those values which match a certain criteria, for example all values from host "foobar.example.com". A target performs an action, usually with or on the value. It could, for example, overwrite the hostname.

Any number of matches and one or more targets are combined into a "rule". If all matches match a value (or no matches have been given at all), all targets are executed with the value. The matches are tried in the order as they are given in the configuration file, but since matches shouldn't have any side effects, the order shouldn't matter.

Any number of rules and one or more "default targets" form a "chain". If a chain is processed, each rule is tested in order and if it matches, the rule's targets are executed.

Each target returns one of three possible statuses:

Continue

Execute the next target, rule or default target if the end of a chain is reached.

Return

The execution of the chain is stopped, and the chain itself will return the Continue status. This means that no more targets and rules will be executed in the current chain, but outside the chain (i. e. in the calling chain or in the main daemon), processing will continue normally.

Stop

Processing of this value is stopped entirely. No further target will be executed and the core daemon will not pass this value to any more chains.

Built-in targets

There are four built-in targets. Plugins may provide additional targets, but you have to load those plugins prior to using those matches. For an overview of other currently available matches, see #Other matches and targets below.

jump

Jumps to another chain and starts executing it. If the called chain encounters a Return status, the next target or rule after the jump target will be executed.

stop

Issues the Stop status. This means that processing of this value will be stopped immediately and no further targets or rules will be executed.

return

Issues the Return status. This means that processing of the current chain is stopped and processing will continue with the next target or match after the jump that called the chain.

write

The only built-in target that isn't directly concerned with control flow: The write target will send the value one, some, or all write plugins.

Pre- and post-cache chains

Illustration how values are passed through the chains and are inserted into the value cache.

The two chains currently available are called "pre-cache chain" and "post-cache chain". To understand their difference, it's crucial to know how collectd's global cache is used.

There is one global cache in collectd into which, by default, all values are inserted. This cached value is used to convert counter values to a rate, for example to the StoreRates option of the CSV plugin. The cache is especially important for the UnixSock plugin, which uses it to handle the LISTVAL and GETVAL commands (see Plain text protocol).

Using this filtering mechanism, you can rename values. If you want to do this, you should do it before the values are added to the cache. Doing otherwise will result in weird behavior with plugins that use the cache.

Other filters in a chain may use the cache themselves. If you put such a rule before the value has been added to the cache, the rule may end up working with the rate from the previous round.

Last but not least, if you chose to ignore values, the behavior of the UnixSock plugin depends on the chain you put such a rule in, too. If the ignore statement is reached in the pre-cache chain, the value will not be written to any files and also the UnixSock plugin will not report it. If the statement is in the post-cache chain, the value may not be written to disk, but programs using the UNIX domain socket will still be able to use it, e. g. collectd-nagios.

The actual names of the pre-cache and post-cache chains depends on the following configuration options:

Other matches and targets

At the time of this writing, the following matches and targets were available. For more information on each match and target, please read the collectd.conf(5) manual page.

Matches

A complete list of all available matches is available on the Table of Matches page.

regex

Matches values by identifies, using regular expressions.

timediff

Matches values with an invalid time, i. e. a time that differs "too much" from the server's time.

value

Matches the actual value of a data source.

Targets

A complete list of all available targets is available on the Table of Targets page.

notification

Creates and dispatches a notification.

replace

Match parts of the identifier and replaces the matched string with something else.

set

(Re)Set one part of the identifier completely with a fixed string.