Zabbix Housekeeping Metrics 模板实战：从 zabbix_server.log 解析 Housekeeper 删除记录与执行耗时-平芜编程栈

【免费下载链接】community-templates

Zabbix Community Templates repository

项目地址：https://gitcode.com/gh_mirrors/co/community-templates

导读

Housekeeping（数据清理）是 Zabbix Server 定期回收过期历史数据的核心机制，但默认情况下它"默默运行"，运维人员很难直观看到每次清理删除了多少记录、花了多长时间。本篇技术指南以 Zabbix Community Templates 仓库中的Housekeeping Metrics模板为核心，讲解如何通过log[]主动检查项捕获zabbix_server.log中的 housekeeping 摘要日志，并用 8 个依赖项配合正则预处理把"删除记录数、执行耗时"解析成可监控、可绘图、可告警的指标。读完本文，你将掌握该模板的完整工作原理、导入配置步骤、宏与正则的调参方法，以及如何结合模板导出文件（YAML/XML）理解其底层实现细节。

模板概览：它解决什么问题

Housekeeping Metrics 模板由作者 Bernardo Lankheet 开发（灵感来源于 Diego Cavalcante 的 ZAKEEP.zabbix.housekeeper.monitor 项目思路），定位非常明确：采集 Zabbix Server Housekeeper 执行的度量数据。模板本身不监控业务可用性，而是回答两个运维高频问题：

每次 housekeeping 从history、trends、problems、events、audit、sessions、alarms、items/triggers等表中分别删除了多少条记录；
最近一次 housekeeping 总共执行了多长时间。

模板官方说明中特别强调了一个适用边界：它不适用于采用表分区（table partitioning）或其他数据库维护例程的环境——因为这类环境下数据删除不再由 housekeeper 负责，zabbix_server.log中也不会产生对应的删除摘要行，采集结果将失去意义。

在仓库中，该模板以多版本形式维护：5.0目录提供 XML 格式，5.4、6.0目录提供 YAML 格式，且三个版本的 README 内容一致；作者在 Homolog 一节标注的验证环境为 Zabbix 4.4 与 5.0.6。同时模板存在 EN-US 与 PT-BR 两种语言版本，仓库内收录的是英文版。

工作原理：日志行 → 主项捕获 → 依赖项解析

整个监控链路非常精巧，仅靠"1 个日志主项 + 8 个依赖项"就完成了结构化提取，其运行机制如下：

Zabbix Server 每次执行 housekeeping 时，会在zabbix_server.log中写入一行包含删除信息的摘要日志（README 的 How it works 一节明确说明了这一点）。
模板中的主监控项Syslog Housekeeping属于log类型（Zabbix agent active 主动检查），按 1 秒间隔读取日志文件，并用正则{$REGEXLOG}从日志流中筛出 housekeeping 摘要行。
其余 8 个监控项全部是依赖项（Dependent item），它们不直接采集数据，而是以Syslog Housekeeping为父项（master item），通过各自的正则预处理步骤，从父项捕获的那一行日志中"切出"对应的数值片段。
依赖项更新间隔为0，意味着与父项同步刷新，不额外消耗轮询资源，数据到达时机完全跟随 housekeeping 的调度节奏（housekeeping 默认每小时执行一次，间隔由zabbix_server.conf中的HousekeepingFrequency参数控制）。

从 6.0 模板文件 template_zabbix_monitor_housekeeper.yaml 中可以清晰看到这一主从结构：父项Syslog Housekeeping使用键log[{$PATHLOG},"{$REGEXLOG}",,,skip,,]（见 YAML L255-L266），而 8 个依赖项全部通过master_item.key指向这一日志项。

log[] 键参数拆解

主项的键是理解模板的钥匙：

log[{$PATHLOG},"{$REGEXLOG}",,,skip,,]

Zabbixlog[]键的完整参数形式为log[file,<regex>,<encoding>,<maxlines>,<mode>,<output>,<stderr>,<maxproclines>]，模板中的用法对应：

参数位	值	含义
file	`{$PATHLOG}`	要读取的日志文件路径
regex	`"{$REGEXLOG}"`	匹配正则（用引号包裹，避免特殊字符被解析歧义）
encoding	（空）	使用默认编码
maxlines	（空）	无行数上限
mode	`skip`	只处理匹配正则的新日志行，跳过不匹配的行
output	（空）	默认输出
stderr	（空）	不处理 stderr

其中mode=skip是保证解析质量的关键：它确保只有命中 housekeeping 正则的日志行才会成为父项的值，其余日志（连接、告警、同步等）一律被丢弃，从而让依赖项的提取正则始终面对"干净的输入"。

快速上手：导入、链接与等待采集

README 的使用说明非常简洁，实际操作只需三步：

