This shows you the differences between two versions of the page.
manual:config:macros:usermacros [2015/05/05 07:56] asaveljevs [Example 1] fixed net.tcp.service item key |
manual:config:macros:usermacros [2016/01/08 11:41] |
||
---|---|---|---|
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> |