Zabbix Documentation 4.2

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
manual:config:macros:usermacros [2016/12/15 08:00]
manual:config:macros:usermacros [2018/10/01 09:42] (current)
Line 1: Line 1:
 +==== 2 User macros ====
  
 +=== Overview ===
 +
 +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. ​
 +
 +User macros can be defined on global, template and host level. These macros have a special syntax: ​
 +
 +  {$MACRO}
 +
 +Zabbix resolves macros according to the following precedence:
 +
 +  - host level macros (checked first)
 +  - 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 third level templates of the host, sorted by template ID, etc.
 +  - global macros (checked last)
 +
 +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 resolved.
 +
 +User macros can be used in:
 +
 +  * 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]]
 +
 +== Common use cases of global and host macros ==
 +
 +  * use a global macro in several locations; then change the macro value and apply configuration changes to all locations with one click
 +  * take advantage of templates with host-specific attributes: passwords, port numbers, file names, regular expressions,​ etc.
 +
 +=== Configuration ===
 +
 +To define user macros, go 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
 +
 +<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>​
 +
 +The following characters are allowed in the macro names: **A-Z** , **0-9** , **_** , **.**
 +
 +=== Examples ===
 +
 +== Example 1 ==
 +
 +Use of host-level macro in the "​Status of SSH daemon"​ item key:
 +
 +''​net.tcp.service[ssh,,​{$SSH_PORT}]''​
 +
 +This item can be assigned to multiple hosts, providing that the value of **{$SSH_PORT}** is defined on those hosts.
 +
 +== Example 2 ==
 +
 +Use of host-level macro in the "CPU load is too high" trigger:
 +
 +''​{ca_001:​system.cpu.load[,​avg1].last()}>​{$MAX_CPULOAD}''​
 +
 +Such a trigger would be created on the template, not edited in individual hosts.
 +
 +<note tip>If you want to use amount of values as the function parameter (for example, **max(#​3)**),​ include hash mark in the macro definition like this: SOME_PERIOD => #​3</​note>​
 +
 +== Example 3 ==
 +
 +Use of two macros in the "CPU load is too high" trigger:
 +
 +''​{ca_001:​system.cpu.load[,​avg1].min({$CPULOAD_PERIOD})}>​{$MAX_CPULOAD}''​
 +
 +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 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 ==
 +
 +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 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.
 +
 +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.
 +
 +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.
 +
 +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. ​