Zabbix Proxy 健康监控模板全解析:本地、远程与 Agent 采集三种方案实战指南
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。部署步骤:
- 在 Zabbix server 前端将模板链接到目标主机;
- 通过宏指定远程 proxy 的地址与端口;
- 在远程 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 网络受限、不便直接暴露统计端口)时,使用这两个模板。前提条件与远程方案一致:
- 在宏中指定远程 proxy 的
{$ZABBIX.PROXY.ADDRESS}与{$ZABBIX.PROXY.PORT}; - 在远程 proxy 的
zabbix_proxy.conf中调整StatsAllowedIP允许 agent 所在主机访问统计接口; - 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,...]vszabbix.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 的取值是否正确。