Zabbix Proxy 健康监控模板全解析:本地、远程与 Agent 采集三种方案实战指南

原创2026-10-04 09:26:181,922 阅读
文章标签:运维指标监控可观测性告警监控大盘APM日志分析后端前端消息队列高可用分布式数据库

Zabbix Proxy 健康监控模板全解析:本地、远程与 Agent 采集三种方案实战指南

本篇技术指南围绕 Zabbix Proxy 官方监控模板 展开,系统讲解如何用 Zabbix 内部指标(internal metrics)监控 Zabbix proxy 自身的健康状态,涵盖本地直连、远程统计(stats)与被动/主动 Agent 四种部署形态,并深入模板背后的监控项(items)、触发器(triggers)、宏(macros)与源码实现。读完本文,你将掌握 proxy 进程利用率、队列积压、各类缓存水位、proxy 内存缓冲区状态等核心指标的采集原理、阈值调优方法,以及如何通过 StatsAllowedIP、CacheSize 等配置项联动解决容量与性能告警。

一、模板概览:一个目录,四种监控方案

当前仓库的 templates/app/zabbix_proxy/ 目录中包含两个核心文件:

  • README.md:模板官方文档,完整定义了四个模板的使用方式;
  • template_app_zabbix_proxy.yaml:模板的机器可读 YAML 定义(由官方模板工具 Templator 生成,zabbix_export 版本为 8.0)。

README 中实际上定义了四个模板,覆盖三种数据采集通路:

模板名称 采集方式 适用场景
Zabbix proxy health 本地内部指标(Zabbix internal) 模板直接挂在本地 proxy 主机上,采集 proxy 自身进程内部数据
Remote Zabbix proxy health 内部指标 + 远程 stats 请求(zabbix[stats,...]) 由 Zabbix server(或其他 proxy)远程拉取目标 proxy 的统计 JSON
Zabbix proxy health by Zabbix agent 被动 Zabbix agent(zabbix.stats[...]) 通过 proxy 本机安装的被动 agent 采集 stats 数据
Zabbix proxy health by Zabbix agent active 主动 Zabbix agent 通过 proxy 本机安装的主动 agent 采集 stats 数据

官方文档要求:Zabbix 版本为 8.0 及以上,模板已在 Zabbix proxy 8.0 上测试通过;使用前请先按照官方 “Templates out of the box” 章节完成基本配置。

二、方案一:Zabbix proxy health(本地内部指标)

2.1 部署方式

将模板链接(Link)到本地 Zabbix proxy 主机即可,无需任何宏修改。该模板完全依赖 Zabbix internal 类型监控项,即 proxy 进程自己把内部统计值暴露给 zabbix[xxx] 键。

2.2 宏定义

宏 说明 默认值
{$ZABBIX.PROXY.UTIL.MIN} 百分比利用率触发器的默认下限阈值(可通过宏上下文按进程细分) 65
{$ZABBIX.PROXY.UTIL.MAX} 百分比利用率触发器的默认上限阈值(可通过宏上下文按进程细分) 75

这两个宏只用于进程利用率类触发器,且均支持宏上下文。例如触发表达式中的 {$ZABBIX.PROXY.UTIL.MAX:"data sender"} 可以只针对 data sender 进程覆盖默认值,实现“不同进程、不同阈值”的精细告警策略。

2.3 核心监控项(Items)

本地方案监控项数量最多、最完整,按功能可分为五组:

① 队列与性能类

监控项 说明 键值
Queue over 10 minutes 延迟至少 10 分钟的在监控项数量 zabbix[queue,10m]
Queue 延迟至少 6 秒的在监控项数量 zabbix[queue]
Required VPS proxy 所需的性能(每秒需要采集的值数量) zabbix[requiredperformance](预处理:Discard unchanged with heartbeat 12h)
Uptime proxy 进程运行秒数 zabbix[uptime]

② 进程利用率类(24 项):全部采用 zabbix[process,<type>,avg,busy] 键,返回对应类型进程在过去一分钟的平均忙碌时间百分比。覆盖的进程类型包括:

  • 内部服务类:data sender、availability manager、configuration syncer、discovery manager、discovery worker、history syncer、housekeeper、ipmi manager、preprocessing worker、preprocessing manager、self-monitoring、task manager、trapper
  • 数据采集类:odbc poller、http poller、icmp pinger、ipmi poller、java poller、poller、snmp trapper、unreachable poller、vmware collector、agent poller、http agent poller、snmp poller、internal poller、browser poller、telemetry query poller

