Threshold pattern

A threshold rule is defined by the threshold pattern. It collects a group of selected events within a time interval and determines, after each event is received, whether a threshold condition has been met. It is a stateful rule.

Overview

The threshold pattern collects events over a time period until a threshold value is met. The time period is indicated by a mandatory time window, as defined by the <timeWindow> element in the rule language.

The threshold pattern provides the following three options for a threshold type:
event count threshold
With this type of threshold, you can define the number of events that must meet the event selection criteria in a certain time period. The defined threshold value is compared to the number of events that have been accepted. When the event count equals the defined limit within the time window, the threshold is met.

This type of threshold can be useful for a very simple event count check. For example, it can answer the question: "Have 5 login failure events occurred within 1 minute?"

This threshold is defined by the <eventCountThreshold> element. The <eventCountThreshold> element also specifies one of the following two possible time interval modes for the time window:
fixed interval
A fixed interval begins when the first event that meets the event selection criteria is received and ends when one of the following occurs:
  • The rule meets its threshold within the specified time duration.
  • The specified time duration has passed.
sliding interval
A sliding interval begins when the first event that meets the event selection criteria is received. However, when the rule has not met its threshold and the specified time duration has passed, the time window adjusts (slides) the beginning time to the event reception time for a new "first" event, which is typically the next event that is accepted. The sliding interval continues to adjust in this way until one of the following occurs:
  • The rule meets its threshold within the specified time duration.
  • After the event that begins the time window is received, no subsequent events are received within the specified time duration.
The event that begins the time window (becomes the new "first" event) is the event with a reception time that meets this criteria: the reception time, added to the time interval duration for the rule, is greater than the current time. Here is the criteria in the form of an equation:
event reception time + time interval duration for rule > current time
When no such event exists, the sliding interval cannot adjust the time any further, and the interval ends.
computed threshold
With this type of threshold, you can write code (or use code that was written by someone else) that performs a computation on each accepted event and returns a computed threshold value that is held in a previously defined variable. This computed threshold value is then compared to a defined threshold value to determine whether the threshold is met.

Therefore, a complex computation can be applied to create (or update) a computed threshold value, possibly using data that is saved from previous events, and the rule writer can set the defined threshold value independently of the logic that calculates the computed threshold value.

This type of threshold can be useful for the aggregation and comparison of a value to a defined threshold value. For example, it can be used to calculate the sum of the dollar amount of sales to a certain customer over a certain period of time and to compare that sum to a defined threshold value.

This threshold is defined by the <computedThreshold> element.

boolean threshold
With this type of threshold, you can write code (or use code that was written by someone else) that returns a value of true or false for each accepted event. If the value is true, the threshold has been met. If the value is false, the threshold rule continues to process until the time period is over or until it accepts another event.

This type of threshold can be useful for checking a range of values. For example, if CPU utilization must be between 30% and 80% at all times, this threshold can constantly verify that the utilization remains within that range.

This threshold is defined by the <booleanThreshold> element.

Conditions under which the rule response runs

With the threshold pattern, the rule response runs at the following times:
  • When the threshold has been met, as defined by the <onDetection> element.
  • When one or more events are accepted but the threshold is not met within the time window, as defined by the <onTimeOut> element.

Example usage of this rule pattern

An example usage of the threshold pattern with the event count threshold is a rule that does the following:
If more than 4 Server unreachable events originate from the same subnetwork within a sliding time interval of 30 seconds, the rule runs an action to check the status of a router.
Related reference
Threshold rule summary