导读

本文围绕 Zabbix Community Templates 仓库中的Housekeeping Metrics（Zabbix-Monitor-Housekeeper）模板展开，讲解如何利用 Zabbix 自身的日志监控能力（active check + dependent item）持续采集 Zabbix Server 后台 Housekeeper 每次清理数据库的历史/趋势、事件、告警等记录数以及单次执行耗时。读完本文，你将掌握该模板的完整工作原理、全部监控项与正则预处理细节、宏配置方法，以及它在 Zabbix 4.4 / 5.0.6 等环境中的导入使用与适用边界，并能基于仓库中的模板源码（5.0 XML、5.4 YAML、6.0 YAML）自行验证与二次开发。

一、为什么需要监控 Housekeeper

Zabbix Server 自带的Housekeeper进程负责定期清理数据库中过期的历史数据（history）、趋势数据（trends）、事件（events）、告警（alarms）、会话（sessions）、审计（audit）、问题（problems）以及 items/triggers 相关记录。随着监控规模增长，数据库中积累的数据量会持续膨胀，Housekeeper 每次执行清理的规模、耗时直接影响数据库负载与磁盘占用。

然而，Zabbix 默认并不直接暴露 Housekeeper 的执行统计指标。Housekeeping Metrics 模板的思路非常直接：解析 zabbix_server.log 中 Housekeeper 每次执行后写下的清理日志行，将其中的各表删除记录数和执行耗时提取为可检索、可绘图、可告警的监控项。

需要特别说明的是（原文档亦明确标注）：该模板不适用于使用表分区（table partitioning）或其他独立数据库维护例程的环境，因为在这些环境下 Housekeeper 的实际清理行为与日志输出模式会发生变化。

二、模板概览与来源

该模板在仓库中提供了三个版本目录：

• 5.0/：以 XML 格式导出（template_zabbix_monitor_housekeeper.xml），对应 Zabbix 5.0 的导入格式；
• 5.4/：以 YAML 格式导出（template_zabbix_monitor_housekeeper.yaml）；
• 6.0/：以 YAML 格式导出（template_zabbix_monitor_housekeeper.yaml）。

原文档标注的验证环境（Homolog）为Zabbix 4.4与Zabbix 5.0.6；仓库目录中还提供了面向 5.4 与 6.0 的 YAML 导出，说明该模板在后续大版本中仍然可用。模板本身还分为英文版（EN-US，随仓库发布）与葡萄牙语版（PT-BR，未随仓库发布）两个语言变体。

三、工作原理：日志采集 + 依赖项提取

3.1 整体工作流程

模板的工作方式并不复杂，可以用一句话概括（原文档原文）：每当 zabbix-server 执行 housekeeping 时，zabbix_server.log 中会生成一行包含清理信息（被删除的数据）的日志；类型为 log 的 Syslog Housekeeping 监控项通过主动检查（active check）捕获该行，其余依赖监控项（dependent item）则根据父监控项的信息被预先填充。

具体链路如下：

1. Zabbix Server 的 Housekeeper 进程在每次清理完成后，向zabbix_server.log写入一行汇总日志；
2. 模板中的主监控项Syslog Housekeeping（类型Zabbix agent (active)、value_type为LOG）以 1 秒的更新间隔读取日志文件，并通过正则筛选出 housekeeping 相关行；
3. 其余 8 个依赖监控项以Syslog Housekeeping为 master item（父项），各自通过 REGEX 预处理从同一行日志中提取对应的数值；
4. 两个预置图形分别展示单次执行耗时与各类记录删除数量的时间序列。

3.2 日志行格式（由预处理正则反推）

虽然模板并未在文档中直接给出日志示例，但从 8 个依赖监控项各自配置的 REGEX 预处理规则（见 5.0 XML）可以反推出日志行中各字段的顺序结构。将这些正则按捕获顺序拼接，可以得到如下形态的一行（数值仅为示意）：

housekeeper [deleted 12345 hist/trends, 678 items/triggers, 901 triggers, 234 events, 567 problems, 890 sessions, 123 alarms, 456 audit records in 12.345678 sec]

各依赖项的正则与捕获内容对应关系如下：

注：以上日志行结构是从模板源码中 8 条 REGEX 预处理规则推断出的逻辑顺序，用于帮助理解字段提取逻辑；实际日志文本以你所使用 Zabbix 版本的zabbix_server.log输出为准。