③ 缓存水位类

监控项 说明 键值
Configuration cache, % used 配置缓存(存储主机与监控项数据的共享内存)使用百分比 zabbix[rcache,buffer,pused]
History write cache, % used 历史数据缓存使用百分比(高值通常暗示数据库写入性能问题) zabbix[wcache,history,pused]
History index cache, % used 历史索引缓存使用百分比 zabbix[wcache,index,pused]
VMware cache, % used VMware 数据缓存使用百分比 zabbix[vmware,buffer,pused]
Proxy memory buffer, % used proxy 内存缓冲区使用百分比 zabbix[proxy_buffer,buffer,pused]

④ proxy 内存缓冲区状态类

监控项 说明 键值
Proxy buffer, state 当前缓冲区工作状态:0=磁盘(内存缓冲禁用时也返回 0);1=内存 zabbix[proxy_buffer,state,current](Discard unchanged 1h)
Proxy buffer, state changes 自 proxy 启动以来磁盘/内存模式切换次数 zabbix[proxy_buffer,state,changes](Discard unchanged 1h)

关于缓冲区状态的源码依据:stats.c 中,当程序类型为 proxy 时,通过 zbx_pb_get_mem_info() 与 zbx_pb_get_state_info() 将内存使用率、state 与 state change 写入 JSON;缓冲区状态频繁切换通常意味着磁盘缓冲与内存缓冲间抖动,应结合配置调整。

⑤ 吞吐与预处理类

监控项 说明 键值
Number of processed values per second 每秒处理值总数(不含不支持项) zabbix[wcache,values](Change per second)
Number of processed numeric (unsigned/float)、log、character、text values per second 按值类型拆分处理速率 zabbix[wcache,values,uint/float/log/str/text](Change per second)
Number of processed not supported values per second 导致监控项变为不支持状态的次数 zabbix[wcache,values,not supported](Change per second)
Zabbix preprocessing 预处理统计主监控项(JSON) zabbix[preprocessing]
Preprocessing queue 预处理队列中的值数量 依赖项 zabbix[preprocessing_queue],JSON Path $.data.queue

说明:本地模板中的 zabbix[preprocessing_queue] 实际是依赖项,其 JSON 路径 $.data.queue 指向主监控项 zabbix[preprocessing] 返回的 JSON。

⑥ 附加项

  • Zabbix proxy check:zabbix[triggers],标记“是否为 proxy”(0/1)。预处理分三步:任何错误→置 0;值在范围 0→0 之外→置 1;Discard unchanged 1d。用于防止模板误挂到 server 上。
  • Version:zabbix[version],proxy 版本号,Discard unchanged 1d。
  • Discovery queue:zabbix[discovery_queue],发现队列中的值数量。
  • Values waiting to be sent:zabbix[proxy_history],proxy 历史表中等待发送给 server 的值数量。
  • Utilization of data sender internal processes 等 24 个进程利用率项(见上文)。

2.4 触发器(Triggers)

进程利用率告警(24 条):统一表达式模式为:

avg(/Zabbix proxy health/zabbix[process,<type>,avg,busy],10m)>{$ZABBIX.PROXY.UTIL.MAX:"<type>"}

10 分钟平均忙碌百分比超过对应宏上下文阈值即触发,严重级别均为 Average,需手动关闭。

缓存容量告警(5 条),均为 Average 级别,告警描述直接给出配置建议:

触发器 表达式 建议动作
Excessive configuration cache usage max(...,10m)>{$ZABBIX.PROXY.UTIL.MAX:"configuration cache"} 增大 CacheSize
Excessive vmware cache usage max(...)>{$ZABBIX.PROXY.UTIL.MAX:"vmware cache"} 增大 VMwareCacheSize
Excessive history cache usage max(...)>{$ZABBIX.PROXY.UTIL.MAX:"history cache"} 增大 HistoryCacheSize
Excessive history index cache usage max(...)>{$ZABBIX.PROXY.UTIL.MAX:"index cache"} 增大 HistoryIndexCacheSize
Excessive proxy memory buffer usage max(...)>{$ZABBIX.PROXY.UTIL.MAX:"proxy buffer"} 增大 ProxyMemoryBufferSize

状态与运维告警(5 条):

