3 Trigger expression

Overview

This page describes the trigger expression syntax and evaluation details.

The syntax of a simple expression is:

function(/host/item,time_period)<operator><constant>

In this expression, the first operand (to the left of the operator) is a function with its parameters in parentheses (typically the data item and time period).

The function is used to analyze received data during the set time period, resulting in a calculated value.

This value is then compared to the second operand, using the operator. In this example the second operand is a constant, but it can also be another function.

For example:

min(/Zabbix server/net.if.in[eth0,bytes],5m)>100K

This trigger fires if the number of received bytes on eth0 during the last five minutes was always over 100 kilobytes. In this case the expression is true and a problem is created.

Trigger expressions are extremely flexible. In more complex expressions, a number of functions, operators and constants can be combined.

See also:

• Trigger examples
• Problem detection with triggers (general introduction)

Functions

Functions allow to analyze collected values, for example, calculate the average or find a specific string.

Click on the respective function group to see more details.

Except where stated otherwise, these functions are supported in:

• Trigger expressions
• Calculated items
• Expression macros

Foreach functions are supported only for aggregate calculations.

Typically functions return numeric values for comparison. When returning strings, comparison is possible with the = and <> operators (see Detect non-matching software on different hosts example).

Function parameters

Function parameters allow to specify:

• item key (as /host/key) for functions referencing a host item history
• time period (and other function-specific parameters)
• other expressions

Item key

The referenced item must be in a supported state (except for nodata() function, which is calculated for unsupported items as well).

