xinyState
A Workflow Engine function that returns true if it detects that an alert is “flapping” (repeatedly changing state from “down” to “up” or "up" to "down"). The function returns false if flapping is not detected, or if an alert that was previously flapping is no longer flapping.
This function is available as a feature of the Add-ons v2.5 download and later.
This function is available for event workflows only.
Back to Workflow Engine Functions Reference.
Description
Important
This function works on the events for an alert rather than the alert itself, and it is important that the corresponding xinyClose function is used to reset the data when an alert is closed.
The function uses two filters that determine the current status of the event: “up” and “down”. These are SQL-like CEvent filters and can use any of the available event fields (such as core and custom_info). For example, “description matches 'fail’” or “custom_info.priority = 5."
The X parameter defines the threshold of state changes over the Y parameter (in seconds).
A state change is counted when there is a detected change from "down" to "up" or "up" to "down". Repeated events for the same previous state have no impact.
For example, in the following event flow, there would be 3 state changes :
From down to up: e1 to e2
From up to down: e2 to e3
From down to up: e(n) to e(n+1)
The repeated “down” events (e4 - e(n)) have no impact on the state change count.
Intermediate, repeating events also have no impact. For example, the following event flow still has 3 state changes:
The xinyState function returns true as long as the X threshold is breached in Y seconds; that is, during the “flap,” but not after the flap is no longer detected. The XinY calculation is made when the state change is detected.
In the following example, the X value is 3, the Y is 60, 3 state changes in 60 seconds.
After the third state change, the xinyState returns true—there were 3 state changes in the previous 60 seconds. However, after the fourth state change, the xinyState function returns false, since 3 state changes did not occur in the previous 60 seconds.
This moving window ensures the function only returns true during a flap, allowing the flap “flood” to be managed, but allowing non-flap state changes to be processed normally.
Typically, a workflow using the xinyState uses a subsequent function to manage the flap events, dropping the event or modifying the description appropriately. Dropping the event has no impact on the calculation.
Important
It is strongly recommended that you only use this function on a subset of alerts that are known to produce “flapping” conditions that impact downstream behavior. The XinY data is held in memory, and the larger the number of alerts stored, the higher this resource requirement will be. The data held per alert is small. A typical record is shown below, using ~125 bytes to detail the last 4 state transitions and last status. Each state change within the last Y seconds is stored, so a rapidly flapping alert (such as hundreds per second) increases this footprint, as will the duration of Y.
{ "times": [ 1659109326, 1659109340,1659109344, 1659109386 ],"state": "down"}
Arguments
Workflow Engine function xinyState takes the following arguments:
Name | Required | Type | Description |
|---|---|---|---|
| yes | string | CEvent SQL-like filter to determine if an event is “up”. |
| yes | string | CEvent SQL-like filter to determine if an event is “down”. |
| yes | number | The “X” threshold, indicating the number of state changes down to up, or up to down, allowed in the Y threshold. |
| yes | number | The “Y” value, indicating how long a period X is measured over (in seconds). |
Example
In the following example we know that flapping interfaces (linkUp, linkDown SNMP traps) can produce a downstream impact with workflows etc.
Define an Event Workflow with a suitable entry filter - scope the workflow to the target alerts.
Use the
xinyStatefunction. Ensure the Forwarding Behavior is set to “Stop this Workflow”upFilter: description matches “Link Up”downFilter: description matches “Link Down”count: 10seconds: 60
Add a suitable follow on action to execute if the XinY threshold is exceeded (the
xinyStateaction returns true)drop or setDescription
This would appear in the UI as:
{"upFilter":"description matches 'Link Up'","downFilter":"description matches 'Link Down'","count":5,"seconds":60}