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将结果发送回服务器。

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

异步检查最大并发数为1000 (由 MaxConcurrentChecksPerPoller定义).

异步agent pollers 由 StartAgentPollers 参数定义.

Server 请求

头部和数据长度的定义请参考协议详情。

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

Agent 响应

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

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

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 连接关闭。

对于不支持的监控项:

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 处理数据, 更改监控项状态为不支持并显示指定的错误消息。
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 server",
         "host_metadata": "mysql,nginx",
         "hostinterface": "zabbix.server.lan",
         "ip": "159.168.1.1",
         "port": 12050,
         "version": "7.0.0",
         "variant": 2,
         "config_revision": 1,
         "session": "e3dcbd9ace2c9694e1d7bbd030eeef6e"
       }

字段	类型	必填	值
request	string	yes	`主动检查`
host	string	yes	主机名.
host_metadata	string	no	配置参数 HostMetadata 或 HostMetadataItem 度量值.
hostinterface	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	增量配置同步的会话标识符.

Server 响应

在处理主动检查请求之后，主动检查响应由服务器发送回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	yes	`成功` \| `失败`
info		string	no	失败时的错误信息.
data		array of objects	no	主动检查监控项. 如果主机配置未更改则省略.
	key	string	no	具有扩展宏的Item key.
	itemid	number	no	监控项ID.
	delay	string	no	监控项更新时间. 从 Zabbix 7.0 开始，Zabbix agent 和 Zabbix agent 2 都支持灵活/调度间隔.
	lastlogsize	number	no	监控项最新日志大小.
	mtime	number	no	监控项更改时间.
	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将忽略主动检查服务器响应中包含的任何远程命令.
	command	string	no	远程命令.
	id	number	no	远程命令标识符.
	wait	number	no	远程命令执行方式 ("0" (不等待) 对于从动作操作; "1" (等待) 对于从手动的脚本执行).
config_revision		number	no	增量配置同步的配置标识符. 如果主机配置未更改，则省略。如果主机配置更改则增加.

服务器必须成功响应。

例如:

Agent 打开一个 TCP 连接
Agent 请求检查列表
服务器响应监控项列表和要执行的远程命令
Agent 解析响应
TCP 连接关闭
Agent开始定期收集数据并执行远程命令 (从Zabbix agent 7.0开始支持)

请注意，在使用主动检查时，（敏感）配置数据可能供有权访问 Zabbix server采集器端口的各方使用。这是可能的，因为任何人都可能假装是一个主动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每隔 HeartbeatFrequency 秒 (在Zabbix agent)/ agent 2 配置文件中配置）发送到Zabbix server/proxy。

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

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

字段	类型	必填	值
request	string	yes	`主动检查心跳`
host	string	yes	主机名.
heartbeat_freq	number	yes	agent 心跳频率 ( HeartbeatFrequency 配置参数 ).
version	string	yes	agent 版本号 .
variant	number	yes	agent 变体 (1 - Zabbix agent, 2 - Zabbix agent 2).

较旧的XML协议

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

Documentation