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

Docs/specs/ZBXNEXT-1782

From Zabbix.org
Jump to: navigation, search

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[1], \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

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

References

  1. From HTML spec: "Line breaks are represented as "CR LF" pairs (i.e., `%0D%0A')" http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4