3.3 主监控项：Syslog Housekeeping

• 名称：Syslog Housekeeping
• 类型：Zabbix agent (active)（主动式 agent 检查）
• 键值：log[{$PATHLOG},"{$REGEXLOG}",,,skip,,]
• 更新间隔：1s
• 值类型：LOG
• 历史/趋势保留：0（日志类监控项不保留 history 与 trends）
• 所属应用：01 - Housekeeping - Log

这里对log[]键值的参数逐一说明（Zabbix 官方log项语法为log[file,regexp,encoding,maxlines,mode,output,flexible,severity]）：

3.4 依赖监控项与 REGEX 预处理

8 个依赖监控项均满足以下共同特征（见 5.4 YAML 源码）：

• 类型：DEPENDENT（依赖项）
• 更新间隔：0（继承 master item 的节奏，无需单独轮询）
• master_item.key：log[{$PATHLOG},"{$REGEXLOG}",,,skip,,]（即 Syslog Housekeeping）
• 历史保留：7d；趋势保留：120d
• 所属应用：02 - Housekeeping - Metrics
• 预处理：一条REGEX步骤，输出为捕获组\1；并配置了错误处理器

以Records deleted in Alarms为例，其预处理配置为：

preprocessing: - type: REGEX parameters: - 'sessions, (.*) alarms' - \1 error_handler: CUSTOM_VALUE error_handler_params: '-1'

这里有一个值得注意的工程细节：error_handler: CUSTOM_VALUE+error_handler_params: '-1'。当 REGEX 匹配失败时（例如 Housekeeper 尚未执行、日志中暂无新的清理行），预处理会将该依赖项的值替换为自定义值-1，而不是保留上一次的旧值。这样既避免了“陈旧数据”被误读为最新状态，也使得后续若配置触发器时可以直接用负值判定“暂无数据”状态。

唯一例外的是Duration of the last executed Housekeeper：它的value_type为FLOAT，units设置为uptime，正则records in (.*) sec提取出的秒数会被 Zabbix 以 uptime 格式展示（自动换算为更易读的时长形式）。

四、宏定义与配置

模板共使用两个文本宏（Text macro），这是使用模板前需要确认或按环境调整的唯二入口：

{$PATHLOG}需要根据实际部署调整：不同发行版/安装方式下日志路径可能不同（如源码编译安装时可能在/usr/local/zabbix/logs/zabbix_server.log），自定义安装路径时务必在模板宏或主机级宏中覆盖。{$REGEXLOG}用于保证主监控项只捕获 housekeeping 清理行，避免zabbix_server.log中其他日志行进入处理流程，一般情况下保持默认即可。

模板级标签为Zabbix→Housekeeping（YAML 中tags定义），方便在 Zabbix 前端按标签检索模板。

五、监控项完整清单

根据 5.0 README 与模板源码，模板共采集 9 个监控项，其中 1 个为主监控项、8 个为依赖监控项：

该模板不包含触发器（Triggers），也不包含模板链接（Template links）与自动发现规则（Discovery rules）——它是一套纯粹的“采集 + 可视化”模板，告警策略需由使用方自行补充。模板中的两个应用（application）01 - Housekeeping - Log与02 - Housekeeping - Metrics用于在 Zabbix 前端按应用分组展示这些监控项。

六、预置图形

模板随附两个图形（见 6.0 YAML 中graphs定义），导入后即可在 Latest data 与 Monitoring → Graphs 中直接查看：

6.1 Housekeeper - Duration

• 展示dep.housekeeper.duration（最近一次 Housekeeper 执行耗时）；
• 图形项颜色1A7C11，Y 轴置于右侧（yaxisside: RIGHT）；
• 适合用来观察清理任务是否出现耗时异常增长。

6.2 Housekeeper - Metrics

• 同时绘制 7 个记录删除量指标：alarms、audit、events、histtrends、itemstriggers、problems、sessions；
• 所有图形项使用DASHED_LINE（虚线）绘制，并设置ymin_type_1: FIXED（Y 轴最小值固定为 0），避免因某一指标波动导致坐标轴失真；
• 各指标以不同颜色区分（F63100、2774A4、A54F10、5A5A5A、4DB6AC、AC8C14、611F27），便于一眼对比不同数据表的清理量级。

七、导入与使用方法

