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

Docs/specs/ZBXNEXT-2683

From Zabbix.org
Jump to: navigation, search

Context specific user macros

ZBXNEXT-2683

Status: v1.2

Owner: Andris Zeila

Summary

Adding context to user macros allows to override the default macro value by a context specific one. If there are no values defined for the specified macro context then macro will evaluate to its default value (the one defined for the same macro without context).

The common use case would be using LLD macro value as a user macro context. For example a trigger prototype could be defined for mounted file system discovery to use different low space limit depending on mount points or file system types.

The user macro context must be supported in all places the user macros are supported.

Specification

Macro syntax

Macro name should support an optional context value: {$<MACRO>:<context>}

<MACRO> - the macro name according to the current Zabbix user macro naming syntax.

<context> - a text value, quoted with " if context contains } characters or starts with " character. Quotes inside quoted macros must be escaped with \ character. The \ character itself is not escaped, which means it's impossible to have quoted macro ending with \ character - the macro {$MACRO:"a:\b\c\"} is invalid.

For example: {$LOW_SPACE_LIMIT:/dev/tmp}

Macro comparison must be done after unquoting the context. This means that macros {$MACRO:context}, {$MACRO:"context"}, {$MACRO: "context" } are the same.

When entering macros in frontend they must be checked for uniqueness after unquoting their contexts.

Only discovery macros are supported in macro context. Any other macros are ignored and treated as a text value.

When extracting unquoted macro context leading spaces are trimmed but trailing are not. {$MACRO:A} is the same as {$MACRO: A}, but not {$MACRO:A }.

When extracting quoted macro context all spaces before leading quotes and after trailing quotes are trimmed, but all spaces inside quotes are left as they were. Macros {$MACRO:"A"}, {$MACRO: "A"}, {$MACRO:"A" } and {$MACRO: "A" } are the same, but macros {$MACRO:"A"} and {$MACRO:" A "} are not.

It is possible to define empty context: {$MACRO:} which is not the same as macro without a context {$MACRO}.

In item keys the context specific macros are quoted if necessary. For example

  • key[{$MACRO:value: "}]
  • key[{$MACRO:"{#MACRO}"}]
  • key["{$MACRO:\"{#MACRO},1\"}"]

Macro storage

The context specific macros are stored together with normal macros in globalmacro and hostmacro tables as they are - by embedding the context value into macro name. For example:

mysql> select * from globalmacro;
+---------------+--------------------+-------+
| globalmacroid | macro              | value |
+---------------+--------------------+-------+
|           200 | {$LOW_SPACE}       | 30    |
|           201 | {$LOW_SPACE:/tmp}  | 5     |
|           202 | {$LOW_SPACE:/home} | 10    |
+---------------+--------------------+-------+

Macro evaluation

First evaluate the macro with its context. If the macro with specified context is not found in host or linked templates, and it is not a global macro, then the base macro without context is evaluated.

For example if the following user macros are defined:

Macro Value
{$LOW_SPACE_LIMIT} 10
{$LOW_SPACE_LIMIT:/var} 20
{$LOW_SPACE_LIMIT:/var/tmp} 30

then those macros would evaluate as follows:

Macro Value
{$LOW_SPACE_LIMIT} 10
{$LOW_SPACE_LIMIT:/var} 20
{$LOW_SPACE_LIMIT:“/var/logs”} 10
{$LOW_SPACE_LIMIT: “/var/tmp” } 30
{$LOW_SPACE_LIMIT: /var/tmp/misc} 10

Database changes

The macro field size in globalmacro and hostmacro tables must be extended from 64 to 255.

Server changes

  • User macro parsing must support the optional context
  • User macro evaluation must expand the default macro if context specific macro value was not found.
  • LLD macros must be properly expanded in user macro contexts, adding quoting/escaping if necessary.

Frontend changes

  • Users should be able to enter lowercase characters in macro name field when editing global/host macros. Upon losing focus the macro name (without context) should be automatically converted to upercase if necessary.
  • User macro validation must support the optional context.
  • User macro parsing must support the optional context
  • User macro evaluation must expand the default macro if context specific macro value was not found.

API and XML changes

  • User macro parsing must support the optional context
  • User macro evaluation must expand the default macro if context specific macro value was not found.
  • User macro should support utf-8 characters in context

Also discussed

  • It has been decided to evaluate macro with its context on host-template-global level first, if not found - without context on host-template-global level again. Another option was evaluating first on host with/without the context, then repeat that on the template and global level. If convincing use cases are found, an option to choose the priority could be considered in the future.

Documentation


ChangeLog

  • 1.1 Changed macro parameter syntax
  • 1.2 Renamed user macro parameter to user macro context and parameterized macro to context specific macro