Zabbix Documentation 4.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/11 10:29]
asaveljevs [Example 4] correcting LLD macro syntax inside context
manual:config:macros:usermacros [2017/10/06 14:12] (current)
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}**.+User macros are supported in Zabbix for greater flexibility,​ in addition ​to the macros ​[[:manual/​appendix/​macros/​supported_by_location|supported]] out-of-the-box
  
-The macros can be used in:+User macros can be defined on global, template and host level. These macros have a special syntax
  
-  ​* item names +  ​{$MACRO}
-  * item key parameters  +
-  * trigger names and descriptions +
-  * trigger expression parameters and constants (see examples) +
-  * several other [[manual:​appendix:​macros:​supported_by_location#​additional_support_for_user_macros|locations]] +
- +
-The following characters are allowed in the macro names: **A-Z** , **0-9** , **_** , **.**+
  
 Zabbix resolves macros according to the following precedence: Zabbix resolves macros according to the following precedence:
Line 20: Line 14:
   - macros defined for first level templates of the host (i.e., templates linked directly to the host), sorted by template ID   - macros defined for first level templates of the host (i.e., templates linked directly to the host), sorted by template ID
   - macros defined for second level templates of the host, sorted by template ID   - macros defined for second level templates of the host, sorted by template ID
-  - macros defined for third level templates of the host, sorted by template ID +  - macros defined for third level templates of the host, sorted by template ID, etc.
-  - ...+
   - global macros (checked last)   - global macros (checked last)
  
Line 28: Line 21:
 If Zabbix is unable to find a macro, the macro will not be resolved. 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: +User macros ​can be used in:
-  * for global macros, visit //​Administration -> General -> Macros// +
-  * for host and template level macros, open host or template properties and look for the //Macros// tab+
  
-<note tip>If a user macro is used in items or triggers in a template, it is suggested to add that macro to the template even if it is defined on a global level. That way, exporting the template to XML and importing it in another system will still allow it to work as expected.<​/note>+  * item names 
 +  * item key parameters 
 +  * item update intervals ​and flexible intervals 
 +  * trigger names and descriptions 
 +  * trigger expression parameters and constants (see [[#​examples|examples]]) 
 +  * many other locations - see the [[:​manual/​appendix/​macros/supported_by_location_user|full list]]
  
-**Most common ​use cases of global and host macros:**+== Common ​use cases of global and host macros ​==
  
-  ​- taking ​advantage of templates with host specific attributes: passwords, port numbers, file names, regular expressions,​ etc +  ​* use a global macro in several locations; then change the macro value and apply configuration changes to all locations with one click 
-  - global macros for global one-click configuration changes and fine tuning+  * take advantage of templates with host-specific attributes: passwords, port numbers, file names, regular expressions,​ etc.
  
-=== Macro context ​===+=== Configuration ​===
  
-Macro context is a simple text value. The common use case for macro contexts would be using LLD macro value as a user macro context. For examplea trigger prototype could be defined for mounted file system discovery ​to use different low space limit depending on mount points ​or file system types.+To define ​user macrosgo to the corresponding locations in the frontend: 
 +  * for global macros, visit //​Administration -> General -> Macros// 
 +  * for host and template level macros, open host or template properties and look for the //Macros// tab
  
-Only discovery macros are supported ​in macro contextsAny other macros are ignored ​and treated ​as plain text.+<note tip>If a user macro is used in items or triggers in a template, it is suggested to add that macro to the template even if it is defined on a global levelThat way, exporting the template to XML and importing it in another system will still allow it to work as expected.</​note>​
  
-Technically,​ macro context is specified using rules similar to [[manual:​config:​items:​item:​key|item key]] parameters, except macro context is not parsed as several parameters if there is a '',''​ character:​ +The following characters are allowed in the macro names: **A-Z** , **0-9** ​**_** **.**
- +
-  * Macro context is 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. +
-  ​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 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. +
- +
-The following macros are all equivalent, because they have the same context: ''​{$MACRO:​A}'',​ ''​{$MACRO:​ A}''​ and ''​{$MACRO:"​A"​}''​. This is in contrast with item keys, where ''​key[a]'',​ ''​key[ a]''​ and ''​key["​a"​]''​ 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 global macro with context, then the macro without context is searched for. 
 === Examples === === Examples ===
  
Line 85: Line 76:
  
 == Example 4 == == Example 4 ==
-Set the free disk space trigger prototype for a host to: 
  
-''​{ca_001:​vfs.fs.size[{#FSNAME},pfree].last()}<{$LOW_SPACE_LIMIT:{#FSNAME}}''​+Synchronize the agent unavailability condition with the item update interval: 
 + 
 +  * define {$INTERVAL} macro and use it in the item update interval;  
 +  * use {$INTERVAL} as parameter of the agent unavailability trigger: 
 + 
 +''​{ca_001:​agent.ping.nodata({$INTERVAL})}=1''​ 
 + 
 +== Example 5 == 
 + 
 +Centralize configuration of working hours: 
 + 
 +  * create a global {$WORKING_HOURS} macro equal to ''​1-5,09:​00-18:​00'';​ 
 +  * use it in //​Administration//​ -> //General// -> //Working time//; 
 +  * use it in //User// -> //Media// -> //When active//; 
 +  * use it to set up more frequent item polling during working hours: 
 + 
 +{{:​manual:​config:​macros:​usermacro_example5.png|}} 
 + 
 +  * use it in the //Time period// action condition;​ 
 +  * adjust the working time in //​Administration//​ -> //General// -> //Macros//, if needed. 
 + 
 +=== User macro context === 
 + 
 +An optional context can be used in user macros, allowing to override the default value with context-specific one.  
 + 
 +User macros with context have a similar syntax:  
 + 
 +  {$MACRO:​context}  
 + 
 +Macro context is a simple text value. The common use case for macro contexts would be using a low-level discovery [[:​manual/​discovery/​low_level_discovery#​using_lld_macros_in_user_macro_contexts|macro value]as a user macro contextFor 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. 
 + 
 +Only low-level discovery macros are supported in macro contexts. Any other macros are ignored and treated as plain text. 
 + 
 +Technically,​ macro context is specified using rules similar to [[manual:​config:​items:​item:​key|item key]] parameters, except macro context is not parsed as several parameters if there is a '',''​ character:​ 
 + 
 +  * Macro context must be quoted with ''<​nowiki>"</​nowiki>''​ if the context contains a ''​}''​ character or starts with a ''​<nowiki>"</​nowiki>''​ character. Quotes inside quoted context must be escaped with the ''​\''​ character. The ''​\''​ character itself is not escaped, which means it's impossible to have a 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.
  
-Add macros+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.
-  * ''​{$LOW_SPACE_LIMIT}''​ **10** +
-  * ''​{$LOW_SPACE_LIMIT:/​tmp}''​ **50**+
  
-If, for example, the mounted file system discovery discovered filesystems ''/'',​ ''/​home''​ and ''/​tmp'',​ then events will be created when ''/''​ and ''/​home''​ filesystems have 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]] of macro context in a disk space trigger prototype and take limitation clause into consideration