Filters
Filters are used by several checks to filter resulting items from a list. Think of this as the "SELECT criteria from SQL" or similar you literally flag items from a large set as "interesting" or "not interesting". The end result is a sub-set of the original set.
The first check to see this was the CheckEventLog but it has since been added in more places and since the syntax is the same (in fact the code as well is the same). This page describes the underlaying concept.
Modules Using Filters
- CheckEventLog
- CheckFile2?
- CheckWMI
Syntax
A filter is made up of three things:
- Filter mode Determines what happens when the filter is matched.
- Filter type What the filter will match (ie. which field).
- An Expression What to check for.
The syntax of a filter is: filter<mode><type>=<expression>
Order
Order is important, as soon as a positive (+) or negative (-) rule is matched it is either discarded or included (depending on mode) and the checking is "finished" and it will continue with the next entry or line. The best way here is to have an "idea" either remove all entries first or include all required ones first (depending on what you want to do). You can mix and such but this will probably complicate things for you unless you actually need to.
Filter modes
Capturing entries (or discarding them) are done with filters. There are three kinds of filters.
| <filter mode> | title | description |
| + | positive requirements | All these filters must match or the row is discarded. |
| . | potential matches | If this matches the line is included (unless another lines overrides). |
| - | negative requirements | None of these filters can match (if any do the row is discarded). |
Thus if you want to have: all errors and entries from the last month but not the ones from the cdrom, but if the source is MyModule? get everything. I would break this down as such: (notice there are other options). + type=error
- date=older than 2 months
. source=MyModule? This would pick up all errors, and drop all old records and then pickup all remaining "MyModule?" records (in this case you could have used + on the source filter since there are no more rules).
Filter Types
Filter types are the keywords you can match against they are always different for each CheckCommand? so check the documentation for the check you are using for details.
In general you can say thay they consist of a keyword representing a "value" in the line or object. They also have different associated "value types" which can be used for the value part. Common value types are
time expression
A time expression is a date/time interval as a number prefixed by a filter prefix (<, >, =, !=) and followed by a unit postfix (m, s, h, d, w). A few examples of time expression are: filter+generated=>2d means filter will match any records older than 2 days, filter+generated=<2h means match any records newer then 2 hours. Warning, the bash interprets the "<,>,!". Use the "\" to avoid this. e.g. filter+generated=\>2d . On the Client activate the "Nasty Metachars" Option, to allow the \.
string expression
A string expression is a key followed by a string that specifies a string expression. Currently substr and regexp are supported. Thus you enter filter.message=regexp:(foo|bar) to enter a regular expression and filter-message=substr:foo to enter a substring patter match.
Filter in/out
There are two basic ways to filter:
- in You want to have only specific items. When you filter in it means all records matching your filter will be returned.
- out You want to get all items except specific items. When you filter out it means all records matching your filter will be discarded.
So:
filter=in filter+eventType==warning ... filter=out filter-eventType==warning
They both look similar and will have similar same effect as the first one filters "in" and matches all warnings and the second one filters out and discards all warnings. There is one very fundamental difference though the first one will only return the warnings where as the second one will return all entries and all warnings.