触发器 表达式 严重级别
More than 100 items have been missing data for over 10 minutes min(zabbix[queue,10m],10m)>100 Warning
Wrong template assigned last(zabbix[triggers])=1 Disaster
Version has changed 相邻两次版本值不同且非空 Info
{HOST.NAME} has been restarted last(zabbix[uptime])<10m Info
(另有 Version/restart 两条均需手动关闭)

依据 checks_internal.c,zabbix[version]、zabbix[queue]、zabbix[process]、zabbix[wcache]、zabbix[rcache]、zabbix[vmware]、zabbix[stats]、zabbix[preprocessing]、zabbix[discovery_queue] 等键均在该文件中有明确的分支解析实现,可据此确认模板键值的合法性。

三、方案二:Remote Zabbix proxy health(远程 stats 采集)

3.1 部署方式与前提

此方案用于由一个 Zabbix 实例远程监控另一个 proxy。部署步骤:

  1. 在 Zabbix server 前端将模板链接到目标主机;
  2. 通过宏指定远程 proxy 的地址与端口;
  3. 在远程 proxy 的 zabbix_proxy.conf 中调整 StatsAllowedIP,允许发起统计请求的来源 IP(否则无法采集,模板会触发 “Failed to fetch stats data”)。

StatsAllowedIP 的仓库默认配置为 127.0.0.1(conf/zabbix_proxy.conf),默认仅允许本机访问统计接口,因此跨主机远程采集必须显式添加 server/proxy 的 IP 或网段,例如:

# 允许多个来源
StatsAllowedIP=127.0.0.1,192.168.1.0/24,::1,2001:db8::/32,zabbix.example.com

3.2 宏定义

在本地模板宏的基础上,远程方案新增/调整了:

宏 说明 默认值
{$ZABBIX.PROXY.ADDRESS} 远程 proxy 的 IP/DNS 127.0.0.1
{$ZABBIX.PROXY.PORT} 远程 proxy 的端口 10051
{$ZABBIX.PROXY.UTIL.MIN} 进程利用率下限阈值 65
{$ZABBIX.PROXY.UTIL.MAX} 进程利用率上限阈值 75
{$ZABBIX.PROXY.NODATA_TIMEOUT} 统计数据视为不可用的时间阈值(用于 nodata 触发器) 5m

3.3 采集机制:主监控项 + JSON Path 依赖项

远程方案的核心是单个主监控项 + 大量依赖项的两级结构:

  • 主监控项 Zabbix stats:zabbix[stats,{$ZABBIX.PROXY.ADDRESS},{$ZABBIX.PROXY.PORT}],类型为 Zabbix internal,一次请求拉取远程 proxy 的完整统计 JSON;
  • 其余监控项均为 Dependent(依赖)项,通过 JSON Path 预处理从主监控项的 JSON 中提取具体字段。

例如:

监控项 依赖键 JSON Path
Queue over 10 minutes zabbix[stats,{ADDR},{PORT},queue,10m] $.queue
Configuration cache, % used rcache.buffer.pused $.data.rcache.pused
Utilization of data sender processes process.data_sender.avg.busy $.data.process['data sender'].busy.avg
Version version $.data.version
Proxy memory buffer, % used proxy_buffer.buffer.pused $.data.wcache.['proxy buffer'].memory.pused
Proxy buffer, state proxy_buffer.state.current $.data.wcache.['proxy buffer'].state
Proxy buffer, state changes proxy_buffer.state.changes $.data.wcache.['proxy buffer'].['state change']
Uptime uptime $.data.uptime
Required VPS requiredperformance $.data.requiredperformance
Preprocessing queue preprocessing_queue $.data.preprocessing_queue
Discovery queue discovery_queue $.data.discovery_queue

源码佐证:checks_internal.c 中 zabbix[stats,...] 分支会校验 IP/端口参数(缺省时 IP 默认 127.0.0.1、端口默认 10051),当参数少于等于 3 个时调用 zbx_zabbix_stats_get() 生成本地 JSON,或通过 zbx_get_remote_zabbix_stats() 远程拉取;并特意在 JSON 外层加入 data 对象,使同一套 JSONPath 表达式在内部采集与外部采集两种来源下完全一致——这正是远程模板与 agent 模板能够复用相同依赖项键的原因。

3.4 容错预处理(Custom on fail)

