Documentation
Table of Contents
FIXME This page is not fully translated, yet. Please help completing the translation.
(remove this paragraph once the translation is finished)
4 History functions
All functions listed here are supported in:
Some general notes on function parameters:
- Function parameters are separated by a comma
- Optional function parameters (or parameter parts) are indicated by
<> /host/keyis a common mandatory first parameter for the functions referencing the host item history/host/keyandtime period:time shiftparameters must never be quoted- Function-specific parameters are described with each function
| FUNCTION | |||
|---|---|---|---|
| Description | Function-specific parameters | Comments | |
| change (/host/key) | |||
| The amount of difference between the previous and latest value. | Supported value types: float, int, str, text, log For strings returns: 0 - values are equal 1 - values differ Example: => change(/host/key)>10 Numeric difference will be calculated, as seen with these incoming example values ('previous' and 'latest' value = difference): '1' and '5' = +4'3' and '1' = -2'0' and '-2.5' = -2.5See also: abs for comparison |
||
| count (/host/key,time period<:time shift>,<operator>,<pattern>) | |||
| Number of values within the defined evaluation period. | time period - maximum evaluation period1 in seconds (time suffixes can be used) or in latest collected values (if preceded by a hash mark) Time shift (optional) allows to move the evaluation point back in time. operator (optional; must be double-quoted) Supported operators:eq - equal (default) ne - not equal gt - greater ge - greater or equal lt - less le - less or equal like - matches if contains pattern (case-sensitive) bitand - bitwise AND regexp - case-sensitive match of the regular expression given in patterniregexp - case-insensitive match of the regular expression given in patternpattern (optional) - required pattern (string arguments must be double-quoted) |
Supported value types: float, integer, string, text, log Float items match with the precision of 2.22e-16 (since Zabbix 5.4.1); before that or if database is not upgraded the precision is 0.000001. With bitand as the third parameter, the fourth pattern parameter can be specified as two numbers, separated by '/': number_to_compare_with/mask. count() calculates "bitwise AND" from the value and the mask and compares the result to number_to_compare_with. If the result of "bitwise AND" is equal to number_to_compare_with, the value is counted.If number_to_compare_with and mask are equal, only the mask need be specified (without '/'). With regexp or iregexp as the third parameter, the fourth pattern parameter can be an ordinary or global (starting with '@') regular expression. In case of global regular expressions case sensitivity is inherited from global regular expression settings. For the purpose of regexp matching, float values will always be represented with 4 decimal digits after '.'. Also note that for large numbers difference in decimal (stored in database) and binary (used by Zabbix server) representation may affect the 4th decimal digit.Examples: => count(/host/key,10m) → number of values for the last 10 minutes1 => count(/host/key,10m,"like","error") → number of values for the last 10 minutes that contain 'error' => count(/host/key,10m,,12) → number of values for the last 10 minutes that equal '12' => count(/host/key,10m,"gt",12) → number of values for the last 10 minutes that are over '12' => count(/host/key,#10,"gt",12) → number of values within the last 10 values that are over '12' => count(/host/key,10m:now-1d,"gt",12) → number of values for the preceding 10 minutes up to 24 hours ago that were over '12' => count(/host/key,10m,"bitand","6/7") → number of values for the last 10 minutes having '110' (in binary) in the 3 least significant bits. => count(/host/key,10m:now-1d) → number of values for the preceding 10 minutes up to 24 hours ago |
|
| countunique (/host/key,time period<:time shift>,<operator>,<pattern>) | |||
| Number of unique values within the defined evaluation period. | time period - maximum evaluation period1 in seconds (time suffixes can be used) or in latest collected values (if preceded by a hash mark) Time shift (optional) allows to move the evaluation point back in time. operator (optional; must be double-quoted) Supported operators:eq - equal (default) ne - not equal gt - greater ge - greater or equal lt - less le - less or equal like - matches if contains pattern (case-sensitive) bitand - bitwise AND regexp - case-sensitive match of the regular expression given in patterniregexp - case-insensitive match of the regular expression given in patternpattern (optional) - required pattern (string arguments must be double-quoted) |
Supported value types: float, integer, string, text, log Float items match with the precision of 2.22e-16 (since Zabbix 5.4.1); before that or if database is not upgraded the precision is 0.000001. With bitand as the third parameter, the fourth pattern parameter can be specified as two numbers, separated by '/': number_to_compare_with/mask. count() calculates "bitwise AND" from the value and the mask and compares the result to number_to_compare_with. If the result of "bitwise AND" is equal to number_to_compare_with, the value is counted.If number_to_compare_with and mask are equal, only the mask need be specified (without '/'). With regexp or iregexp as the third parameter, the fourth pattern parameter can be an ordinary or global (starting with '@') regular expression. In case of global regular expressions case sensitivity is inherited from global regular expression settings. For the purpose of regexp matching, float values will always be represented with 4 decimal digits after '.'. Also note that for large numbers difference in decimal (stored in database) and binary (used by Zabbix server) representation may affect the 4th decimal digit.Examples: => countunique(/host/key,10m) → number of unique values for the last 10 minutes1 => countunique(/host/key,10m,"like","error") → number of unique values for the last 10 minutes that contain 'error' => countunique(/host/key,10m,"gt",12) → number of unique values for the last 10 minutes that are over '12' => countunique(/host/key,#10,"gt",12) → number of unique values within the last 10 values that are over '12' => countunique(/host/key,10m:now-1d,"gt",12) → number of unique values for the preceding 10 minutes up to 24 hours ago that were over '12' => countunique(/host/key,10m,"bitand","6/7") → number of unique values for the last 10 minutes having '110' (in binary) in the 3 least significant bits. => countunique(/host/key,10m:now-1d) → number of unique values for the preceding 10 minutes up to 24 hours ago |
|
| find (/host/key,<time period<:time shift>>,<operator>,<pattern>) | |||
| Find a value match. | time period - (optional) maximum evaluation period1 in seconds (time suffixes can be used) or in latest collected values (if preceded by a hash mark); defaults to the latest value if not specified Time shift (optional) allows to move the evaluation point back in time. operator (optional; must be double-quoted) Supported operators:eq - equal (default) ne - not equal gt - greater ge - greater or equal lt - less le - less or equal like - value contains the string given in pattern (case-sensitive)bitand - bitwise AND regexp - case-sensitive match of the regular expression given in patterniregexp - case-insensitive match of the regular expression given in patternpattern - required pattern (string arguments must be double-quoted); Perl Compatible Regular Expression (PCRE) regular expression if operator is regexp, iregexp. |
Supported value types: float, int, str, text, log Returns: 1 - found 0 - otherwise If more than one value is processed, '1' is returned if there is at least one matching value. With regexp or iregexp as the third parameter, the fourth pattern parameter can be an ordinary or global (starting with '@') regular expression. In case of global regular expressions case sensitivity is inherited from global regular expression settings.Example: => find(/host/key,10m,"like","error") → find a value that contains 'error' within the last 10 minutes |
|
| first (/host/key,time period<:time shift>) | |||
| The first (the oldest) value within the defined evaluation period. | time period - maximum evaluation period1 in seconds (time suffixes can be used) Time shift (optional) allows to move the evaluation point back in time. |
Supported value types: float, int, str, text, log Example: => first(/host/key,1h) → retrieve the oldest value within the last hour See also last(). |
|
| fuzzytime (/host/key,time period) | |||
| Checking how much the passive agent time differs from the Zabbix server/proxy time. | time period - evaluation period in seconds (time suffixes can be used) | Supported value types: float, int Returns: 1 - difference between the passive item value (as timestamp) and Zabbix server/proxy timestamp is less than or equal to T seconds 0 - otherwise Usually used with the 'system.localtime' item to check that local time is in sync with the local time of Zabbix server. Note that 'system.localtime' must be configured as a passive check. Can be used also with vfs.file.time[/path/file,modify] key to check that file didn't get updates for long time. Example: => fuzzytime(/host/key,60)=0 → detect a problem if the time difference is over 60 seconds This function is not recommended for use in complex trigger expressions (with multiple items involved), because it may cause unexpected results (time difference will be measured with the most recent metric), e.g. in fuzzytime(/Host/system.localtime,60)=0 or last(/Host/trap)<>0 |
|
| last (/host/key,<time period<:time shift>>) | |||
| The most recent value. | time period (optional) - the Nth most recent value Time shift (optional) allows to move the evaluation point back in time. |
Supported value types: float, int, str, text, log Take note that a hash-tagged time period (#N) works differently here than with many other functions. For example: last() is always equal to last(#1) last(#3) - third most recent value (not three latest values) Zabbix does not guarantee the exact order of values if more than two values exist within one second in history. Example: => last(/host/key) → retrieve the last value => last(/host/key,#2) → retrieve the previous value => last(/host/key,#1) <> last(/host/key,#2) → the last and previous values differ See also first(). |
|
| logeventid (/host/key,<time period<:time shift>>,<pattern>) | |||
| Checking if event ID of the last log entry matches a regular expression. | time period (optional) - the Nth most recent value Time shift (optional) allows to move the evaluation point back in time. pattern (optional) - regular expression describing the required pattern, Perl Compatible Regular Expression (PCRE) style (string arguments must be double-quoted). |
Supported value types: log Returns: 0 - does not match 1 - matches |
|
| logseverity (/host/key,<time period<:time shift>>) | |||
| Log severity of the last log entry. | time period (optional) - the Nth most recent value Time shift (optional) allows to move the evaluation point back in time. |
Supported value types: log Returns: 0 - default severity N - severity (integer, useful for Windows event logs: 1 - Information, 2 - Warning, 4 - Error, 7 - Failure Audit, 8 - Success Audit, 9 - Critical, 10 - Verbose). Zabbix takes log severity from Information field of Windows event log. |
|
| logsource (/host/key,<time period<:time shift>>,<pattern>) | |||
| Checking if log source of the last log entry matches a regular expression. | time period (optional) - the Nth most recent value Time shift (optional) allows to move the evaluation point back in time. pattern (optional) - regular expression describing the required pattern, Perl Compatible Regular Expression (PCRE) style (string arguments must be double-quoted). |
Supported value types: log Returns: 0 - does not match 1 - matches Normally used for Windows event logs. For example, logsource("VMware Server"). |
|
| nodata (/host/key,time period,<mode>) | |||
| Checking for no data received. | time period - evaluation period in seconds (time suffixes can be used). The period should not be less than 30 seconds because the history syncer process calculates this function only every 30 seconds. nodata(0) is disallowed. mode - if set to strict (double-quoted), this function will be insensitive to proxy availability (see comments for details). |
All value types are supported. Returns: 1 - if no data received during the defined period of time 0 - otherwise Since Zabbix 5.0, the 'nodata' triggers monitored by proxy are, by default, sensitive to proxy availability - if proxy becomes unavailable, the 'nodata' triggers will not fire immediately after a restored connection, but will skip the data for the delayed period. Note that for passive proxies suppression is activated if connection is restored more than 15 seconds and no less than 2 & ProxyUpdateFrequency seconds later. For active proxies suppression is activated if connection is restored more than 15 seconds later. To turn off sensitiveness to proxy availability, use the third parameter, e.g.: nodata(/host/key,5m,"strict"); in this case the function will work the same as before 5.0.0 and fire as soon as the evaluation period (five minutes) without data has past. Note that this function will display an error if, within the period of the 1st parameter: - there's no data and Zabbix server was restarted - there's no data and maintenance was completed - there's no data and the item was added or re-enabled Errors are displayed in the Info column in trigger configuration. This function may not work properly if there are time differences between Zabbix server, proxy and agent. See also: Time synchronization requirement. |
|
| percentile (/host/key,time period<:time shift>,percentage) | |||
| P-th percentile of a period, where P (percentage) is specified by the third parameter. | time period - maximum evaluation period1 in seconds (time suffixes can be used) or in latest collected values (if preceded by a hash mark) Time shift (optional) allows to move the evaluation point back in time. percentage - a floating-point number between 0 and 100 (inclusive) with up to 4 digits after the decimal point |
Supported value types: float, int | |
| trendavg (/host/key,time period:time shift) | |||
| Average of trend values within the defined time period. | time period - the time period (minimum '1h'), defined as <N><time unit> whereN - number of time unitstime unit - h (hour), d (day), w (week), M (month) or y (year).Time shift - the time period offset (see examples) |
Examples: => trendavg(/host/key,1h:now/h) → average for the previous hour (e.g. 12:00-13:00) => trendavg(/host/key,1h:now/h-1h) → average for two hours ago (11:00-12:00) => trendavg(/host/key,1h:now/h-2h) → average for three hours ago (10:00-11:00) => trendavg(/host/key,1M:now/M-1y) → average for the previous month a year ago |
|
| trendcount (/host/key,time period:time shift) | |||
| Number of successfully retrieved trend values within the defined time period. | time period - the time period (minimum '1h'), defined as <N><time unit> whereN - number of time unitstime unit - h (hour), d (day), w (week), M (month) or y (year).Time shift - the time period offset (see examples) |
Examples: => trendcount(/host/key,1h:now/h) → count for the previous hour (e.g. 12:00-13:00) => trendcount(/host/key,1h:now/h-1h) → count for two hours ago (11:00-12:00) => trendcount(/host/key,1h:now/h-2h) → count for three hours ago (10:00-11:00) => trendcount(/host/key,1M:now/M-1y) → count for the previous month a year ago |
|
| trendmax (/host/key,time period:time shift) | |||
| The maximum in trend values within the defined time period. | time period - the time period (minimum '1h'), defined as <N><time unit> whereN - number of time unitstime unit - h (hour), d (day), w (week), M (month) or y (year).Time shift - the time period offset (see examples) |
Examples: => trendmax(/host/key,1h:now/h) → maximum for the previous hour (e.g. 12:00-13:00) => trendmax(/host/key,1h:now/h) - trendmin(/host/key,1h:now/h) → calculate the difference between the maximum and minimum values (trend delta) for the previous hour (12:00-13:00) => trendmax(/host/key,1h:now/h-1h) → maximum for two hours ago (11:00-12:00) => trendmax(/host/key,1h:now/h-2h) → maximum for three hours ago (10:00-11:00) => trendmax(/host/key,1M:now/M-1y) → maximum for the previous month a year ago |
|
| trendmin (/host/key,time period:time shift) | |||
| The minimum in trend values within the defined time period. | time period - the time period (minimum '1h'), defined as <N><time unit> whereN - number of time unitstime unit - h (hour), d (day), w (week), M (month) or y (year).Time shift - the time period offset (see examples) |
Examples: => trendmin(/host/key,1h:now/h) → minimum for the previous hour (e.g. 12:00-13:00) => trendmax(/host/key,1h:now/h) - trendmin(/host/key,1h:now/h) → calculate the difference between the maximum and minimum values (trend delta) for the previous hour (12:00-13:00) => trendmin(/host/key,1h:now/h-1h) → minimum for two hours ago (11:00-12:00) => trendmin(/host/key,1h:now/h-2h) → minimum for three hours ago (10:00-11:00) => trendmin(/host/key,1M:now/M-1y) → minimum for the previous month a year ago |
|
| trendsum (/host/key,time period:time shift) | |||
| Sum of trend values within the defined time period. | time period - the time period (minimum '1h'), defined as <N><time unit> whereN - number of time unitstime unit - h (hour), d (day), w (week), M (month) or y (year).Time shift - the time period offset (see examples) |
Examples: => trendsum(/host/key,1h:now/h) → sum for the previous hour (e.g. 12:00-13:00) => trendsum(/host/key,1h:now/h-1h) → sum for two hours ago (11:00-12:00) => trendsum(/host/key,1h:now/h-2h) → sum for three hours ago (10:00-11:00) => trendsum(/host/key,1M:now/M-1y) → sum for the previous month a year ago |
|
Footnotes
1 The function is evaluated starting with the first received value (unless the time shift parameter is used), i.e. Zabbix will not wait for all the values of the defined evaluation period before evaluating the function.