Docs/specs/ZBXNEXT-1782

Support of new trigger operators: <=, >=, <> and 'not'

ZBXNEXT-1782

Status: v1.3

Owner: Alexei, Sasha

Summary

Currently logical operators supported by trigger expressions are limited to =, #, < and > only. It should be extended to support new operators like more or equal, less or equal, not and a new syntax for #, | and &. The new syntax will make Zabbix expressions easier to read and understand for not-so-technical people.

Also the new syntax will be similar to one used for new LLD filters.

Details

New logical operators will be introduced: <=, >=, <>, and, or and not. Existing #, |, and & will be removed.

Definition of the operators

 <=  less or equal
 >=  more or equal
 <>  not equal
 and logical AND
 or  logical OR
 not logical not, 'not' A is evaluated as 0 (false) if A is not equal to 0, i.e. (A>0.000001 | A<-0.000001).

New operator precedence:

1. - (unary)
2. not
3. / *
4. + -
5. < <= > >=
6. = <>
7. and
8. or

The operators are case sensitive, And, AND, OR, Or - are incorrect.

In contrary of existing implementation, all operators will have left-to-right associativity except unary - and not.

Operators not, and and or must be surrounded by spaces or parentheses. For example, in pseudo-syntax: not A, A and B, A or B, (A or C)and(not(A and B).

API and front-end changes

• New operators should be supported by validator of trigger expressions
• The validator should also support \r, \n and tab characters same way as spaces.
  • The exploded trigger expression on the Monitoring->Triggers, Configuration->Triggers and Event details page must display new lines and tabs
• Existing labels OR, AND, AND/OR should be renamed to 'Or', 'And' and 'And/Or' respectively everywhere in the front-end: configuration of actions, trigger constructor, log wizard.

Existing older labels #, & and | should be updated in:

• Configuration of actions (tab 'Condition')
• Trigger condition popup
• Trigger form: insert macro popup menu
• Trigger expression constructor in the trigger configuration form

Trigger expression constructor

• The constructor will not support the ">=" and "<=" operators. When opening an expression that contains one of these operators, the operator will be substituted for "=".
• The constructor will not support the "not" operator: it will be treated as a literal part of an expression.
• The "Insert macro" button will be renamed to "Insert expression". The menu will contain two elements: "Trigger status "OK"" and "Trigger status "Problem"" which will insert "{TRIGGER.VALUE}=0" and "{TRIGGER.VALUE}=1" expressions respectfully.

Regexp trigger expression constructor

• The trigger expression constructor in the item list will support the "not" operator when parsing an existing expression.

Server side changes

• New operators should be supported when evaluating trigger expressions
  • The validator should also support \n, \r and tab characters same way as spaces
• New syntax should be applied also for calculated items

Automatic database upgrade

• The upgrade procedure should convert older trigger operators # | & to new syntax
• Syntax of calculated items should be updated as well
• Extra spaces will be removed and new spaces will be added around operators, for example,

 'a|b'     => 'a or b'
 'a |   b' => 'a or b'

• If new trigger expression exceeds DB field size, a warning message will be written to the log file and trigger expression will not be converted.

XML import/export

• XML import will automatically convert # | & to new syntax only for XML files of older Zabbix versions.
• Extra spaces will be removed the same way as in upgrade patches.

Templates

• Existing templates should be modified to use new syntax

Test cases

• Existing test cases should be extended to include new operators

A few examples

Example 1

• Old syntax: {host:key.min(5m)}>10 | {host:key.min(30m)}>8
• New syntax: {host:key.min(5m)}>10 or {host:key.min(30m)}>8

Example 2

• Old syntax: {host:key.last(0)}#10 & {host:key.last(0)}>3
• New syntax: {host:key.last(0)}<>10 and {host:key.last(0)}>3

Example 3

• Old syntax: {host:key.last(0)}#0
• New syntax: {host:key.last(0)}<>0, also possible 'not {host:key.last(0)}'

Example 4 (calculated item)

• Old syntax: min("host:key", 30)#0 & max("host:key", 30)>5
• New syntax: min("host:key", 30)<>0 and max("host:key", 30)>5

Documentation

What's new in 2.4 Zabbix Manual

• Supported operators
• Examples of trigger expressions with new operators, updated existing examples that use # | &
• Document that operators # & | are no longer supported, users should use new operators instead
• New operator associativity
• New operator precedence
• New syntax for calculated items
• Document that DB upgrade may end up with triggers having the same expression, for example, both 'a|b' and 'a| b' will be converted to 'a or b'.

API docs

• Not equal operator label in https://www.zabbix.com/documentation/2.2/manual/api/reference/action/object#action_operation_condition

Decisions made

• Decided not to make # | & deprecated, removed immediately. If we supported both operators it is not clear how to handle import of older templates because trigger uniqueness criteria is based on trigger expressions.

ChangeLog

• v1.1
  • trigger expressions must support "\r"
  • The exploded trigger expression on the Monitoring->Triggers, Configuration->Triggers and Event details page must display new lines and tabs
• v1.2
  • decreased "not" operator precedence
  • allowed to use parentheses around "not", "or" and "and" operators instead of spaces
• v1.3
  • added changes to the expression constructor menu