用户宏

概述

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

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

{$MACRO}

Zabbix 按照以下优先级解析宏：

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

换句话说，如果主机没有定义某个宏，Zabbix 将尝试在主机的模板中按深度递增的顺序查找该宏。如果仍未找到，则在全局宏存在的情况下使用全局宏。

如果同一级别的多个已链接模板中存在名称相同的宏，则使用模板 ID 最低的模板中的宏。因此，在多个模板中使用相同名称的宏存在配置风险。

如果 Zabbix 无法找到某个宏，则不会解析该宏。

在“配置”部分（例如触发器列表）中，宏（包括用户宏）会按设计保持未解析状态，以便更透明地显示复杂配置。

用户宏可以用于：

  • 监控项名称
  • 监控项键参数
  • 监控项更新间隔和灵活间隔
  • 触发器名称和描述
  • 触发器表达式参数和常量（请参阅示例）
  • 许多其他位置 - 请参阅完整列表
全局和宿主宏的常见用例
  • 在多个位置使用全局宏；然后更改宏值并一键将配置更改应用于所有位置
  • 利用具有主机特定属性的模板：密码、端口号、文件名、正则表达式等。

建议使用主机宏而不是全局宏，因为添加、更新或删除全局宏会强制对所有主机进行增量配置更新。有关更多信息，请参见 Passive and active agent checks。

配置

要定义用户宏，请转到前端中的相应位置：

  • 对于全局宏，请访问 Administration > Macros。
  • 对于主机和模板级别的宏，请打开主机或模板属性，并查找 Macros 选项卡。

用户宏具有以下属性：

Parameter Description
Macro 宏名称。名称必须用花括号括起来，并以美元符号开头。
示例：{$FRONTEND_URL}。宏名称中允许使用以下字符：A-Z（仅大写） 、0-9 、_ 、.
Value 宏值。支持三种值类型：
Text（默认）- 纯文本值
Secret text - 值会以星号掩码显示
Vault secret - 值包含指向 vault secret 的路径/查询。

要更改值类型，请单击值输入字段末尾的按钮。

用户宏值的最大长度为 2048 个字符。
Description 用于提供有关此宏更多信息的文本字段。

配置用户宏时，请注意以下与上下文相关的行为：

  • 如果在模板监控项或触发器中使用了用户宏，请考虑将这些宏也添加到模板中（即使它们已在全局定义）；这样，在将模板导出为 XML 并导入到其他系统后，Text 类型宏仍可按预期工作（secret macro 值不会被 导出）
  • 如果在触发器表达式中使用了用户宏，则这些宏仅在引用参数或常量时才会解析；如果引用主机、监控项键值、函数、运算符或其他触发器表达式，则不会解析（secret macro 不能用于触发器表达式）
  • 如果在具有低级别发现规则和主机原型的主机上使用了用户宏， 发现的主机 将继承该主机上定义的所有用户宏

示例

示例 1

在“SSH 守护进程状态”监控项键中使用主机级别宏：

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

只要在这些主机上定义了 {$SSH_PORT} 的值，就可以将此监控项分配给多个主机。

示例 2

在“CPU 负载过高”触发器中使用主机级别的宏：

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

此类触发器应在模板上创建，而不是在各个主机中编辑。

如果要将值的数量用作函数参数（例如，max(/host/key,#3)），请在宏定义中包含井号，如下所示：SOME_PERIOD => #3。

示例 3

在“CPU 负载过高”触发器中使用两个宏：

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

请注意，宏可以用作触发器函数的参数，本例中使用的是 min() 函数。

示例 4

将 agent 不可用条件与监控项更新间隔同步：

  • 定义 {$INTERVAL} 宏，并在监控项更新间隔中使用它；
  • 将 {$INTERVAL} 用作 agent 不可用触发器的参数：

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

示例 5

集中配置工作时间：

  • 创建全局 {$WORKING_HOURS} 宏，并将其设置为 1-5,09:00-18:00；
  • 在管理 > 常规 > 前端的工作时间字段中使用该宏；
  • 在用户 > 用户中某个用户的媒体选项卡的活动时间字段中使用该宏；
  • 使用该宏设置在工作时间内更频繁地轮询监控项：

  • 在操作条件的时间段中使用该宏；
  • 如有需要，在管理 > 宏中调整工作时间。
示例 6

使用主机原型宏为发现的主机配置监控项：

  1. 在主机原型上定义用户宏 {$SNMPVALUE}，并将 {#SNMPVALUE} 低级别发现宏设置为其值：

  1. 将 Generic SNMPv2 模板分配给主机原型。
  2. 在 Generic SNMPv2 模板监控项的 SNMP OID 字段中使用 {$SNMPVALUE}。

用户宏上下文

请参阅带上下文的用户宏。