导入模板：登录 Zabbix Web 界面，进入Configuration → Templates，点击右上角Import，选择模板文件导入。Zabbix 5.4/6.0 使用 YAML 格式（6.0 模板），Zabbix 5.0 使用 XML 格式（5.0 模板），按自己的版本选择对应文件即可。
链接主机：把模板链接到运行 Zabbix Server 的那台主机（即模板作者所说的Host "Zabbix server"）。注意该模板依赖 Zabbix agent 的主动检查（active checks），因此目标主机上必须运行着能与 Server 正常通信的 Zabbix agent，且 Server 端已启用主动检查。
等待采集：链接后无需手动触发，监控项会按 housekeeping 自身的执行计划采集。housekeeping 默认每小时执行一次，因此首个完整数据点可能需要等待下一次 housekeeping 运行（如果是刚刚完成过清理的周期，则很快就有数据）。可在Monitoring → Latest data中按主机过滤，观察Records deleted in *与Duration of the last executed Housekeeper等项是否已经出值。

模板本身没有配置模板链接（Template links）和自动发现规则（Discovery rules），也没有内置触发器（Triggers）——README 的对应章节均为 "There are no ..."，因此导入后只需关注监控项与图表即可。

宏配置详解：日志路径与匹配正则

模板通过两个文本宏（Text macro）实现核心参数化，默认值定义在模板的macros段（见 YAML L271-L279）：

宏名	描述	默认值	类型
`{$PATHLOG}`	`zabbix_server.log`的路径	`/var/log/zabbix/zabbix_server.log`	Text macro
`{$REGEXLOG}`	匹配 housekeeping 日志行的正则	`.deleted.[0-9]+ hist/trends.*`	Text macro

两个宏的调参场景非常明确：

{$PATHLOG}：当 Zabbix Server 的日志文件不在默认路径时（例如自定义了LogFile配置、日志被 logrotate 归档或重定向到其他目录），只需在主机或模板级覆盖该宏即可，无需改动监控项。
{$REGEXLOG}：用于在日志流中"锁定"housekeeping 摘要行。默认值.*deleted.*[0-9]+ hist/trends.*要求行内同时出现deleted、数字与hist/trends片段。如果你的 Zabbix 版本输出的 housekeeping 日志行格式不同（见下文"注意事项"），应优先调整此宏，而不是改动主项键。

需要留意的是：README 宏列表一节中因 Markdown 渲染显示为{$ PATHLOG}、{$ REGEXLOG}的写法是排版伪影，实际宏名不带空格，以宏表格及 YAML 中的定义为准。

监控项全解析：主项 + 8 个依赖项

模板共定义 9 个监控项，README 的 Items collected 表格逐一列出。下面结合 6.0 YAML 模板的预处理配置，给出完整清单与解析逻辑。

父项：Syslog Housekeeping

属性	值
名称	Syslog Housekeeping
类型	Zabbix agent (active)
键	`log[{$PATHLOG},"{$REGEXLOG}",,,skip,,]`
更新间隔	1s
值类型	LOG
历史/趋势保留	0（不存储数据，仅作解析源）

该日志项本身不保存任何历史数据（history: '0'、trends: '0'），它的角色纯粹是"管道上游"——以 1 秒间隔持续扫描日志，把命中{$REGEXLOG}的行提供给下游依赖项。这样做既保证了及时性，又不让日志文本占用数据库空间。

8 个依赖项：正则提取对照

所有依赖项的键前缀均为dep.housekeeper.*，delay: '0'（与父项同步），历史保留 7 天、趋势保留 120 天。每个依赖项都配置了一个REGEX预处理步骤，格式为参数1=提取正则、参数2=\1（输出第一个捕获组），并统一配置error_handler: CUSTOM_VALUE、error_handler_params: '-1'——即当正则无法匹配时输出-1，避免空值污染图表与后续计算。

监控项名称	键	提取正则	说明
Records deleted in Hist/Trends	`dep.housekeeper.histtrends`	`deleted (.*) hist`	从`deleted`与`hist`之间取值（见 YAML L167-L187）
Records deleted in Problems	`dep.housekeeper.problems`	`events, (.*) problems`	取`events,`与`problems`之间的值
Records deleted in Items-Triggers	`dep.housekeeper.itemstriggers`	`, (.*) items/triggers`	取`,`与`items/triggers`之间的值
Records deleted in Events	`dep.housekeeper.events`	`triggers, (.*) events`	取`triggers,`与`events`之间的值
Records deleted in Audit	`dep.housekeeper.audit`	`alarms, (.*) audit`	取`alarms,`与`audit`之间的值
Records deleted in Sessions	`dep.housekeeper.sessions`	`problems, (.*) sessions`	取`problems,`与`sessions`之间的值
Records deleted in Alarms	`dep.housekeeper.alarms`	`sessions, (.*) alarms`	取`sessions,`与`alarms`之间的值（见 YAML L76-L97）
Duration of the last executed Housekeeper	`dep.housekeeper.duration`	`records in (.*) sec`	取`records in`与`sec`之间的耗时秒数（见 YAML L121-L143）

由上述正则片段的排列顺序可以推断，模板期望捕获的 housekeeping 摘要行近似为单行、按固定顺序罗列各表删除数量、以耗时收尾的结构，大致形如：

