Table of Contents

2 被动和主动 Agent 检查

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 server或proxy请求一些数据（例如，CPU负载），然后Zabbix agent将结果发送回 server。

被动检查是异步执行的 - 在开始其他检查之前，不需要接收对一个请求的响应。DNS解析也是异步的。

agent poller将尝试连接由DNS查找返回的所有地址。这确保了如果一个IP地址无法访问，poller将尝试下一个可用地址，从而增加了成功连接的可能性。此增强功能适用于Zabbix server和proxy。

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

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

Server请求

对于header和数据长度的定义，请参考协议细节。

{
         "request": "passive checks",
         "data": [
           {
             "key": "agent.version",
             "timeout": 3
           }
         ]
       }

Agent响应

{
         "version": "7.0.0",
         "variant": 2,
         "data": [
           {
             "value": "7.0.0"
           }
         ]
       }

例如，对于支持的items：

Server打开TCP连接
Server发送<HEADER><DATALEN>{"request":"passive checks","data":[{"key":"agent.ping","timeout":3}]}
Agent读取请求并响应 <HEADER><DATALEN>{"version":"7.0.0","variant":2,"data":[{"value":1}]}
Server处理数据以获取值，'1'在我们的情况下
TCP连接关闭

对于不支持的items：

Server打开TCP连接
Server发送<HEADER><DATALEN>{"request":"passive checks","data":[{"key":"vfs.fs.size[/nono]","timeout":3}]}
Agent读取请求并响应 <HEADER><DATALEN>{"version":"7.0.0","variant":2,"data":[{"error":"Unsupported item key."}]}
Server处理数据，将item状态更改为不支持，并附带指定的错误消息
TCP连接关闭

故障转移到旧协议

为了确保 Zabbix server或proxy可以与 7.0 之前版本（具有明文协议）的Agent一起使用，实现了到旧协议的故障转移。

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

请注意， Zabbix server/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 请求

主动检查请求用于获取由 agent 处理的主动检查列表。此请求在 agent 启动时发送，并随后按照 RefreshActiveChecks 间隔发送。

{
         "request": "active checks",
         "host": "Zabbix 服务器",
         "host_metadata": "mysql,nginx",
         "interface": "zabbix.server.lan",
         "ip": "159.168.1.1",
         "port": 12050,
         "version": "7.0.0",
         "variant": 2,
         "config_revision": 1,
         "session": "e3dcbd9ace2c9694e1d7bbd030eeef6e"
       }

字段	类型	必填	值
request	string	是	`active checks`
host	string	是	主机名。
host_metadata	string	否	配置参数 HostMetadata 或 HostMetadataItem 指标值。
interface	string	否	配置参数 HostInterface 或 HostInterfaceItem 指标值。
ip	string	否	配置参数 ListenIP 设置的第一个 IP。
port	number	否	配置参数 ListenPort 值，如果设置且非默认 agent 监听端口。
version	string	是	agent 版本号。
variant	number	是	agent 变体 (1 - Zabbix agent, 2 - Zabbix agent 2)。
config_revision	number	否	配置标识符用于增量配置同步。
session	string	否	会话标识符用于增量配置同步。

服务器响应

主动检查响应由服务器在处理主动检查请求后发送回 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
           }
         ]
       }

字段		类型	必填	值
response		string	是	`success` \| `failed`
info		string	否	失败情况下的错误信息。
data		array of objects	否	主动检查项目。如果主机配置未更改则省略。
	key	string	否	项目键，已扩展宏。
	itemid	number	否	项目标识符。
	delay	string	否	项目更新间隔。自 Zabbix 7.0 起，Zabbix agent 和 Zabbix agent 2 均支持灵活/调度间隔。
	lastlogsize	number	否	项目 lastlogsize。
	mtime	number	否	项目 mtime。
	timeout	string	否	项目超时时间。
