See www.zabbix.com for the official Zabbix site.

Docs/specs/ZBXNEXT-922

From Zabbix.org
Jump to: navigation, search

Forecasting trigger functions

ZBXNEXT-922

Status: v1.0

Owner: Glebs Ivanovskis

Summary

Currently Zabbix can react on events that have already happened. A set of trigger functions should be added which would predict the future behaviour of the monitored system based on historic data. This will enable users to act before potential unwanted situations actually happen.

Specification

Zabbix server should be able to perform statistical analysis of historical data to predict future values of monitored items.

Function
Description Parameters Comments
forecast (sec|#num,<time_shift>,time,<fit>,<mode>)
Future value, max, min, delta or avg of the item. Value corresponds to now + time. Max, min, delta and avg are on interval between now and now + time. sec or #num - evaluation period in seconds or in latest collected values (preceded by a hash mark)

time_shift (optional) - evaluation period is moved the number of seconds back in time

time - forecasting horizon in seconds

fit (optional) - function used to fit historical data, default is linear, other options are polynomialN (1 <= N <= 6 - degree of polynomial), exponential, logarithmic, power

mode (optional) - demanded output, default is value, other options are max, min, delta, avg

Supported value types: float, int

If value to return is larger than 999999999999.9999 or less than -999999999999.9999, return value is cropped to 999999999999.9999 or -999999999999.9999 correspondingly

Becomes not supported if only misused in expression (wrong item type, invalid parameters) otherwise returns -1 in case of errors

timeleft (sec|#num,<time_shift>,threshold,<fit>)
Time in seconds needed for an item to reach a specified threshold sec or #num - evaluation period in seconds or in latest collected values (preceded by a hash mark)

time_shift (optional) - evaluation period is moved the number of seconds back in time

threshold - value to reach

fit (optional) - function used to fit historical data, default is linear, other options are polynomialN (1 <= N <= 6 - degree of polynomial), exponential, logarithmic, power

Supported value types: float, int

If value to return is larger than 999999999999.9999, return value is cropped to 999999999999.9999

Returns 999999999999.9999 if threshold cannot be reached

Becomes not supported if only misused in expression (wrong item type, invalid parameters) otherwise returns -1 in case of errors

Details

Both functions will always return float even if input values are integer.

Errors may arise in such situations:

  • specified evaluation period contains no data;
  • result of mathematical operation is not defined;
  • numerical complications (unfortunately, for some sets of input data range and precision of double-precision floating-point format become insufficient).

No warnings or errors are flagged if chosen fit poorly describes provided data or there is just too few data for accurate prediction.

Polynomial degree can be from 1 to 6, polynomial1 is equivalent to linear. However, use higher degree polynomials with caution (More info here). If the evaluation period contains less points than needed to determine polynomial coefficients, polynomial degree will be lowered (e.g polynomial5 is requested, but there are only 4 points, therefore polynomial3 will be fitted).

To avoid calculations with huge numbers we consider the timestamp of the first value in specified period plus 1 ns as a new zero-time (current epoch time is of order 1e9, epoch squared is 1e18, double precision is about 1e-16). 1 ns is added to provide all positive time values for logarithmic and power fits which involve calculating log(t). Time shift does not affect linear, polynomial, exponential (apart from easier and more precise calculations) but changes the shape of logarithmic and power functions. Therefore one would possibly want to provide zero-time explicitly. If so, such functionality may be added later.

Mathematical background

Let x is a value of item at time moment t. From mathematical point of view linear regression method can be easily generalised to perform linear, polynomial, exponential, logarithmic and power fitting. Used mathematical expression, dependent variable, list of independent variables and corresponding model coefficients for every fitting method are summarized in the table below.

fit expression dependent variable independent variables model coefficients
linear x = a + b*t x [1; t] [a; b]
polynomial x = a_0 + a_1*t + a_2*t^2 + ... + a_n*t^n x [1; t; t^2; ...; t^n] [a_0; a_1; ...; a_n]
exponential x = a*exp(b*t) log(x) [1; t] [log(a); b]
logarithmic x = a + b*log(t) x [1; log(t)] [a; b]
power x = a*t^b log(x) [1; log(t)] [log(a); b]

The dependent variable approximation can be then calculated simply as scalar multiplication of independent variable vector and model coefficient vector. Least squares method can then be used to find best model coefficients. Model coefficient vector a is given by a simple matrix formula a = inverse(transpose(T)*T)*transpose(T)*x, where T is a matrix, each row of which is a list of independent variables calculated for a time moment t_i. Total number of operations needed is n^2*m + n*m + n^3 + n^2, where m is number of data points provided and n is independent variable count for a given fit.

Once model coefficients have been determined and functional form x = f(t) is known one can find out necessary return value.

Function forecast should return:

mode return value
value f(now + time)
max max_{now <= t <= now + time} f(t)
min min_{now <= t <= now + time} f(t)
delta max - min
avg integral_{now}^{now + time} f(t)dt / time

Function timeleft should solve equation f(t) - threshold = 0 and return the root which is closer to now within now and now + time or -1 there is no such root.

For linear, exponential, logarithmic and power fits all necessary calculations can be written explicitly. For polynomial only value can be calculated without any additional steps. Calculating avg involves computing polynomial antiderivative (analytically). Computing max, min and delta involves computing polynomial derivative (analytically) and finding its roots (numerically). Solving f(t) = 0 involves finding polynomial roots (numerically).

API changes

No

Frontend changes

Create trigger popup should include new trigger functions. Parameter validation should be added.

Translation strings

  • Fit
  • Threshold
  • Forecast for next t seconds based on period T is < N
  • Forecast for next t seconds based on period T is = N
  • Forecast for next t seconds based on period T is > N
  • Forecast for next t seconds based on period T is NOT N
  • Time to reach threshold estimated based on period T is < N
  • Time to reach threshold estimated based on period T is = N
  • Time to reach threshold estimated based on period T is > N
  • Time to reach threshold estimated based on period T is NOT N

Database changes

No

Documentation

Add description of new trigger functions and their parameters, provide examples.

HowTo

ChangeLog

  • v1.0 added more detailed description of function behaviour (becoming not supported vs. returning error code)