Rules
Components can contain various data types:
- Numeric
- String
- Boolean
A rule is composed from conditions. There are 3 types of conditions (all can be mixed in one rule):
- Basic
- Time-based
- Statistics-based
Conditions in specific rule can be connected by:
- logical alternation OR
- logical conjunction AND
Operators used in conditions:
- greater than (>)
- less than (<)
- greater than or equal (>=)
- less than or equal (<=)
- equal
- not equal
- like (only for strings, same as string.contains(string))
- between (fulfilled when value is in defined range)
- not between
Basic condition checks for any value from defined components and alert is triggered when processed observation by rule engine meets the condition.
Example:
temperature > 50
Notice: Rule engine fetches rules every 10 seconds. Some time (in milliseconds) takes to process all rules. So the maximum delay between rule creation and actual rule activation is ~10 s . This affects all rules.
If conditions are combined with OR, if any condition is fulfilled as simple basic condition, then alert is triggered (conditions fulfill rule independently).
Example:
temperature (orange) > 50 OR humidity (yellow) < 30
Alerts are triggered if any condition is fulfilled.
If N conditions are combined with AND, rule is fulfilled when every condition is fulfilled within 2-minute time window.
Examples:
temperature (orange) > 50 AND humidity (yellow) < 30
This needs more explanation. Let's look at the first red circle (alert). The alert is sent when every other condition has last state fulfilled in 2-minute time span before this point. As we can see before this point we have humidity fulfillment at value = 28 . It fits in the 2-minute window, so the whole rule triggers alert. Just imagine this as a boolean flag for every condition - if incoming observation matches condition, the flag is set to true for 2 minutes. Every other matching observation sets its own condition's flag to true for 2 minutes and checks if all other flags are set to true. If so, alert is triggered.
temperature (orange) > 50 AND humidity (yellow) < 30
The corresponding fulfillment point is the nearest point before the point being examined.
Negative example:
orange > 70 cm AND blue > 60 cm
In the example chart you can see a problem with time window. The first orange fulfillment is valid for 2 minutes, so the yellow point wouldn't raise an alert (it is a little more than 2 minutes away from the last orange fulfillment).
A time-based condition is fulfilled when in specific, user-defined time all observations meet the requirements.
Examples:
value > 10, time span = 8 min
Notice: The earliest alert may be triggered after user-defined time. This time must elapse before alert trigger.
If defined time has elapsed and all observations fulfill condition, all observations after that, which fit to requirements, would trigger alerts until receiving of bad sample.
This chart shows where is the bad sample from which gearpump starts counting the defined time span. Yellow points are after bad sample. Grey vertical line is 8 minutes before the alert was triggered. As we can see condition "observations must be higher than 10 for at least 8 minutes" is fulfilled here (actually that's how we can describe time-based condition!).
Two things are important here:
- gearpump application starts counting time span on first correct sample after bad one. That's why we don't have alerts for 16:13 and 16:15.
- notice that the point at 16:08 has to be greater than 10. Otherwise there would be no alert. The first observation before (or exactly at) 16:10 has to fulfill the condition.
Notice that our rule engine doesn't take into account the lines between the points (only observations' accurate values).
If conditions are combined with OR, if any condition is fulfilled as simple time-based condition, then alert is triggered (conditions fulfill rule independently).
If N conditions are combined with AND, rule is fulfilled when every condition is fulfilled within its own time window.
Example:
blue condition: value > 50, time span = 5 orange condition: value > 10, time span = 8
Blue condition has to wait for orange condition to be fulfilled to send the alert (AND operator). If on a certain point of time blue is fulfilled orange has to be fulfilled too at the same time (e.g bad observation between particular fulfillments could revoke the rule's fulfillment).
Counting time span doesn't actually starts on the first point fulfilling the condition. Look that in the above chart for blue condition there is 6 minutes between first fulfillment and alert (not 5!), because of important thing mentioned earlier: observations must fulfill the condition for at least defined time span.
Notice: The earliest alert may be triggered after the longest user-defined time. This time must elapse before any alert trigger.
A statistics-based condition is a condition with defined statistic to compute data against. To create this condition you must provide time which limits available data used to calculate (e.g. if you choose 10 minutes, only data received in last 10 minutes is taken into account) and minimal instances for calculation i.e. minimum amount of data samples to calculate desired value.
Example: > 2stdev, time span = 5, amount = 10
Let's look at this example chart. The condition in this case would not trigger any alert, because in desired time span there is not enough amount of observations. It could start triggering alerts after lowering the amount or expanding time span. Actually, these parameters describes the minimum density of data to calculate statistics against.
Notice: As opposed to time-based condition, this one can start triggering alerts after reaching minimum amount of samples. In time-based condition, the delay between rule creation and first alert trigger is at least user-defined time long. If quantity of gathered samples is greater than desired minimum, the condition could be fulfilled, no matter how long the time span is.
The statistics now available are: 2stdev (2 standard deviations) and 3stdev (3 standard deviations). It is related to well-known statistics rule called 68–95–99.7 rule described on Wikipedia .
In short terms, this kind of condition is fulfilled for unusual values occurrence. The above image shows normal probability distribution of data. Percentages describes how many data (statistically) are between particular ranges. μ is the average and σ is the standard deviation. The distance between specific data and μ describes how unusual the value is (the greater the distance, the more unusual value). So, if we want for example ~5% of data, that is far from mean (unusual), then we choose not between 2stdev (whole data except orange-coloured).
| Statistic condition | Trigger on... | Percentage [%] |
|---|---|---|
| between 2stdev | usual data | 95 |
| not between 2stdev | unusual data | 5 |
| > 2stdev | unusual data greater than average | ~2.2 |
| < 2stdev | unusual data less than average | ~2.2 |
| between 3stdev | very usual data (almost all) | 99.7 |
| not between 3stdev | very unusual data (almost none) | 0.3 |
| > 3stdev | very unusual data greater than average | ~0.1 |
| < 3stdev | very unusual data less than average | ~0.1 |
Example:
condition: Not between 2stdev (trigger on 5% of unusual data), time limit: 120 min, minimal instances: 5
In the chart a red point will trigger the alert. The defined time span takes all observations visible on the chart. Changing the time span would change the behavior - alert would not be triggered. But changing the minimal instances count wouldn't affect the condition, until it is less than observations quantity visible on the chart.
Example:
condition: Not between 2stdev (trigger on 5% of data), time limit: 10 min, minimal instances: 10
This wouldn't trigger an alert. Time span is too short. Pink point is an unusual observation. Let's change time limit to 1 hour and minimal instances to all observations which can be seen on the chart. This is a negative example too: rule engine would start calculating statistics after the unusual data was received. So, points that are past and used to calculate further statistics would not trigger the alert.
If conditions are combined with OR, if any condition is fulfilled as simple statistics-based condition, then alert is triggered (conditions fulfill rule independently).
If N conditions are combined with AND, rule is fulfilled when every condition is fulfilled within its own amount window.
Amount window - as opposed to time-based, statistics-based has to reach an minimum amount of data in defined time span. It doesn't need to wait for time span to elapse.
Example:
orange: Not between 3stdev (trigger on 0.3% of data), time limit: 50 min, minimal instances: 2
blue: Not between 3stdev (trigger on 0.3% of data), time limit: 50 min, minimal instances: 10
| Kind of condition | Fulfillment | Minimum requirement for alert triggering |
|---|---|---|
| Basic | Any sample matches defined condition | Rule engine fetch and process delay (+10 s) elapsed |
| Time-based | All samples in defined time span matches condition | Defined time span elapsed |
| Statistics-based | Statistic calculation result from all samples in defined time span matches defined condition | Minimum sample amount reach event |
| Basic AND basic | Final state of every condition is fulfilled within 2 minute time window | Rule engine fetch and process delay (+10 s) elapsed |
| Time AND time | Every condition is fulfilled within its own time window | the longest user-defined time elapsed |
| Statistics AND statistics | fulfilled within its own amount window | Minimum sample amount reach event of every condition |
| Basic AND time | All samples for specific component in defined time span matches condition and basic condition was fulfilled in last 2 minutes | Defined time span elapsed |
| Basic AND statistics | Statistic calculation result from all samples in defined time span matches defined condition and basic condition was fulfilled in last 2 minutes | Minimum observation amount reach event |
| Time AND statistics | All samples in defined time span matches condition and statistic calculation result from all samples in defined time span | Defined time span from time-based condition elapsed and minimum sample amount reach event of every condition |
| Basic AND time AND statistics | All samples in defined time span matches condition and statistic calculation result from all samples in defined time span and basic condition was fulfilled in last 2 minutes | Defined time span from time-based condition elapsed and minimum sample amount reach event of every condition |