2 用户宏

2 User macros

概述

Overview

除了支持开箱即用的宏之外，Zabbix 还支持更灵活的用户宏。

User macros are supported in Zabbix for greater flexibility, in addition to the macros supported out-of-the-box.

用户宏可以在全局、模板和主机级别进行定义。这些宏具有一个特殊的语法：

User macros can be defined on global, template and host level. These macros have a special syntax:

{$MACRO}
       
       {$MACRO}

Zabbix 根据以下优先级来解析宏：

Zabbix resolves macros according to the following precedence:

1. 主机级别的宏 (首先检查)；
2. 为主机的第一级别模板定义的宏（即直接链接到主机的模板），按照模板 ID 来排序；
3. 为主机的第二级别模板定义的宏，按照模板 ID 来排序；
4. 为主机的第三级别模板定义的宏，按照模板ID来排序等；
5. 全局宏 (最后检查)。

1. host level macros (checked first)
2. macros defined for first level templates of the host (i.e., templates linked directly to the host), sorted by template ID
3. macros defined for second level templates of the host, sorted by template ID
4. macros defined for third level templates of the host, sorted by template ID, etc.
5. global macros (checked last)

换言之，如果一个主机不存在一个宏， Zabbix 将会尝试在级别递增的主机模板中找到它，如果仍然找不到，那么将会使用全局宏（如果全局宏存在的话）。

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.

如果 Zabbix不能找到宏，那么宏将不能被解析。

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)
• many other locations - see the 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

如果要定义用户宏，请转到Zabbix的前端页面的如下位置：

• 对于全局宏，请访问 // 管理 → 常规 → 右上角下拉菜单选择 “宏” //；
• 对于主机和模板级别的宏，请打开主机或模板属性并查看 宏 标签页面。

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>如果在模板的监控项或触发器使用用户宏，建议将该宏添加到模板，即使它被定义在全局级别上。这样的话，将模板导出至XML文件中，之后在其他系统中导入，那么在其他系统中使用也将会达到预期的使用效果。 :::

宏名称中允许使用以下字符：A-Z , 0-9 , _ , .

The following characters are allowed in the macro names: A-Z , 0-9 , _ , .

示例

Examples

示例 1

Example 1

在 "Status of SSH daemon" 监控项键值中使用主机级别的宏：

Use of host-level macro in the "Status of SSH daemon" item key:

net.tcp.service[ssh,,{$SSH_PORT}]

net.tcp.service[ssh,,{$SSH_PORT}]

该监控项可以分配给多个主机，前提是在这些主机上定义了 {$SSH_PORT} 的值。

This item can be assigned to multiple hosts, providing that the value of {$SSH_PORT} is defined on those hosts.

示例 2

Example 2

在 "CPU load is too high" 触发器上使用主机级别的宏:

Use of host-level macro in the "CPU load is too high" trigger:

{ca_001:system.cpu.load[,avg1].last()}>{$MAX_CPULOAD}

{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>如果要使用数值作为函数参数（例如，max(#3)），则在宏定义中要包含井号（hash mark）例如：SOME_PERIOD => #3 :::

示例 3

Example 3

在"CPU load is too high"触发器中使用了两个宏：

Use of two macros in the "CPU load is too high" trigger:

{ca_001:system.cpu.load[,avg1].min({$CPULOAD_PERIOD})}>{$MAX_CPULOAD}

{ca_001:system.cpu.load[,avg1].min({$CPULOAD_PERIOD})}>{$MAX_CPULOAD}

请注意，宏可以用作触发器函数的参数，在这个示例中为 min() 。

Note that a macro can be used as a parameter of trigger function, in this example function min().

<note important>在触发器表达式中，如果引用参数或者常量，则用户宏将会解析。如果引用主机、监控项键值、函数、操作或其他触发器表达式的话，他们将不会解析。 :::

示例 4

Example 4

同步代理不可达情况下的更新间隔项:

Synchronize the agent unavailability condition with the item update interval:

• 定义宏 {$INTERVAL} 并在更新间隔项时间中使用;
• 使用 {$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

{ca_001:agent.ping.nodata({$INTERVAL})}=1

示例 5

Example 5

工作时间集中配置：

Centralize configuration of working hours:

• 创建一个全局宏 {$WORKING_HOURS} 例如 1-5,09:00-18:00;
• 在 Administration → General → Working time 中使用;
• 在 User → Media → When active 中使用;
• 在工作时间设置更多的频度的监控项中使用:

• 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:

• 在动作的条件配置 Time period 中使用;
• 如果需要，在 Administration → General → Macros中调整工作时间。

• 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} 

宏上下文是一个简单的文本值。宏上下文的常见使用案例是使用自动发现宏值作为用户宏上下文。例如，根据文件系统的挂载点或文件系统类型，可以为挂载的文件系统自动发现定义自动发现触发器原型以使用不同的可使用空间阈值。

Macro context is a simple text value. The common use case for macro contexts would be using a low-level discovery 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 item key parameters, except macro context is not parsed as several parameters if there is a , character:

• Macro context must be quoted with " if the context contains a } character or starts with a " character. Quotes inside quoted macros must be escaped with the \ character. The \ character itself is not escaped, which means it's impossible to have a quoted macro ending with the \ character - the macro {$MACRO:"a:\b\c\"} is invalid.
• 宏的内容必须引用'"',如果宏内容包含有'}'的字符或者从一个'"'字符.那在引号中的引号必须使用'\'字符进行转义从而不改变宏的内容,这也说明宏被引用后的字符'"'没有被转义则不能使用,宏 {$MACRO:"a:\b\c\"}是无效的.
• 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 }.
• 宏内容中前面的空格会被忽略,后面的空格不会忽略.例如:{$MACRO:A} 和 {$MACRO: A} 相同, 但不同于 {$MACRO:A }.
• All spaces before leading quotes and after trailing quotes are ignored, but 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.
• 宏变量中引号外面的空格可以被忽略,但是引号里面的空格不会忽略.宏{$MACRO:"A"}, {$MACRO: "A"}, {$MACRO:"A" } 和 {$MACRO: "A" } 相同,但是跟宏{$MACRO:"A"} 和 {$MACRO:" A "} 不同.

• Macro context must be quoted with " if the context contains a } character or starts with a " 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:"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 ignored, but 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.

以下的宏是一样的,因为它们表示的内容一样: {$MACRO:A}, {$MACRO: A} 和 {$MACRO:"A"}. 这与监控项相反, key[a], key[ a] 和 key["a"] 在语法上相同,但唯一性不同。

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.

当宏在使用时,zabbix会查看宏的背景,如果宏没有在主机或者模板上关联,或者有没有在全局宏中定义,那么宏不会被使用。

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 usage example of macro context in a disk space trigger prototype and take limitation clause into consideration.