housekeeper deleted "N" hist/trends, "N" items/triggers, "N" events, "N" problems, "N" sessions, "N" alarms, "N" audit records in "N.NN" sec

每个依赖项的正则就像"探针"，锚定前后两个固定关键字，取出夹在中间的数字。需要注意：各版本 Zabbix 的 housekeeping 日志措辞与顺序可能存在差异，这是模板对版本敏感的根源所在（详见"注意事项"）。

两个值得单独说明的细节：

Duration of the last executed Housekeeper的value_type为FLOAT，预处理正则records in (.*) sec提取出带小数的秒数；同时配置了units: uptime，Zabbix 会将其渲染为1d 2h 3m 4s这类人类可读的时长格式，非常适合直接看图。
所有依赖项在提取失败时都会输出-1。如果zabbix_server.log中暂时没有新的 housekeeping 行，父项没有新值，依赖项则保持上一次的值；而一旦日志行格式与正则不匹配，你会看到-1——这是排查"为什么没有数据"时最直接的信号。

内置图表：Duration 与 Metrics

模板自带两张图表，导入后无需额外配置即可在Monitoring → Graphs中查看：

Housekeeper - Duration：单序列图，展示dep.housekeeper.duration，颜色1A7C11，绘制在右侧 Y 轴（见 YAML L280-L291）。用于观察每次清理耗时随数据量增长的变化趋势。
Housekeeper - Metrics：多序列组合图，包含 7 个删除记录项（alarms、audit、events、histtrends、itemstriggers、problems、sessions），全部以虚线（DASHED_LINE）绘制、各自分配独立颜色，Y 轴最小值固定（ymin_type_1: FIXED）（见 YAML L293-L351）。这张图能直观呈现每次 housekeeping 各表删除量的分布，帮助判断哪张表的数据膨胀最快、清理压力最大。

源码级细节：从 YAML 导出文件看模板实现

阅读 template_zabbix_monitor_housekeeper.yaml 能获得 README 之外的实现级信息：

导出元数据：文件头声明zabbix_export.version: '6.0'，导出日期为2021-11-21T22:04:36Z，模板归属于Templates/Custom分组，模板内部名称为Housekeeping Metrics（uuid: 543f342b117d4f9da2442c9bc59316f8）。
模板级标签：模板带Zabbix: Housekeeping标签；监控项按职责分为两套Application标签——主项为01 - Housekeeping - Log，8 个依赖项统一为02 - Housekeeping - Metrics。这种标签设计便于在 Latest data 中按标签快速过滤，也体现了"日志捕获层 / 指标解析层"的分层组织思路。
数据保留策略：依赖项统一history: 7d、trends: 120d，与 Zabbix 对这类低频指标的常规建议一致——housekeeping 每小时最多产生一个数据点，7 天历史足以覆盖告警与近期回溯需求。
版本文件差异：仓库按 Zabbix 大版本分目录存放：5.0/ 提供 XML 导出（适用于 Zabbix 5.0 的旧式导入格式），5.4/ 与 6.0/ 提供 YAML 导出；三份 README 的监控项清单与宏定义完全一致，说明模板逻辑在 5.0 到 6.0 之间保持了兼容与稳定。

注意事项与使用限制

结合 README 声明与实现细节，落地使用前务必确认以下几点：

表分区环境不适用：若数据库采用表分区并按分区 DROP 清理过期数据，housekeeper 不会产生删除摘要日志，模板采集不到任何有效指标。这是模板官方明确标注的边界。
日志行格式随版本变化：模板的提取正则链（deleted ... hist/trends、events, ... problems、records in ... sec等）是针对特定日志措辞设计的。不同 Zabbix 版本可能改写 housekeeping 日志的措辞或顺序，导致部分依赖项输出-1。部署前建议先人工查看zabbix_server.log中真实的 housekeeping 行，若格式不符，优先调整{$REGEXLOG}，再逐项核对 8 个依赖项的预处理正则。
依赖主动检查：主项是Zabbix agent (active)类型，请确保目标主机 agent 配置了ServerActive且能正常被 Server 拉取主动检查结果。
默认日志路径：宏{$PATHLOG}默认指向/var/log/zabbix/zabbix_server.log，自定义了日志路径的环境需覆盖该宏。
无内置触发器：模板不包含触发器，若希望"某次清理删除了异常多的记录"或"housekeeping 耗时异常增长"时产生告警，需要基于上述 9 个监控项自行创建触发器表达式。

结语

Housekeeping Metrics 模板为 Zabbix 运维提供了一个"零额外脚本"的 housekeeping 可观测性方案：它复用 Zabbix 自带的log[]主动检查能力捕获日志，再以依赖项 + 正则预处理完成结构化解析，最终以指标和图表的形式呈现每次数据清理的规模与耗时。理解其"主项捕获、依赖项解析"的架构，以及{$PATHLOG}、{$REGEXLOG}两个宏与各提取正则的对应关系，你就能在各类 Zabbix 版本环境中快速部署，并在日志格式变化时自行校准模板，让 housekeeping 从"黑盒"变成可量化、可追踪的运维数据。