Regular expressions in Checkmk

With regular expressions, it is always a question of whether a pattern matches a certain text (e.g. a service name). The simplest application example is a chain of alphanumeric characters. These (and the minus sign used as a hyphen) simply match themselves in an expression.

When searching in the monitoring environment Checkmk is usually not case-sensitive. In most cases, the expression CPU load matches the text CPU load as well as cpu LoAd. Searching in the configuration environment, on the other hand, is usually case-sensitive. Justified exceptions to these standards are possible and are described in the inline help.

Attention: In input fields without a regular expression where an exact match is specified (mostly with host names), upper and lower case are always distinguished!

In addition to the 'plain text' character strings, there are a number of characters and character strings that have 'magic' functions. The most important such character is the . (point). It exactly matches any single arbitrary character:

One would very often like to define that a sequence of characters of a certain length may occur. For this purpose one specifies the number of repetitions of the preceding character in curly brackets:

There are abbreviations for the last three above conditions: * matches the preceding character any number of times, + matches at least one occurrence and ? matches at most one occurrence.

You can also use the period . with the repeat operators to search for a sequence of arbitrary characters in a more defined way:

Character classes allow certain sections of the character set to be matched, for example, "here must come a digit". To do this, place all of the characters to be matched within square brackets. With a minus sign you can also specify ranges. Note: The sequence in the 7-bit ASCII character set applies.

For example, [abc] stands for exactly one of the characters a, b or c, and [0-9] for any digit — both can be combined. Also a negation of the whole is possible — with a ^ in the parenthesis, [^abc] then stands for any character except a, b, c.

Character classes can of course be combined with other operators. Let’s start with some abstract examples:

Here are some practical examples:

Note: If you need one of the characters -, [ or ], you will have to use a trick. Write the - (minus sign) at the end of the class — as already shown in the previous example. When evaluating the regular expressions the minus sign, if it is not in the middle of three characters, is not evaluated as an operator, but as exactly this character. If necessary insert a closing square bracket as the first character in the class, and an opening bracket as the second character. Since no empty classes are allowed, the closing square bracket is then interpreted as a normal character. A class with these special characters would look like this: []-], or respectively [][-] if the opening square bracket is also needed.

In many cases it is necessary to distinguish between matches at the beginning, at the end or simply somewhere within a string. For a match of the beginning of a string (prefix match) use the ^ (circumflex), for the end (suffix match) use the $ (dollar sign). If neither of these operators is specified, most regular expression libraries use the infix-match as the default — it is searched for anywhere in the character string. For exact matches, use both ^ and $.

Note: In monitoring and the Event Console, infix match is the standard. Expressions that occur anywhere in the text are found, i.e. the search for 'memory' also finds 'kernel memory'. In the Setup GUI, on the other hand, when comparing regular expressions with service names and other things, Checkmk basically checks whether the expression matches the beginning of the text (prefix match) — this is usually what you are looking for:

If you do need an infix match in places where prefix match is provided, simply extend your regular expression with .* at the beginning to match any prefixed string:

Tip: You can preface any search at the beginning of a string with ^ and any search within a string with .*, the regular expression interpreters will ignore redundant symbols.

Since the point matches everything, it naturally also matches a point. If you now want to match exactly one point, you have to mask it with a \ (backslash). This applies analogously for all other special characters. These are: \ . * + ? { } ( ) [ ] | & ^ and $. Coding a \ backslash results in the special character following it being treated as a normal character:

Attention Python: Since in Python the backslash in the internal string representation is masked internally with another backslash, these two backslashes must be masked again, which leads to a total of four backslashes:

With the vertical line | you can define alternatives, i.e. use an OR operation: 1|2|3 matches 1, 2 or 3. If you need such alternatives in the middle of an expression, group them within round brackets:

Match groups (or capture groups) fulfill two functions: The first function is the grouping of alternatives or partial matches, as shown in the previous example. Nested groupings are also possible. In addition, the repeat operators *, +, ? and {…​} may be used preceded by round brackets. Thus the expression (/local)?/share matches both /local/share and /share.

The second function is to 'capture' matched character groups in variables. In the Event Console (EC), Business Intelligence (BI), in bulk renaming of hosts and in piggyback mappings, there is the possibility of using the text part corresponding to the regular expression in the first parenthesis as \1, the part corresponding to the second parenthesis as \2, and so on. The last example in the table shows the use of alternatives within a match group.

The following image shows such a renaming of multiple hosts in a single action. All host names that match the regular expression server-(.*)\.local will be replaced by \1.servers.local. Where the \1 stands exactly for the text 'captured' by the .* in the parenthesis:

In the concrete example, server-lnx02.local is thus converted into lnx02.servers.local.

If a match group is not required to 'capture' character groups, for example if it is only used for structuring, ?: can be used to convert it into a non-capturing match group (non-capturing match group): (?:/local)?/share.

With inline flags, specific settings concerning the mode of evaluation can be made within a regular expression. Most relevant for working with Checkmk is (?i), which switches to case-insensitive matching for expressions that are otherwise case-sensitive. In very rare cases, you will also want to use (?s) and (?m) for working with multi-line strings.

Note that since version 3.11 Python expects inline flags either at the beginning of a regular expression - (?i)somestring — or specifying the scope — (?i:somestring). Since Checkmk in some cases combines regular expressions internally for better performance, we strongly advise not to use inline flags at the beginning of a regular expression. Instead, always use the notation with scope — which, when in doubt, extends to the entire regular expression:

(?i:somestring).

This is a variant of the non-capturing match group.

In particular, if proper names in comments or descriptive texts have been copied and pasted, and therefore Unicode characters or different types of spaces appear in the text, Python’s extended classes are very helpful:

In places in which Checkmk allows Unicode matching, \w is particularly useful when searching for similarly-spelled words in different languages, for example proper names that are sometimes written with and sometimes without an accent.