ceelog-expression man page

ceelog-expression — ceelog filter expression format


This man page describes the format of "ceelog expressions". Parsing and evaluation of these expressions is provided by libceelog and is common to applications that use this library.

Lexical Structure

White space (ASCII space, tab and new-line characters) and comments between tokens are ignored. Comments either start with // and continue until end of line, or start with /* and end with */ (without nesting).

The following tokens are recognized:

( ) \
Logical operators
! && ||
Comparison operators
== != ~ !~
A sequence of characters surrounded by the " quotes. The \ character starts an escape sequence. The only defined escape sequences are \\ and \". The semantics of other escape sequences is undefined.

A sequence of characters surrounded by the / characters. Escape sequences consisting of \ followed by any single character are recognized and passed to the regex parser unmodified; their only effect is that \/ does not terminate the regex.

The regex is not automatically anchored; use the ^ or $ regex metacharacters to anchor it explicitly if necessary.

Note that // starts a comment; it is not an empty regex.

An ASCII letter or _ followed by a (possibly empty) empty sequence of ASCII letters, digits, and the _ symbol.


Primary Expressions

The primary expression has one of the following forms:

field-path comparison-operator value
A field value comparison, as described below.
Unstructured regex match

Field value comparisons

In a field value comparison, field-path is a sequence of one more identifiers separated by the ! operator. It is evaluated by starting at the root of the JSON content of the event, and using the sequence of identifiers as a path within the object structure. If the event does not have any JSON content, or if the any identifier of the path specifies a non-existing member, or if any but the last identifier of the path specifies a member that is not an object, the result of the comparison is false (regardless of the operator).

comparison-operator specifies the comparison to perform:

== !=
Get a string representation of the field named by field-path, and compare it to value, which must be a string literal.
~ !~
Get a string representation of the field named by field-path, and match it against value, which must be a regex.

In both of the cases above, a "string representation" of a string field is equal to the field's value, and a "string representation" of other fields is a string that is a valid JSON representation of the field's value.

Note that there are many compliant ways to represent composite values (arrays and subobjects), and it is unspecified what the precise string representation is. It is therefore recommended to only use field value comparisons for fields that are strings or integers.

Unstructured Regex Matches

In an unstructured regex match (a standalone regex without specifying a field or operator), the unstructured message within the event is matched against the regex. For event without a JSON content, the unstructured message is the text that remains after removing all known fields (priority, time stamp, host name, tag, PID, the : character and a space). For events with a JSON content, the unstructured message is the content of the top-level field.

Compound expressions

If E1 and E2 are valid expressions, then

( E1 )

! E

E1 && E2

E1 || E2

are valid expressions as well, with the usual C semantics and evaluation priorities.

Note that

! field-path op value

is interpreted as

!(field-path op value)

not as

(!field-path) op value


The following expressions demonstrate the syntax of ceelog expressions:


uid == 0

uid != 0

trusted!uid == 0

username ~ /^guest-/

username !~ /^guest-/

trusted!uid == 0 && username ~ /^guest-/

As a demonstration of the semantics of handling missing fields, the following expression is true if field-path names an existing subobject:

(field-path == "") || (field-path != "")

Future Directions

New escape sequences for quoted strings may be defined.

Referenced By


Explore man page connections for ceelog-expression(5).

ceelog CEELOG 2013-05-17