Zabbix Documentation 2.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

manual:config:macros:usermacros [2016/12/15 08:00]
manual:config:macros:usermacros [2015/05/05 07:56] (current)
asaveljevs [Example 1] fixed net.tcp.service item key
Line 1: Line 1:
 +==== - User macros ====
  
 +=== 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}**. ​
 +
 +The macros can be used in:
 +
 +  * item names
 +  * item key parameters ​
 +  * trigger names
 +  * 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 substitutes 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
 +  - ...
 +  - 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 substituted.
 +
 +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>​
 +
 +**Most common use cases of global and host macros:**
 +
 +  - taking advantage of templates with host specific attributes: passwords, port numbers, file names, regular expressions,​ etc
 +  - global macros for global one-click configuration changes and fine tuning
 +
 +=== 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(0)}>​{$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 expand if referencing a parameter or constant. They will NOT expand if referencing the host, item key, function, operator or another trigger expression.</​note>​