Baseline

Description

The Baseline function calculates and sets low and high thresholds for a monitor based on data gathered during a learning period after an agent is enabled or restarted.

The calculated thresholds account for typical fluctuations in the data, enabling alerts to be triggered only for conditions exceeding the learned "normal" range. The Baseline function also calculates new thresholds and updates baselines at specified intervals, enabling the monitor to adjust as network conditions change.

Parameters

<monitor>

Specifies the monitor to which the baseline applies.

If the monitored URI contains wildcards, the baseline is calculated against all resources pointed to by expanding the wildcard. The same baseline thresholds apply to all resources.

<title>

Specifies the title to be displayed for this baseline. If specified, the title is displayed in the Web UI as the name of the baseline.

The definition of title must use the Title function.

For example: title=Title("Baseline for CPU utilization")

<algorithm>

Specifies the algorithm to use to calculate the baseline thresholds.

The supported and default algorithm is: MaxAlgorithm

<high-multiplier>

Specifies the high-threshold multiplier to apply to the value calculated by the algorithm.

The algorithm result multiplied by the high-multiplier determines the current high threshold for the monitor.

Typically, the high threshold is used to determine when the rule condition is true and therefore to trigger an alert and execute actions.

Default: 2

<low-multiplier>

Specifies the low-threshold multiplier to apply to the value calculated by the algorithm.

The algorithm result multiplied by the low-multiplier determines the current low threshold for the monitor.

Typically, the low threshold is used to determine when the clear condition is true and therefore to execute clear actions, such as clearing the alert.

Default: 1

<duration>

Specifies amount of time series data required for learning.

The initial learning time is used determine how long to stay in the initial learning state after an agent is enabled. If there is already a time series in the database for the monitored resource, the Baseline function compares the amount of data to the initial learning time and includes that data.

For example, if the initial learning time is one hour and one or more hours of time series data exists in the database, the thresholds are set immediately. If there is 55 minutes of data available, the agent stays in the initial learning state for five minutes. If there is no data available, the baseline stays in the initial learning state for one hour.

During the initial learning state, the baseline function looks at the monitored data and uses its algorithm to determine normal patterns versus anomalies. Unless you specify values for the default_thresholds parameter, the agent does not generate alerts during the initial learning state.

Ensure that the initial learning time is long enough to gather enough data to determine normal versus abnormal patterns.

For example:

• If you are monitoring something that is updated infrequently, a longer initial learning time might be required to obtain enough data.

• If an agent is monitoring network traffic and that agent is enabled during a time that has unusually low traffic, the baseline calculates a low value, and "normal" traffic levels exceed the threshold, creating an alert. By setting a longer duration for the initial learning period, you maximize the ability of the algorithm to make calculations based on typical conditions.

The format for <duration> is <number><unit>, where <unit> is one of the following:

Value	Meaning
s	seconds
m	minutes
h	hours
d	days
w	weeks

Default: 1h

<lthresh> and <hthresh>

Specifies the default low and default high thresholds. These thresholds are used while the baseline is in the initial learning state. Both thresholds must be specified.

If default thresholds are not specified, alerts are not triggered for the monitor while the baseline is in the learning state.

Example

The following example contains a monitor that includes a baseline:

# algorithm for dynamic Threshold calculation
self.alg = MaxAlgorithm(continuous_learning_window="10m")

# rx packets
uri1 = '/rest/v1/system/interfaces/{}?attributes=statistics.rx_packets'
rate_m1 = Rate(uri1, "10 seconds", [self.params['interface_id']])
self.m1 = Monitor(
    rate_m1,
    'Rx Packets (packets per second)')
self.r1 = Rule('Rule for Monitor Interface rx Packets')
title1 = Title("Baseline for Interface rx Packets")
self.baseline1 = Baseline(self.m1, algorithm=self.alg, title=title1,
                          high_threshold_factor=2,
                          low_threshold_factor=1.2,
                          initial_learning_time='1d')
self.r1.condition('{} > {}', [self.m1, self.baseline1])
self.r1.clear_condition('{} < {}', [self.m1, self.baseline1])
self.r1.action("ALERT_LEVEL", AlertLevel.CRITICAL)
self.r1.clear_action("ALERT_LEVEL", AlertLevel.NONE)