Omission of the host name in the first parameter (i.e. as in function(//key,parameter,...)) is only supported in certain contexts:

• In the formula of calculated items
• In expression macros, which can be used in:
  • The Event name field
  • Graph name
  • The label of "Host" and "Trigger" map elements

In these contexts, you may also use the {HOST.HOST} macro. {HOST.HOST<1-9>} could be used in the case of the Event name field and the "Trigger" map element to refer to a specific item in the trigger expression. When the host name is omitted or replaced by {HOST.HOST} in these contexts, the reference points to the first item in the trigger expression or to the first item in the graph. Outside of these supported contexts, omitting the host name in trigger expressions will result in an error. See Compare long-term CPU loads example for an illustration of double-slash usage in Event name macros.

Time period

Function-specific parameters are placed after the item key and are separated from the item key by a comma.

Most of numeric functions accept time period as a parameter. It allows to specify the interval we are interested in. It can be specified as time period (30s, 10m, 1h) or as a value range (#5 - for five latest values).

You may use seconds or time suffixes to indicate the time period. Preceded by a hash mark, the parameter has a different meaning:

Parameters with a hash mark have a different meaning with the function last - they denote the Nth previous value, so given the values 30, 70, 20, 60, 50 (from the most recent to the least recent):

• last(/host/key,#2) would return '70'
• last(/host/key,#5) would return '50'

The time period is measured up to "now" - where "now" is the latest recalculation time of the trigger (see Calculation frequency); "now" is not the "now" time of the server.

The time period specifies either:

• To consider all values between "now-time period" and "now" (or, with time shift, between "now-time shift-time period" and "now-time_shift")
• To consider no more than the num count of values from the past, up to "now"
  • If there are 0 available values for the time period or num count specified - then the trigger or calculated item that uses this function becomes unsupported

Note that:

• If only a single function (referencing data history) is used in the trigger, "now" is always the latest received value. For example, if the last value was received an hour ago, the time period will be regarded as up to the latest value an hour ago.
• A new trigger is calculated as soon as the first value is received (history functions); it will be calculated within 30 seconds for date and time and nodata() functions. Thus the trigger will be calculated even though perhaps the set time period (for example, one hour) has not yet passed since the trigger was created. The trigger will also be calculated after the first value, even though the time range was set, for example, to ten latest values.

Time shift

An optional time shift is supported with time or value count as the function parameter. This parameter allows to reference data from a period of time in the past.

Time shift starts with now - specifying the current time, and is followed by +N<time unit> or -N<time unit> - to add or subtract N time units.

For example, avg(/host/key,1h:now-1d) will return the average value for an hour one day ago.

Time shift with absolute time periods

Absolute time periods are supported in the time shift parameter, for example, midnight to midnight for a day, Monday-Sunday for a week, first day-last day of the month for a month.

Time shift for absolute time periods starts with now - specifying the current time, and is followed by any number of time operations: /<time unit> - defines the beginning and end of the time unit, for example, midnight to midnight for a day, +N<time unit> or -N<time unit> - to add or subtract N time units.

Please note that the value of time shift can be greater or equal to 0, while the time period minimum value is 1.

Other expressions

Function parameters may contain other expressions, as in the following syntax:

min(min(/host/key,1h),min(/host2/key2,1h)*10)

Note that other expressions may not be used, if the function references item history. For example, the following syntax is not allowed:

min(/host/key,#5*10)

While other trigger expressions as function parameters are limited to non-history functions in triggers, this limitation does not apply in calculated items.

Operators

The following operators are supported for triggers (in descending priority of execution):

¹ String operand is still cast to numeric if:

• another operand is numeric
• operator other than = or <> is used on an operand

(If the cast fails - numeric operand is cast to a string operand and both operands get compared as strings.)

not, and and or operators are case-sensitive and must be in lowercase. They also must be surrounded by spaces or parentheses.

All operators, except unary - and not, have left-to-right associativity. Unary - and not are non-associative (meaning -(-1) and not (not 1) should be used instead of --1 and not not 1).

Evaluation result:

• <, <=, >, >=, =, <> operators shall yield '1' in the trigger expression if the specified relation is true and '0' if it is false. If at least one operand is Unknown the result is Unknown;
• and for known operands shall yield '1' if both of its operands compare unequal to '0'; otherwise, it yields '0'; for unknown operands and yields '0' only if one operand compares equal to '0'; otherwise, it yields 'Unknown';
• or for known operands shall yield '1' if either of its operands compare unequal to '0'; otherwise, it yields '0'; for unknown operands or yields '1' only if one operand compares unequal to '0'; otherwise, it yields 'Unknown';
• The result of the logical negation operator not for a known operand is '0' if the value of its operand compares unequal to '0'; '1' if the value of its operand compares equal to '0'. For unknown operand not yields 'Unknown'.

Unknown expression state

It is possible that an unknown operand appears in a trigger expression when:

• unsupported item is used
• function evaluation, for a supported item, results in error

In this case the trigger expression generally evaluates to Unknown (as it cannot be evaluated)

It is possible to get notified on unknown triggers.

Exceptions

Despite an unknown operand, trigger expressions can be evaluated to known result (Problem/OK) in some cases:

• The nodata() function is evaluated regardless of whether the referenced item is supported or not.
• Expressions with AND/OR can be evaluated to known result in two cases:
  • Case 1: "1 or some_function(unsupported_item1) or some_function(unsupported_item2) or ..." evaluates to known result ('1' or "Problem"),
  • Case 2: "0 and some_function(unsupported_item1) and some_function(unsupported_item2) and ..." evaluates to known result ('0' or "OK").
• If the function evaluation for a supported item results in error, the function value becomes Unknown and it takes part as unknown operand in further expression evaluation.

Unknown operands may "disappear" only in logical expressions as described above. In arithmetic expressions unknown operands always lead to Unknown (except division by 0).

If a trigger expression with several unsupported items evaluates to Unknown, the error message in the frontend refers to the last unsupported item evaluated.

Value caching

Values required for trigger evaluation are cached by Zabbix server. Because of this trigger evaluation causes a higher database load for some time after the server restarts.

The value cache is not cleared when item history values are removed (either manually or by housekeeper), so the server will use the cached values until they are older than the time periods defined in trigger functions or server is restarted.