远程方案为每个依赖项设计了“取数失败”兜底策略,避免主监控项返回后因字段缺失导致整条链路变红:

  • 进程利用率类:进程未启动时返回特定错误,如 Processes data sender not started、No "discovery manager" processes started.;
  • proxy_check($.data.triggers):失败置 0,值不在范围置 1;
  • VMware 缓存($.data.vmware.pused):无 vmware collector 进程时返回 No vmware collector processes started;
  • Proxy memory buffer($.data.wcache.['proxy buffer'].memory.pused):内存缓冲禁用时返回 Proxy memory buffer is disabled.;
  • Proxy buffer state/state changes:失败置 0;
  • 预处理吞吐/VPS 项:失败时 Discard value(丢弃该次取值);
  • Discovery queue:提示检查 server 配置中的 StartDiscoverers 参数。

3.5 触发器差异

远程模板在继承本地全部告警的基础上,新增一条:

触发器 表达式 严重级别
Failed to fetch stats data nodata(rcache.buffer.pused,{$ZABBIX.PROXY.NODATA_TIMEOUT})=1 Warning(无手动关闭要求)

即超过 {$ZABBIX.PROXY.NODATA_TIMEOUT}(默认 5 分钟)未收到统计 JSON 即告警,通常指向 StatsAllowedIP 配置错误、网络不通或端口不可达。其余触发器表达式中的主机前缀由 /Zabbix proxy health/ 改为 /Remote Zabbix proxy health/,逻辑不变。

四、方案三与四:by Zabbix agent / by Zabbix agent active

4.1 适用场景与前提

当希望由 proxy 本机的 Zabbix agent 来代理采集 stats 数据(例如目标 proxy 网络受限、不便直接暴露统计端口)时,使用这两个模板。前提条件与远程方案一致:

  1. 在宏中指定远程 proxy 的 {$ZABBIX.PROXY.ADDRESS} 与 {$ZABBIX.PROXY.PORT};
  2. 在远程 proxy 的 zabbix_proxy.conf 中调整 StatsAllowedIP 允许 agent 所在主机访问统计接口;
  3. proxy 本机需安装并运行 Zabbix agent。

4.2 主监控项差异

  • 被动 agent 模板:主监控项类型为 Zabbix agent,键 zabbix.stats[{$ZABBIX.PROXY.ADDRESS},{$ZABBIX.PROXY.PORT}](被动模式下由 server 轮询 agent);
  • 主动 agent 模板:主监控项类型为 Zabbix agent (active),键同样为 zabbix.stats[...](主动模式下 agent 定期向 server 汇报)。

两者采集到的 JSON 结构与 zabbix[stats,...] 一致,因此下游依赖项、JSON Path 预处理、触发器与远程方案完全相同(仅表达式主机前缀分别变为 /Zabbix proxy health by Zabbix agent/ 与 /Zabbix proxy health by Zabbix agent active/),区别仅在于 stats 数据的传输通道由“内部键直接请求”变为“agent 代理转发”。

从模板 YAML 也可以确认:三个“远端采集类”模板在 items 层完全同构,唯一差别是 master item 的类型与键前缀(zabbix[stats,...] vs zabbix.stats[...]),可见模板设计上刻意让三种通道共享同一套解析逻辑。

4.3 宏与触发器

两个 agent 模板的宏列表与远程方案一致(ADDRESS、PORT、UTIL.MIN/MAX、NODATA_TIMEOUT),触发器也完全一致,包括 Failed to fetch stats data(Warning)。因此可据此选择任一通道,监控口径完全统一。

五、模板背后的实现原理:内部键如何产生数据

理解模板键的数据来源,有助于排查“监控项不支持”类问题。模板用到的键在源码中的实现位置如下:

键 实现位置(src/libs/zbxpoller/checks_internal.c) 返回内容
zabbix[version] L334 编译期版本号 ZABBIX_VERSION
zabbix[queue,<from>,<to>] L364 通过 zbx_dc_get_item_queue() 统计延迟区间内的监控项数量
zabbix[requiredperformance] L396 配置缓存中统计的每秒所需处理值
zabbix[uptime] L406 当前时间 - config_startup_time
zabbix[process,<type>,<mode>,<state>] L510 指定进程类型的忙碌百分比/运行状态
zabbix[wcache,<cache>,<mode>] L614 历史/索引缓存的总量、空闲、使用及百分比
zabbix[rcache,<cache>,<mode>] L756 配置缓存的总量、空闲、使用及百分比
zabbix[vmware,...] L804 VMware 缓存统计
zabbix[stats,...] L860 完整统计 JSON(含 data 包裹层)
zabbix[preprocessing] L977 预处理队列尺寸/吞吐 JSON
zabbix[discovery_queue] L997 发现队列尺寸

