2 被动和主动 Agent 检查

概述

本节提供有关 Zabbix agent 和 Zabbix agent 2 执行的被动和主动检查的详细信息。

Zabbix 使用基于 JSON 的通信协议与 Zabbix agent进行通信。

从Zabbix 7.0起，Zabbix agent 和 Zabbix agent 2 协议已统一。Zabbix agent 和 Zabbix agent 2 请求/响应之间的差异由"variant" 标签值表示。

被动检查

被动检查是一种简单的数据请求。Zabbix 服务器或 proxy 会请求一些数据（例如 CPU 负载），然后 Zabbix agent 将结果返回给服务器。

被动检查是异步执行的 - 在启动其他检查之前，不需要先接收某个请求的响应。DNS 解析同样是异步的。

agent poller 会尝试连接 DNS 查询返回的所有地址。这样可以确保如果某个 IP 地址不可达，poller 会尝试下一个可用地址，从而提高连接成功的可能性。此增强适用于 Zabbix 服务器和 proxy。

异步检查的最大并发数为 1000（由 MaxConcurrentChecksPerPoller 定义）。

异步 agent poller 的数量由 StartAgentPollers 参数定义。

服务器请求

关于报文头和数据长度的定义，请参阅 协议详情。

{
  "request": "passive checks",
  "data": [
    {
      "key": "agent.version",
      "timeout": 3
    }
  ]
}
Field Type Mandatory Value
request string yes "passive checks"
data array of object yes 被动检查监控项。
key string yes 展开宏后的监控项键值。
timeout number yes 通信超时。

agent 响应

{
  "version": "7.4.0",
  "variant": 2,
  "data": [
    {
      "value": "7.4.0"
    }
  ]
}
Field Type Mandatory Value
version string yes agent 版本号。
variant number yes agent 变体（1 - Zabbix agent，2 - Zabbix agent 2）。
data array of object yes 包含检查结果。
value string no 检查成功时的监控项值。
error string no 检查不成功时的错误消息。

例如，对于受支持的监控项：

  1. 服务器打开一个 TCP 连接
  2. 服务器发送 <HEADER><DATALEN>{"request":"passive checks","data":[{"key":"agent.ping","timeout":3}]}
  3. agent 读取请求并响应： <HEADER><DATALEN>{"version":"7.4.0","variant":2,"data":[{"value":1}]}
  4. 服务器处理数据以获取值，在本例中为 '1'
  5. TCP 连接关闭

对于不受支持的监控项：

  1. 服务器打开一个 TCP 连接
  2. 服务器发送 <HEADER><DATALEN>{"request":"passive checks","data":[{"key":"vfs.fs.size[/nono]","timeout":3}]}
  3. agent 读取请求并响应： <HEADER><DATALEN>{"version":"7.4.0","variant":2,"data":[{"error":"Unsupported item key."}]}
  4. 服务器处理数据，将监控项状态更改为不受支持，并附带 指定的错误消息
  5. TCP 连接关闭
故障切换到旧协议

为确保 Zabbix 服务器或 proxy 能够与 7.2 之前版本、使用明文协议的 agent 配合工作，系统实现了向旧协议的故障切换机制。

被动检查在重启后或接口配置发生更改时，会使用 JSON 协议（7.0 及更高版本）执行。
如果响应中未收到有效的 JSON（agent 返回了 "ZBX_NOTSUPPORTED"），Zabbix 将把该接口缓存为旧协议，并通过仅发送监控项键值来重试检查。

请注意，Zabbix 服务器/proxy 每小时都会再次尝试让所有接口使用新协议进行通信，并在需要时回退到旧协议。

主动检查

主动检查需要更复杂的处理，agent 必须首先从server/proxy端获取监控项列表，或通过 远程命令 进行独立处理。

从中获取主动检查的server/proxy在Agent 配置文件 的"ServerActive"参数中列出。请求这些检查的频率由同一配置文件中的"RefreshActiveChecks"参数设置。但是，如果刷新主动检查失败，则会在硬编码 60 秒后重试。

从 Zabbix 6.4 开始，Agent（处于主动模式）不再每两分钟从server/proxy接收一次完整的配置副本（默认）。相反，为了减少网络流量和资源使用，每 5 秒（默认）执行一次增量配置同步，server/proxy 仅在Agent尚未收到配置时才提供配置的完整副本，或者主机配置、全局宏或全局正则表达式发生了某些变化。

