Help centre - Matching Expressions

Filter using Matching Expressions.

Matching Expressions are filters configurable for every alert. Only incoming events that match the filter will be processed and can affect the alert state. More specifically:

Attribute existence is tested: Events are only considered for processing if all attribute names in a filter a) refer to an existing attribute in an event or b) refer to a non-existing attribute in the event and test it against 'undef' keyword. If an attribute name in an alert's matching expression refers to a non-existing name in an event, the event will not be processed.
The filter matched. Events are processed if the filter does match.

All essential alert types offer the possibility to specify a filter. An empty filter lets everything pass. Some alert types may use multiple ones: Particularly, the "ratio"-based alert can be used to compute ASR so that it initially filters successful call-start events plus failing call-attempt events and then computes the percentage of the call-start subset determined using the next filter.

A basic term consists of an attribute name, operator, and operand. The following expression looks for the event of "call-start" type:

attrs.type="call-end"

The name can include multiple dot-separated entries for nested attributes. Available operators are equal "=", begins with "^", RegExp "~", smaller "<" and greater ">" such as in the following example:

attrs.duration>3600

The next example uses a regular expression to capture both call-start and call-attempt events.

attrs.type~"call-start|call-attempt"

The right-hand operand can be a number, a string enclosed in "" or '', or the term undef (without enclosure!). The term undef evaluates true if the attribute doesn't exist in the inspected JSON.document.

attrs.foo=undef

Multiple terms can be "ANDed" using "&", then the matching expression only evaluates true if all terms are true. The following expression is true for call-end events reporting calls longer than an hour.

attrs.type="call-end" & attrs.duration>3600

Negation can be used to negate a term. It is expressed by an exclamation mark before the term. The following example matches if a MOS average value is less than or equal to 3.0 .

! attrs.rtp-MOScqex-avg-a>3.0 & rtp-MOScqex-avg-b>3.0

More Complex Expressions

It is a good practice to keep the expressions simple and easy to read. Nonetheless, there may be cases when a more complicated expression can help to address a precarious case. The following additional expressions are available:

| can be used as OR between terms
() can be used to establish a precedence explicitly
>= and <= operators are also possible
@time ca
@time can be used to test against the current clock, as shown in the examples below. if no timezone is specified, UTC is assumed.

@time.dow → current weekday abbrev (Mon, Tue, …)

@time.hour → current hour (0–23)

@time.minute → current minute (0–59)

@time.hhmm → current time as HHMM integer (e.g. 1430)

@time.weekday → "true" / "false"

or as a convenience atom:

@time(Mon) → @time.dow="Mon"

@time(Mon-Fri) → OR of individual days

@time(09:00-17:00) → @time.hhmm>=900 & @time.hhmm<1700

@time(Mon-Fri 09:00-17:00) → combined day OR and time AND

@time[America/New_York](Mon-Fri 09:00-17:00) → per-expression timezone

Note: The filtering language is rather simple on purpose: it allows unamgibuous matching of incoming event elements and it can be translated into elastic query expressions to narrow down the events that have led to raising an alert. Unlike in matching expressions, there are cases where more complex expressions are helpful to extract data from an event: in "select" parameter and formatting string. JSONpath expressions can be used there instead.

Page updated

Report abuse