refresh_unsupported		number	否	不支持的项目刷新间隔。
regexp		array of objects	否	全局正则表达式。
	name	string	否	全局正则表达式名称。
	expression	string	否	全局正则表达式。
	expression_type	number	否	全局正则表达式类型。
	exp_delimiter	string	否	全局正则表达式分隔符。
	case_sensitive	number	否	全局正则表达式大小写敏感设置。
commands		array of objects	否	要执行的远程命令。如果通过动作操作或手动脚本执行触发了远程命令执行，则包括在内。请注意，自 Zabbix agent 7.0 起支持在主动 agent 上执行远程命令。较旧的主动 agent 将忽略主动检查服务器响应中包含的任何远程命令。
	command	string	否	远程命令。
	id	number	否	远程命令标识符。
	wait	number	否	远程命令执行模式（"0"（nowait）用于动作操作的命令；"1"（wait）用于手动脚本执行的命令）。
config_revision		number	否	配置标识符用于增量配置同步。如果主机配置未更改则省略。如果主机配置更改则递增。

服务器必须以成功响应。

例如：

Agent 打开 TCP 连接
Agent 请求检查列表
服务器响应项目列表和要执行的远程命令
Agent 解析响应
TCP 连接关闭
Agent 开始周期性数据收集和执行远程命令（自 Zabbix agent 7.0 起支持）

请注意，（敏感）配置数据可能当使用主动检查时，对访问 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": "1234456akdsjhfoui",
         "host": "Zabbix server",
         "version": "7.0.0",
         "variant": 2
       }

字段		类型	必填	值
request		string	yes	`agent数据`
data		array of objects	yes	监控项值.
	id	number	yes	值标识符（用于在出现网络问题时检查重复值的增量计数器）.
	itemid	string	yes	监控项ID.
	value	string	no	监控项值.
	lastlogsize	number	no	监控项 lastlogsize.
	mtime	number	no	监控项修改时间.
	state	number	no	监控项状态.
	source	string	no	值事件日志源.
	eventid	number	no	值事件日志eventid.
	severity	number	no	值事件日志严重性.
	timestamp	number	no	值事件日志时间戳.
	clock	number	yes	值时间戳（自纪元以来的秒数）.
	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。值 ID 是一个简单的递增计数器，在一个数据会话中是唯一的（由会话令牌标识）。此 ID 用于丢弃可能在连接性差的环境中发送的重复值。

Server 响应

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

{
         "response": "success",
         "info": "processed: 2; failed: 0; total: 2; seconds spent: 0.003534"
       }

字段	类型	必填	值
response	string	yes	`成功` \| `失败`
info	string	yes	监控项处理结果.

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

例如:

Agent 打开一个 TCP 连接
Agent 发送一个值列表
Server 处理数据并将状态返回
TCP 连接关闭

请注意，在上面的示例中，vfs.fs.size[/nono] 的不支持状态是如何通过"state"值 1 和“value”属性中的错误消息来指示的。

服务器端错误消息将被修剪为 2048 个符号。

心跳消息

Agent 发送

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

它用于监控主动检查的可用性。

{
         "request": "active check heartbeat",
         "host": "Zabbix 服务器",
         "heartbeat_freq": 60,
         "version": "7.0.0",
         "variant": 2
       }

字段	类型	必填	值
request	string	是	`active check heartbeat`
host	string	是	主机名。
heartbeat_freq	number	是	agent心跳频率（HeartbeatFrequency配置参数）。
version	string	是	agent版本号。
variant	number	是	agent变体（1 - Zabbix agent, 2 - Zabbix agent 2）。

重定向响应

当主机已被重新分配时，服务器可能指示agent将其心跳（以及后续的主动检查）重定向至另一proxy或服务器实例。

  {
           "response": "failed",
           "redirect": {
             "revision": 2,
             "address": "192.0.2.0:10055"
           }
         }

字段		类型	必填
response		string	是
redirect		object	是
	revision	number	是
	address	string	是

较旧的XML协议

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

Documentation