然后，agent定期向服务器发送新值。如果Agent收到任何远程命令 需要去执行，执行结果也会被发送。请注意，自 Zabbix Agent 7.0 起，支持在主动Agent上执行远程命令。

如果Agent位于防火墙后面，您可能会考虑仅使用主动检查，因为在这种情况下您不需要修改防火墙以允许初始传入连接。

获取监控项列表

Agent 请求

active checks 请求用于获取由 agent 处理的 active checks。
该请求由 agent 在启动时发送，之后会按照 RefreshActiveChecks 间隔发送。

{
  "request": "active checks",
  "host": "Zabbix server",
  "host_metadata": "mysql,nginx",
  "interface": "zabbix.server.lan",
  "ip": "159.168.1.1",
  "port": 12050,
  "version": "7.4.0",
  "variant": 2,
  "config_revision": 1,
  "session": "e3dcbd9ace2c9694e1d7bbd030eeef6e"
}
Field Type Mandatory Value
request string yes active checks
host string yes 主机名。
host_metadata string no 配置参数 HostMetadata 或 HostMetadataItem 监控项值。
interface string no 配置参数 HostInterface 或 HostInterfaceItem 监控项值。
ip string no 配置参数 ListenIP 的第一个 IP（如果已设置）。
port number no 配置参数 ListenPort 的值（如果已设置且不是默认 agent 监听端口）。
version string yes agent 版本号。
variant number yes agent 变体（1 - Zabbix agent，2 - Zabbix agent 2）。
config_revision number no 增量配置同步的配置标识符。
session string no 增量配置同步的会话标识符。

服务器响应

active checks 响应由服务器在处理 active checks 请求后返回给 agent。

{
  "response": "success",
  "config_revision": 2,
  "data": [
    {
      "key": "system.uptime",
      "itemid": 1234,
      "delay": "10s",
      "lastlogsize": 0,
      "mtime": 0
    },
    {
      "key": "agent.version",
      "itemid": 5678,
      "delay": "10m",
      "lastlogsize": 0,
      "mtime": 0,
      "timeout": "30s"
    }
  ],
  "commands": [
    {
      "command": "df -h --output=source,size / | awk 'NR>1 {print $2}'",
      "id": 1324,
      "wait": 1
    }
  ]
}
Field Type Mandatory Value
response string yes success | failed
info string no 失败时的错误信息。
data array of objects no active check 监控项。如果主机配置未更改，则省略。
key string no 展开宏后的监控项键值。
itemid number no 监控项标识符。
delay string no 监控项更新间隔。
自 Zabbix 7.0 起，Zabbix agent 和 Zabbix agent 2 均支持灵活/计划间隔。
lastlogsize number no 监控项 lastlogsize。
mtime number no 监控项 mtime。
timeout string no 监控项超时时间。
refresh_unsupported number no 不支持的监控项刷新间隔。
regexp array of objects no 全局正则表达式。
name string no 全局正则表达式名称。
expression string no 全局正则表达式。
expression_type number no 全局正则表达式类型。
exp_delimiter string no 全局正则表达式分隔符。
case_sensitive number no 全局正则表达式大小写敏感设置。
commands array of objects no 要执行的远程命令。如果由某个动作 操作 或手动 脚本 执行触发了远程命令执行，则会包含此项。请注意，自 Zabbix agent 7.0 起，活动 agent 支持远程命令执行。较旧的活动 agent 会忽略 active checks 服务器响应中包含的任何远程命令。
command string no 远程命令。
id number no 远程命令标识符。
wait number no 远程命令执行模式（来自动作 操作 的命令为 "0"（nowait）；来自手动 脚本 执行的命令为 "1"（wait））。
timeout number no 服务器/proxy 配置中的远程命令执行超时。
config_revision number no 增量配置同步的配置标识符。如果主机配置未更改则省略；如果主机配置已更改则递增。

服务器必须返回 success。

例如：

  1. Agent 打开一个 TCP 连接
  2. Agent 请求监控项列表
  3. 服务器返回监控项和要执行的远程命令列表
  4. Agent 解析响应
  5. TCP 连接关闭
  6. Agent 开始周期性采集数据并执行远程命令（自 Zabbix agent 7.0 起支持）

请注意，在使用 active check 时，具有访问 Zabbix 服务器 trapper 端口权限的人员可能会获取（敏感）配置数据。之所以可能，是因为任何人都可以伪装成活动 agent 并请求监控项配置数据；除非使用 加密 选项，否则不会进行身份验证。

