Docs » Detectors and Alerts » Using Built-in Alert Conditions » Historical Anomaly

Historical Anomaly

What this alert condition does

Alerts when a signal is different from the same periods in the past (for cyclical or seasonal data).

When to use this alert condition

Use the Historical Anomaly alert condition to monitor metrics with patterns that repeat over known, fixed periods of time. To specify the period of time over which patterns repeat, use the Cycle length parameter.

Examples

  • Count of concurrent logins has a weekly pattern; for example, in your environment, Monday mornings might generally have more logins than Friday nights. Set Cycle length to 1w.
  • Sales revenue spikes every three months when you have a seasonal closeout sale. Set Cycle length to 13w.
  • Count of disk reads spikes every 12 hours when an incremental backup kicks off. Set Cycle length to 12h.

Basic settings

PARAMETER VALUES USAGE NOTES
Cycle length Integer >= 1, followed by time indicator (s, m, h, d, w), e.g. 30s, 10m, 2h, 5d, 1w. Value should be significantly larger than the data resolution. The time range that reflects the cyclicity of your signal. For example, a value of 1w indicates your signal follows a weekly cycle (you want to compare data for a Monday morning with previous Monday mornings). A value of 1d indicates your signal follows a daily cycle (you want to compare today’s data with data from the same time yesterday, the day before, etc.)
Alert when Too high, Too low, Too high or Too low Alert is triggered when the signal is either above a threshold, below a threshold, or outside a specified range (e.g. more than 3.5 deviations above or below normal, or more than 30% above or below normal). To specify whether anomalies will be based on standard deviations from normal or percentage difference from normal, choose Custom sensitivity and then the Normal based on parameter.
Trigger Sensitivity Low, Medium, High, Custom Approximately how often alerts will be triggered, where Low can result in fewer alerts being triggered and alerts taking longer to clear (least flappy). Choose Custom to modify the settings that determine triggering and clearing sensitivity (listed below).

Advanced settings

PARAMETER VALUES USAGE NOTES
Normal based on Mean plus standard deviation, Mean plus percentage change If the short-term variation in a signal is small relative to the scale of the signal, and the scale is somehow natural, using Mean plus percentage change is recommended; using Mean plus standard deviation may trigger alerts even for a large number of standard deviations. In addition, Mean plus percentage change is recommended for metrics which admit a direct business interpretation, e.g. if user_sessions drops by 20%, revenue drops by 5%.
Current window Integer >= 1, followed by time indicator (s, m, h, d, w), e.g. 30s, 10m, 2h, 5d, 1w. Value should be smaller than Cycle length, and should be significantly larger than the data resolution. The time range against which to compare the data; you can think of this as the moving average window. Higher values compute the mean over more datapoints, which generally smoothes the value, resulting in lower sensitivity and potentially fewer alerts.
Number of previous cycles Integer >=1 and <= 8 Works in conjunction with cycle length. The number of cycles to use for setting a historical norm, or baseline. For example, if your cycle length is 1w, this value specifies how many prior weeks you want to use when computing a historical norm. To consider last week the norm, use the value 1; to consider the mean of the last 4 weeks the norm, use the value 4. Higher values mean more data is used to define the baseline.
Trigger threshold and Clear threshold (when Normal based on is Mean plus standard deviation) Number >= 0; Clear threshold must be lower than Trigger threshold

The number of standard deviations away from the norm required to trigger or clear an alert.

For example, a trigger value of 3.5 will trigger an alert when the values being compared differ by 3.5 standard deviations or more. Higher values result in lower sensitivity and potentially fewer alerts.

A clear value of 2.5 will clear the alert when the values being compared differ by 2.5 standard deviations or less. Higher values result in alerts taking longer to clear.

Trigger threshold and Clear threshold (when Normal based on is Mean plus percentage change) Number between 0 and 100, inclusive; Clear threshold must be lower than Trigger threshold.

The percentage change required to trigger or clear the alert.

For example, a trigger value of 30 will trigger an alert when the values being compared differ by 30% or more. Higher values result in lower sensitivity and potentially fewer alerts.

A clear value of 20 will clear the alert when the values being compared differ by 20% or less. Higher values result in alerts taking longer to clear.

Ignore historical extremes Yes, No

Only relevant when Number of previous cycles is greater than or equal to 3.

When Normal based on is Mean plus percentage change, Yes takes the median of the historical baselines; No takes their mean.

When Normal based on is Mean plus standard deviation). Yes excludes the cycles with largest and smallest mean; No includes them

In general, Yes is recommended; if there was an incident last week, for example, excluding the associated data from the threshold calculation provides a more accurate representation of “normal” behavior against which to measure the signal.

Further reading

PARAMETER(S) REMARK(S)
Cycle length and Current window Both parameters should be siginifcantly larger than data resolution (in general by a lot).
Current window and data resolution If the ratio of current window to data resolution is small, the rolling standard deviation may be small. In that situation, using Mean plus percentage change may lead to better results.
Signal The alert condition applies a rolling mean plus standard deviation to the signal, and this may interact poorly with other transformations applied to the signal (e.g. can cause double counting or small standard deviations).