Zabbix 的 JSONPath 预处理失败时，先用故障时的原始 JSON 在前端重放测试，再区分路径错误、字段缺失和返回类型变化。只有字段确实可选时才考虑丢弃异常值，避免把缺失数据当成正常的零值。

适用版本与前提

本文以 Zabbix 7.0 为例，依据官方文档整理，未在目标环境实测。需要能查看监控项及其预处理步骤，并取得脱敏后的原始返回值。如果子监控项依赖主监控项，应先拿到主监控项实际传入子项的数据。Zabbix 7.0 监控项预处理文档。

用正常和异常样本重放测试

进入监控项的预处理页，对 JSONPath 步骤点击测试，粘贴正常样本。下面的路径从根对象进入 stats，再取 pending，预期返回数字 12。

{"stats":{"pending":12}}
$.stats.pending

再用异常样本重复测试。下面第一行缺少 pending，第二行把 stats 从对象改成数组。数组格式需要按真实语义确定取哪一项。只有接口约定首项就是目标时，第三行的路径才适用。

{"stats":{}}
{"stats":[{"pending":12}]}
$.stats[0].pending

如果生产响应是一段 HTML 错误页，先检查采集端收到的响应状态和内容。如果前面还有转换步骤，应测试全部步骤，确认传给 JSONPath 的值和手工样本一致。Zabbix JSONPath 语法参考。

按字段用途处理失败

  • 必填指标缺失时，保留可见的错误并检查上游返回格式。
  • 字段按接口约定可以缺省时，可在该步骤启用 Custom on fail 并选 Discard value。该次样本会被丢弃，需要另行核对无数据告警是否符合预期。
  • 只有指标定义明确规定缺失等于零时，才考虑用固定值 0。否则图表和阈值可能把采集故障当成正常值。

Zabbix 自定义预处理失败行为。

验证新样本确实入库

先确认正常样本能通过所有步骤，最终值符合监控项的数值类型。再用异常样本核对预期错误或丢弃行为。保存后到最新数据查看新时间戳和值，避免把上一次成功值误认成恢复。如果连原始值都没有，请先排查采集链路。排查 Zabbix Agent 主动与被动采集。