发送收集的数据

Agent 发送

agent 数据请求包含已收集的监控项值以及已执行远程命令的结果（如果有）。

{
  "request": "agent data",
  "data": [
    {
      "id": 1,
      "itemid": 5678,
      "value": "7.0.0",
      "clock": 1712830783,
      "ns": 76808644
    },
    {
      "id": 2,
      "itemid": 1234,
      "value": "69672",
      "clock": 1712830783,
      "ns": 77053975
    }
  ],
  "commands": [
    {
      "id": 1324,
      "value": "16G"
    }
  ],
  "session": "8495cd52070e6ca52b371f29c8574165",
  "host": "Zabbix server",
  "version": "7.4.0",
  "variant": 2
}
Field < Type Mandatory Value
request < string yes agent data
data < array of objects yes 监控项值。
id < number yes 值标识符（用于在网络问题情况下检查重复值的递增计数器）。
^ itemid number yes 监控项标识符。
^ value string no 监控项值。
^ lastlogsize number no 监控项 lastlogsize。
^ mtime number no 监控项 mtime。
^ state number no 监控项状态。
^ source string no 值事件日志来源。
^ eventid number no 值事件日志 eventid。
^ severity number no 值事件日志严重性。
^ timestamp number no 值事件日志时间戳。
^ clock number yes 值时间戳（自 Epoch 起的秒数）。
^ ns number yes 值时间戳的纳秒数。
commands < array of objects no 远程命令执行结果。请注意，自 Zabbix agent 7.0 起，活动 agent 支持远程命令执行。较旧的活动 agent 会忽略活动检查服务器响应中包含的任何远程命令。
id number no 远程命令标识符。
^ value string no 如果执行成功，则为远程命令执行结果。
^ error string no 如果执行失败，则为远程命令执行错误消息。
session < string yes 每次 agent 启动时生成的唯一会话标识符。
host < string yes 主机名。
version < string yes agent 版本号。
variant < number yes agent 变体（1 - Zabbix agent，2 - Zabbix agent 2）。

每个值都会分配一个虚拟 ID。Value ID 是一个简单的递增计数器，在一个数据会话内唯一（由会话令牌标识）。此 ID 用于丢弃在网络连接不佳的环境中可能发送的重复值。

服务器响应

服务器在处理 agent 数据请求后，会将 agent 数据响应发送回 agent。

{
  "response": "success",
  "info": "processed: 2; failed: 0; total: 2; seconds spent: 0.003534"
}
Field Type Mandatory Value
response string yes success | failed
info string yes 监控项处理结果。

如果服务器上某些值发送失败（例如，因为主机或监控项已被禁用或删除），agent 不会重试发送这些值。

例如：

  1. Agent 打开一个 TCP 连接
  2. Agent 发送一个值列表
  3. 服务器处理数据并返回状态
  4. TCP 连接关闭

错误消息在服务器端会被截断为 2048 个字符。

心跳消息

Agent 发送

心跳消息由主动 agent 发送到 Zabbix 服务器/proxy，每隔 HeartbeatFrequency 秒发送一次（在 Zabbix agent/agent 2 配置文件中配置）。

它用于监控主动监控项的可用性。

{
  "request": "active check heartbeat",
  "host": "Zabbix server",
  "heartbeat_freq": 60,
  "version": "7.4.0",
  "variant": 2
}
字段 类型 必填 值
request string yes active check heartbeat
host string yes 主机名。
heartbeat_freq number yes agent 心跳频率（HeartbeatFrequency 配置参数）。
version string yes agent 版本号。
variant number yes agent 变体（1 - Zabbix agent，2 - Zabbix agent 2）。

重定向响应

当主机被重新分配后，服务器可能会指示 agent 将其心跳（以及后续的主动监控项）重定向到另一个 proxy 或服务器实例。

  {
    "response": "failed",
    "redirect": {
      "revision": 2,
      "address": "192.0.2.1:10055"
    }
  }
字段 类型 必填 值
response string yes success | failed
redirect object yes 重定向指令。
revision number yes 配置修订标识符。
address string yes 目标服务器/proxy 地址。

较旧的XML协议

Zabbix将占用16 MB的XML base64编码的数据, 但单个解码值应该不超过64 KB，否则，在解码时将被截断到64 KB。