There are several basic alert types available for capturing various types of anomalies. There are also derived alert types based on the basic ones with "fixed" configuration to address a well-defined use case and simplify configuration. Parameters common to all the alert types are described below.
Common parameter types:
custom key: specifies an event attribute name by which alert processing maps incoming events into streams. See more here. Example: "attrs.from".
filtering expression specifies which events to process using a matching expression. Non-matching events will not be evaluated. Example: "attrs.type='call-start'"
severity: used in alert triage in alerts dashboard and/or external alert management applications such as OpsGenie. The lower the number, the higher the priority. For example 0 for the highest priority.
throttlePeriod: number of seconds for which the alerts will not be re-raised for the given key value. (if, say, an alert is raised for a key "foo@bar.com", it will not be raised for 3600 seconds again even if the alerting conditions are determined all over again. an alert can still be raised for another key like "john@doe.com")
restfulFmt: restful formatting string, for example "alert raised severity ${alert.severity}"
restfulChannel: comma-separated list of restful destinations, for example "slack#1, opsgenie"
This is a simple but still powerful alert type that matches incoming event against a matching expression. A typical use-case is matching call-end events with excessively long duration or abnormally low QoS values.
The common filtering parameter and custom key parameter are sufficient to set this alert up. An optional "inarow" parameter requires a matching event to occur several times in a row before the alert is raised. If series are enabled for this alert type, the right-most numerical term of the matching expression is recorded. (e.g. the value of attrs.duration for filter 'attrs.type="call-end" & attrs.duration>3600'.
Known limitations: -
This alert type observes incoming events using a "sliding window." A typical use case is finding out that a user failed to authenticate too many times in the past five minutes. The alert type keeps observing the most recent period of time and counts received events. The timestamp contained in the event determines if the event falls in a window or not -- delayed events are disregarded. Matching events are either simply counted, or a selected numerical attribute can be summed up. An approximation of a sliding window known as a "hopping window" is used to provide scalability for massive incoming data streams.
Specific parameters:
period: length of the window in minutes
select field: an optional event attribute name such as `attrs.duration` that is used as the event's value instead of simply incrementing the event count. A value can also be gained using JSON-path expressions in more complicated events. See https://www.npmjs.com/package/jsonpath-plus . If the value is empty, the count is simply incremented for an incoming event.
sum threshold: the maximum window sum which, if exceeded, raises the alert
Known limitations: the fundamental limitations stem from the "hopping window" (HW) nature of the underlying algorithm. HW is a compromise between "sliding window" and "tumbling window" algorithms. The sliding window shifts continuously in time and holds all events. As a result, it is accurate, continuous, and expensive in storage. The tumbling window scales well because it shifts with time by the whole window length and can keep the window representation, such as sum or count, aggregated. The hopping window is broken into several equal fragments, each with an aggregated representation: count or sum—the time window shifts to the right discreetly by fragment length whenever its time is due. As a result, the algorithm only holds as many aggregated values as the number of fragments (4 by default) and scales well. Unlike a trembling window, previous "window history" is not lost upon a shift, only a fragment, and so a more continuous effect is achieved.
This alert type observes incoming events in a "sliding window", and checks if a subset of these events doesn't cross a threshold. For example, if call starts and call failures are counted, a too-low percentage of successful call starts suggests there is something wrong in the system. This metrics is known as ASR in telephony.
Specific parameters:
period: length of the window in minutes
subset matching expression: this is a filter applied to events that matched the main filtering expression to determine the measures subset.
select field: an optional event attribute name such as `attrs.duration` that is used as the event's value instead of simply incrementing the event count. A value can also be gained using JSON-path expressions in more complicated events. See https://www.npmjs.com/package/jsonpath-plus . If the value is empty, the count is simply incremented for an incoming event.
limit operator: "<" or ">"
ignore ("don't raise for the first ignore event"): a learning period expressed in a number of events. It prohibits premature alerts when an initial short event burst could establish a "poor ratio" without actual significance.
sum threshold: the window sum which, if crossed, raises the alert
Known limitations: the ratio alert type is based on rate type and same limitations apply.
This alert type associates data from events with a key and checks if more values accumulate and how many. This is typically used to observe changes in user behavior, such as observing URIs if they register from unusual geographic regions or call from unusual equipment. An experimental alternative based on probabilistic Bloom filters is also available.
Specific parameters:
select field: this is how the value to be associated with a key is determined. For example `attrs.from-ua` will store the brand of SIP equipment used to make a SIP request. A value can also be gained using JSON-path expressions in more complicated events. See https://www.npmjs.com/package/jsonpath-plus .
ignore ("don't raise for a number of values"): Typically, there is some minimum number of values that show no anomaly. A user can have slightly different behavior when being active from office, home or underway. The ignore parameter makes sure no alert is raised for too few occurences.
Known limitations: CKM can hold up to a specific number of associated entries. (limits.js: MAX_MEM_SIZE=16). The associations are "eternal" -- in some cases, a cardinality of a long-lived entry may surprisingly match cardinality of a short-lived entry with a quick burst of new associations.
This alert type tracks SIP calls that have been observed for the given key. Calls that are not properly terminated within a preconfigured period of time are treated as if they were terminated. The alert type is based on keeping track of sessions. An alternative based on hopping windows (HWPC) is being experimented with to provide higher resilience against lost events.
Specific parameters:
max number of parallel calls: if exceeded, an alert is raised.
Known limitations: missing call-end events are not reflected in the reported number of parallel calls until a timer expires. (siptracker.js: SIP_CALLTRACKING_TIMER_MINUTES=125; // minutes). Call starts that began before processing started are not reflected either.
This alert type observes a value in a window of time and detects when it begins to significantly differ from its smoothened longer-term equivalent. A typical situation this alert type can detect is a rapid change in number of SIP registrations. This often happens when either a SIP registrar looses connectivity or reconnects again.
Specific parameters:
period: length of the window in minutes
declination: percentage by how much the recent values may decline from the longer-term values without raising an alert.
ignore ("don't raise for the first ignore event"): a learning period expressed in a number of events. It prohibits premature alerts when an initial short event burst could establish a "poor ratio" without actual significance.
select field: an optional event attribute name such as `attrs.duration` that is used as the event's value instead of simply incrementing the event count. A value can also be gained using JSON-path expressions in more complicated events. See https://www.npmjs.com/package/jsonpath-plus . If the value is empty, the count is simply incremented for an incoming event.
Known limitations: during an initial "warm-up stage", a false positive may be generated.