根据原文档的 Usage 说明，部署只需三步：

1. 导入模板：在 Zabbix 前端进入Configuration → Templates，点击 Import，选择对应版本目录下的导出文件。请根据你的 Zabbix 版本选择：
   • Zabbix 5.0：导入 5.0/template_zabbix_monitor_housekeeper.xml；
   • Zabbix 5.4：导入 5.4/template_zabbix_monitor_housekeeper.yaml；
   • Zabbix 6.0：导入 6.0/template_zabbix_monitor_housekeeper.yaml。
2. 关联主机：将模板链接（link）到运行 Zabbix Server 的那台主机（即 Host "Zabbix server"），因为zabbix_server.log位于 Zabbix Server 本机，且主监控项使用主动式 agent 检查，需要该主机上运行 Zabbix agent 且能读取日志文件。
3. 等待采集：监控项会按照 Housekeeper 自身的执行计划（housekeeping 调度）被采集——也就是说，并非每 1 秒都有新数据，只有 Housekeeper 实际执行并写出日志行后，主监控项才会捕获到新内容，依赖项才会更新。

补充说明几个实际操作中的前提条件：

• 运行在 Zabbix Server 主机上的 agent 必须对{$PATHLOG}指向的日志文件具备读取权限（通常需要将 agent 运行用户加入zabbix组或调整日志文件权限）；
• 确认zabbix_server.log中确实存在 housekeeping 相关日志输出（这要求 Zabbix Server 的日志级别配置允许输出 housekeeping 信息，默认的 Warning 级别即可满足，因为 housekeeping 汇总行属于该级别）；
• 由于主监控项使用了skip模式，导入模板后只会处理之后新产生的日志行，不会回填历史数据，请耐心等待下一个 housekeeping 周期。

八、适用版本与边界条件

• 已验证版本：Zabbix 4.4 与 Zabbix 5.0.6（原文档 Homolog 说明）；仓库同时提供 5.4、6.0 的 YAML 导出。
• 明确不适用场景：使用了表分区（table partitioning）或其他数据库维护例程的环境。这是因为在这些环境中，数据清理可能不经过标准的 Housekeeper 路径，日志行格式与清理行为均会变化，模板的正则提取将失效或产生误导性数据。
• 无告警能力：模板本身不含触发器，如需对“清理耗时过长”“删除量异常”等情况告警，需要在导入后自行基于上述监控项补充触发器表达式。

九、源码级验证与二次开发指引

如果需要深度定制，建议直接阅读仓库中的模板导出文件，它们比 README 包含更完整的实现细节：

• 5.0/template_zabbix_monitor_housekeeper.xml：完整的 XML 导出，包含 items、preprocessing、graphs、macros 全量定义；
• 5.4/template_zabbix_monitor_housekeeper.yaml 与 6.0/template_zabbix_monitor_housekeeper.yaml：YAML 格式导出，各对象均带 uuid，适合用zabbix_export工具做版本对比。

常见的二次扩展方向（均可基于现有结构实现）：

1. 新增触发器：例如dep.housekeeper.duration超过阈值（如 60s）触发 Warning；或某依赖项值连续 N 次为-1时提示 Housekeeper 长时间未执行。
2. 调整保留策略：默认 history 7d / trends 120d，可在导入后按合规或存储需求调整。
3. 适配其他日志路径：通过修改{$PATHLOG}宏适配非标准安装路径，无需改动监控项本身。
4. 增加告警类监控项：若你的 Zabbix 版本日志格式有差异，可参照现有 REGEX 预处理模式新增依赖项，将正则换成目标字段即可（注意同步调整 master item 的{$REGEXLOG}保证行筛选命中）。

十、总结

Housekeeping Metrics 模板是一份“小而精”的 Zabbix 运维实用模板：它不依赖外部脚本或数据库查询，完全借助 Zabbix 原生能力（log 类主动检查 + dependent item + REGEX 预处理）即可把 Zabbix Server 数据库清理行为转化为可观测指标。其核心价值在于：让运维人员无需登录数据库或手动翻日志，就能在 Zabbix 前端直观跟踪 Housekeeper 每次清理的记录删除量与耗时趋势，为数据库容量规划、清理频率调优和异常排查提供数据支撑。使用时请务必留意其“不适用于表分区环境”的边界，并根据自身 Zabbix 版本选择正确的导入文件。