Zabbix Documentation 3.0

2.23.04.04.2 (current)In development:4.4 (devel)Unsupported:1.82.02.43.23.4

User Tools

Site Tools


manual:config:macros:usermacros

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
manual:config:macros:usermacros [2016/01/08 11:41]
wiper macro context description
manual:config:macros:usermacros [2018/08/09 07:26] (current)
martins-v autonumbering removal
Line 1: Line 1:
-==== User macros ====+==== User macros ====
  
 === Overview === === Overview ===
  
-For greater flexibility,​ Zabbix supports user macros, which can be defined on global, template and host level. These macros have a special syntax: **{$MACRO}**. An optional context can be used in user macros, allowing to override default value with context specific one. User macros with context have similar syntax: **{$MACRO:​context}**.+For greater flexibility,​ Zabbix supports user macros, which can be defined on global, template and host level. These macros have a special syntax: **{$MACRO}**. An optional context can be used in user macros, allowing to override default value with context specific one. User macros with context have similar syntax: **{$MACRO:​context}**.
  
 The macros can be used in: The macros can be used in:
Line 15: Line 15:
 The following characters are allowed in the macro names: **A-Z** , **0-9** , **_** , **.** The following characters are allowed in the macro names: **A-Z** , **0-9** , **_** , **.**
  
-Zabbix ​substitutes ​macros according to the following precedence:+Zabbix ​resolves ​macros according to the following precedence:
  
   - host level macros (checked first)   - host level macros (checked first)
Line 26: Line 26:
 In other words, if a macro does not exist for a host, Zabbix will try to find it in the host templates of increasing depth. If still not found, a global macro will be used, if exists. In other words, if a macro does not exist for a host, Zabbix will try to find it in the host templates of increasing depth. If still not found, a global macro will be used, if exists.
  
-If Zabbix is unable to find a macro, the macro will not be substituted.+If Zabbix is unable to find a macro, the macro will not be resolved.
  
 To define user macros, go to the corresponding locations in the frontend: To define user macros, go to the corresponding locations in the frontend:
Line 40: Line 40:
  
 === Macro context === === Macro context ===
-Macro context is a text value, quoted with ''"''​ if context contains ''​}''​ character 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. ​ 
  
-Only discovery macros are supported in macro contexts. Any other macros are ignored and treated ​as a text values+Macro context is a simple text value. The common use case for macro contexts ​would be using an [[:​manual/​discovery/​low_level_discovery#​using_lld_macros_in_user_macro_contexts|LLD macro value]] ​as a user macro context. For example, a trigger prototype could be defined for mounted file system discovery to use a different low space limit depending on the mount points or file system types.
  
-The common use case for macro contexts ​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+Only low-level discovery macros are supported in macro contexts. Any other macros are ignored and treated ​as plain text.
  
-When lookin up a macro with context ​the following ​rules are used: +Technically, ​macro context ​is specified using rules similar to [[manual:config:items:item:key|item key]] parametersexcept macro context is not parsed as several parameters if there is a '','' ​character:
-  * the leading spaces in context are ignored, the trailing spaces are not. For example ''​{$MACRO:A}''​ is the same as ''​{$MACROA}'',​ but not ''​{$MACRO:A }''​. +
-  * all spaces before leading quotes and after trailing quotes are ignoredbut all spaces inside quotes are not. Macros ''​{$MACRO:"​A"​}'',​ ''​{$MACRO"​A"​}'',​ ''​{$MACRO:"​A"​ }''​ and ''​{$MACRO:​ "​A"​ }''​ are the same, but macros ''​{$MACRO:"​A"​}''​ and ''​{$MACRO:"​ A "​}''​ are not. +
  
-When context ​macros are processed the macro with its context ​is evaluated. If macro with this context is not defined by host or linked templatesand it is not defined as global macro with context, then the macro without ​context is evaluated+  * Macro context ​must be quoted ​with ''<​nowiki>"</​nowiki>''​ if the context ​contains ​''​}''​ character or starts ​with a ''<​nowiki>"</​nowiki>''​ character. Quotes inside quoted ​context ​must be escaped with the ''​\''​ character. The ''​\''​ character itself ​is not escapedwhich means it's impossible to have quoted context ending ​with the ''​\''​ character - the macro ''​{$MACRO:<​nowiki>"</​nowiki>​a:​\b\c\<​nowiki>"</​nowiki>​}''​ is invalid. 
 +  * The leading spaces in context ​are ignored, the trailing spaces are not. For example ''​{$MACRO:​A}'' ​is the same as ''​{$MACRO:​ A}'',​ but not ''​{$MACRO:​A }''​. 
 +  * All spaces before leading quotes and after trailing quotes are ignored, but all spaces inside quotes are not. Macros ''​{$MACRO:<​nowiki>"</​nowiki>​A<​nowiki>"</​nowiki>​}'',​ ''​{$MACRO:​ <​nowiki>"</​nowiki>​A<​nowiki>"</​nowiki>​}'',​ ''​{$MACRO:<​nowiki>"</​nowiki>​A<​nowiki>"</​nowiki>​ }''​ and ''​{$MACRO:​ <​nowiki>"</​nowiki>​A<​nowiki>"</​nowiki>​ }''​ are the same, but macros ''​{$MACRO:<​nowiki>"</​nowiki>​A<​nowiki>"</​nowiki>​}''​ and ''​{$MACRO:<​nowiki>"</​nowiki>​ A <​nowiki>"</​nowiki>​}''​ are not.
  
 +The following macros are all equivalent, because they have the same context: ''​{$MACRO:​A}'',​ ''​{$MACRO:​ A}''​ and ''​{$MACRO:<​nowiki>"</​nowiki>​A<​nowiki>"</​nowiki>​}''​. This is in contrast with item keys, where ''​key[a]'',​ ''​key[ a]''​ and ''​key[<​nowiki>"</​nowiki>​a<​nowiki>"</​nowiki>​]''​ are the same semantically,​ but different for uniqueness purposes.
 +
 +When context macros are processed, Zabbix looks up the macro with its context. If a macro with this context is not defined by host or linked templates, and it is not a defined as a global macro with context, then the macro without context is searched for.
 === Examples === === Examples ===
  
Line 80: Line 82:
 Note that a macro can be used as a parameter of trigger function, in this example function **min()**. Note that a macro can be used as a parameter of trigger function, in this example function **min()**.
  
-<note important>​In trigger expressions user macros will expand ​if referencing a parameter or constant. They will NOT expand ​if referencing the host, item key, function, operator or another trigger expression.</​note>​+<note important>​In trigger expressions user macros will resolve ​if referencing a parameter or constant. They will NOT resolve ​if referencing the host, item key, function, operator or another trigger expression.</​note>​
  
 == Example 4 == == Example 4 ==
-Set the free disk space trigger prototype for a host to: 
- 
-''​{Host:​vfs.fs.size[{#​FSNAME},​pfree].last(0)}<​{$LOW_SPACE_LIMIT:#​FSNAME}''​ 
- 
-Add macros: 
-  * ''​{$LOW_SPACE_LIMIT}''​ **10** 
-  * ''​{$LOW_SPACE_LIMIT:/​tmp}''​ **50** 
- 
-If, for example, the mounted file system discovery discovered filesystems ''/''​ and ''/​tmp'',​ then events will be created when ''/''​ filesystem has less than **10**% of free disk space or ''/​tmp''​ filesystem has less than **50**% of free disk space. 
- 
  
 +See [[manual:​discovery:​low_level_discovery#​using_lld_macros_in_user_macro_contexts|usage example]] for disk space trigger prototype and take limitation clause into consideration. ​