JSON 字段生成端在 stats.c 的 zbx_zabbix_stats_get():它会依次写入 boottime、uptime、hosts、items、items_unsupported、requiredperformance、rcache、version、wcache(含按数据类型拆分的 values、history、index,server 额外含 trend,proxy 额外含 proxy buffer 的 memory/state 信息)。模板中的每个 JSON Path 都能在此函数中找到对应字段,这也是模板键值“有据可查”的保证。

六、容量告警的配置联动:zabbix_proxy.conf 关键参数

模板中五条缓存类触发器全部指向 conf/zabbix_proxy.conf 的配置项,告警后的标准处置如下:

配置项 触发条件 建议处置 仓库默认参考
CacheSize 配置缓存使用率 > 阈值 增大配置缓存(范围 128K–64G) 默认 8M(conf/zabbix_proxy.conf)
HistoryCacheSize 历史缓存使用率 > 阈值 增大历史缓存 默认 4M(conf/zabbix_proxy.conf 附近)
HistoryIndexCacheSize 历史索引缓存使用率 > 阈值 增大历史索引缓存 默认 4M(conf/zabbix_proxy.conf)
VMwareCacheSize VMware 缓存使用率 > 阈值 增大 VMware 缓存 默认 8M(conf/zabbix_proxy.conf)
ProxyMemoryBufferSize 内存缓冲使用率 > 阈值 增大内存缓冲区 默认 16M(conf/zabbix_proxy.conf)

History write cache 的“高使用率”通常意味着数据库写入性能不足(历史缓存用于暂存监控项值,是写入 DB 前的缓冲层),此时除了扩容,还应排查 DB 端性能。而 Proxy buffer, state 若频繁在 0/1 间切换,可结合 ProxyOfflineBuffer(conf/zabbix_proxy.conf)等参数评估缓冲策略。

七、监控口径一致性对比与选型建议

四个模板在“监控什么”上完全一致,区别仅在“数据怎么来”:

维度 本地 health Remote health by agent (passive/active)
数据来源 proxy 进程内部键 zabbix[stats,addr,port] 远程 JSON agent 执行 zabbix.stats[addr,port] 代理 JSON
主监控项类型 Zabbix internal Zabbix internal Zabbix agent / Zabbix agent (active)
需要 StatsAllowedIP 否 是 是
依赖项解析 直接键值 JSON Path($.data.*) JSON Path(同左)
额外触发器 无 Failed to fetch stats data Failed to fetch stats data

选型建议:

  • proxy 与 server 同机或网络直通、希望零额外组件:选 Zabbix proxy health;
  • proxy 分布在不同机房/网络,由中心 server 统一监控:选 Remote Zabbix proxy health,并务必配置 StatsAllowedIP;
  • 目标 proxy 不便直接暴露 10051 统计端口、但本机已部署 agent:选 by Zabbix agent(被动)或 by Zabbix agent active(主动),二者监控口径一致,按 agent 工作模式取其一即可。

八、常见问题排查速查

现象 排查方向
远程/agent 模板触发 “Failed to fetch stats data” 检查 StatsAllowedIP 是否包含采集来源 IP;确认地址/端口宏正确;测试网络连通性
触发器 “Wrong template assigned” 触发 模板误挂到了 server 主机,zabbix[triggers] 返回 1;换用 server 对应的健康模板
进程利用率项报 “Processes xxx not started” 对应进程类型未启动,检查 StartXxx 参数是否配置为 0(如未启用 VMware collector、browser poller 等)
缓存类告警频发 按第六节表格扩容对应配置项,并同步关注数据库写入性能与历史数据保留策略
“Version has changed” 正常提示,升级/回滚 proxy 版本后确认无误手动关闭即可

需要进一步对照实际 JSON 结构调试预处理时,可在目标 proxy 上通过 zabbix_get -s <ip> -p <port> -k "zabbix[stats,127.0.0.1,10051]" 直接拉取原始统计 JSON,即可验证模板中每条 JSON Path 的取值是否正确。

登录后查看全文
zabbix