Zabbix SMART by Zabbix agent 2 模板实战:基于 smartctl 的磁盘健康监控与自动发现
Zabbix SMART by Zabbix agent 2 模板实战:基于 smartctl 的磁盘健康监控与自动发现
导读
本文围绕官方仓库中的 SMART by Zabbix agent 2 监控模板(templates/server/smart_agent2/README.md),系统讲解如何借助 Zabbix agent 2 内置的 SMART 插件与 Smartmontools 的 smartctl 工具,在不依赖任何外部脚本的前提下,对 HDD、SSD、NVMe 磁盘实现 S.M.A.R.T. 属性的自动发现、指标采集、预处理与告警触发。读完本文,你将掌握模板的安装前提、agent 2 插件参数配置、宏覆盖与 LLD 过滤技巧、磁盘与属性两级自动发现的内部机制,以及模板内建触发器(温度告警、自检失败、NVMe 寿命、smartctl 退出状态位掩码)的完整语义。
模板概览:零脚本的 SMART 监控方案
SMART by Zabbix agent 2 是仓库 templates/server/ 目录下官方模板组 "Templates/Server hardware" 中的成员(见 template_module_smart_agent2.yaml),用于监控物理磁盘的 S.M.A.R.T.(Self-Monitoring, Analysis and Reporting Technology)属性。其核心设计目标与特点:
- 无外部脚本:数据采集全部由 Zabbix agent 2 内置的 SMART 插件(源码位于 src/go/plugins/smart/)完成,插件通过调用
smartctl可执行程序获取 SMART 数据。 - 两级 LLD 自动发现:
Disk discovery(磁盘发现)规则发现所有开启 S.M.A.R.T. 的 HDD、SSD、NVMe 磁盘;Attribute discovery(属性发现)规则针对每块磁盘预定义了厂商特定属性,只有当属性实际存在时才会被发现并创建监控项。 - 版本依赖:模板依赖 Zabbix agent 2 5.0 及以上版本与 Smartmontools 7.1 及以上版本(模板本身要求 Zabbix Server/Frontend 为 8.0 及以上)。
- 适配 RAID 场景:模板中
smart.disk.get[{#PATH},"{#RAIDTYPE}"]的第二个参数专门用于传递 RAID 类型(如megaraid,0),覆盖通过 RAID 控制器访问磁盘的场景。
从 plugin.go 的常量定义可以看到,插件注册的核心指标正是模板用到的 smart.disk.discovery、smart.attribute.discovery 与 smart.disk.get 三个。
安装前提与 Setup 步骤
模板 README 给出的部署前提(Requirements)为 Zabbix 8.0 及以上版本。实测版本(Tested versions)为 Smartmontools 7.1 及以上。部署前需按官方《Templates out of the box》指引完成模板导入与主机链接。具体 Setup 分为三步:
1. 安装 Zabbix agent 2 与 Smartmontools
在目标主机上安装 Zabbix agent 2(5.0+)与 Smartmontools 7.1 或更新版本。Smartmontools 提供 smartctl 命令行工具,是插件获取 SMART 数据的底层依赖。
2. 配置 smartctl 可执行文件路径
确保 smartctl 可执行文件的路径被正确指定。两种做法:
- 在 agent 2 配置中显式给出完整路径;
- 或将
smartctl所在目录加入系统环境变量PATH(Linux 与 Windows 均适用)。
Linux 示例(写入 smart.conf 或主配置文件 zabbix_agent2.conf):
Plugins.Smart.Path=/usr/sbin/smartctl
Windows 示例:
Plugins.Smart.Path="C:\Program Files\smartctl\smartctl.exe"
从配置注释可以确认,Plugins.Smart.Path 为可选参数,默认值为 smartctl(即依赖 PATH 环境变量定位可执行文件)。此外插件还支持两个超时参数:
| 参数 | 含义 | 范围 | 默认值 |
|---|---|---|---|
Plugins.Smart.ConnectionTimeout |
等待单次 smartctl 命令执行完成的最大秒数 |
1–30 | 继承 agent 全局超时 |
Plugins.Smart.Timeout |
旧版回退超时值,仅用于来自 Zabbix Server 7.0 之前版本发起的请求 | 1–30 | 继承 agent 全局超时 |
值得说明的是,Plugins.Smart.Timeout 在插件 README.md 中已标注为 deprecated(已弃用),新部署建议使用 ConnectionTimeout。
3. 为 zabbix 用户授权 smartctl(仅 Linux)
Windows 无需此步骤。Linux 下 smartctl 读取磁盘 SMART 数据通常需要管理员权限,因此需要让 agent 2 以无密码方式执行该命令。模板 README 给出的标准做法:
- 运行
visudo编辑sudoers文件:
sudo visudo
- 添加以下授权行并保存:
zabbix ALL=(ALL) NOPASSWD:/usr/sbin/smartctl
关于插件更多参数细节,可参见仓库内的插件说明文档 src/go/plugins/smart/README.md 与示例配置 smart.conf。
模板宏(Macros)说明
模板内置 5 个宏,全部支持在主机级别覆盖或在模板级别覆盖,用于控制发现行为与告警阈值:
| 宏 | 描述 | 默认值 |
|---|---|---|
{$SMART.DISK.DISCOVERY.TYPE} |
控制 SMART 磁盘的发现方式,仅允许 name 或 id 两个取值 |
name |
{$SMART.TEMPERATURE.MAX.WARN} |
温度告警阈值,用于触发器表达式 | 50 |
{$SMART.TEMPERATURE.MAX.CRIT} |
温度严重阈值,用于触发器表达式 | 65 |
{$SMART.DISK.NAME.MATCHES} |
磁盘属性发现与磁盘发现过滤器的包含条件(正则) | ^.*$ |
{$SMART.DISK.NAME.NOT_MATCHES} |
磁盘属性发现与磁盘发现过滤器的排除条件(正则) | CHANGE_IF_NEEDED |
从 template_module_smart_agent2.yaml 的宏定义可见其约束:
{$SMART.DISK.DISCOVERY.TYPE}被声明为 LIST 类型,仅提供name/ID两个选项——对应插件smart.disk.discovery中按磁盘名称还是按 SMART ID 进行扫描;{$SMART.TEMPERATURE.MAX.WARN}与{$SMART.TEMPERATURE.MAX.CRIT}均带数值正则校验^-?([0-9]+|(([0-9]+)\.([0-9]+)))$,支持整数与小数,可配置为负数;- 两个磁盘名称过滤宏被归类到 "Filters" 配置分组,其中
NOT_MATCHES默认值CHANGE_IF_NEEDED提醒用户在接入真实环境后按需修改排除规则。
磁盘发现(Disk discovery)与监控项原型
LLD 规则
| 名称 | 描述 | 类型 | Key |
|---|---|---|---|
| Disk discovery | 发现 SMART 磁盘 | Zabbix agent | smart.disk.discovery[{$SMART.DISK.DISCOVERY.TYPE}] |
该 LLD 规则在 YAML 中配置的轮询间隔为 1h(template_module_smart_agent2.yaml),并使用两个过滤器条件(AND 语义):
{#NAME}匹配{$SMART.DISK.NAME.MATCHES}(默认^.*$,即全部纳入);{#NAME}不匹配{$SMART.DISK.NAME.NOT_MATCHES}(默认CHANGE_IF_NEEDED)。
插件执行该发现时(对应 handler.go 中注册的 diskDiscovery 处理函数),会返回包含 {#NAME}、{#DISKTYPE}(如 nvme、ata、sat、scsi 等)、{#MODEL}、{#SN}、{#PATH}、{#RAIDTYPE} 以及 {#ATTRIBUTES} 的 JSON 数组,这些宏在后续监控项原型中被大量引用。
监控项原型(Item prototypes)
磁盘发现规则下的监控项原型全部以 smart.disk.get[{#PATH},"{#RAIDTYPE}"] 作为主监控项(master item),其余均为依赖型监控项(Dependent item),通过 JSON Path 预处理从主项返回的 JSON 中提取字段,从而避免对每块磁盘反复执行 smartctl。
| 监控项原型 | 类型 | Key | 预处理要点 |
|---|---|---|---|
| [{#NAME}]: Smartctl error | Dependent | smart.disk.error[{#NAME}] |
$.error;Discard unchanged 1h |
| [{#NAME}]: Get disk attributes | Zabbix agent | smart.disk.get[{#PATH},"{#RAIDTYPE}"] |
主项,直接调用插件 |
| [{#NAME}]: Device model | Dependent | smart.disk.model[{#NAME}] |
$.model_name;6h |
| [{#NAME}]: Serial number | Dependent | smart.disk.sn[{#NAME}] |
$.serial_number;6h |
| [{#NAME}]: Self-test passed | Dependent | smart.disk.test[{#NAME}] |
$.self_test_passed + JavaScript 映射 + 6h |
| [{#NAME}]: Self-test in progress | Dependent | smart.disk.test.progress[{#NAME}] |
$.self_test_in_progress + JavaScript 映射 + 6h |
| [{#NAME}]: Temperature | Dependent | smart.disk.temperature[{#NAME}] |
$.temperature,单位 °C;6h |
| [{#NAME}]: Power on hours | Dependent | smart.disk.hours[{#NAME}] |
$.power_on_time;6h |
| [{#NAME}]: Percentage used | Dependent | smart.disk.percentage_used[{#NAME}] |
$.percentage_used;6h |
| [{#NAME}]: Critical warning | Dependent | smart.disk.critical_warning[{#NAME}] |
$.critical_warning;6h |
| [{#NAME}]: Media errors | Dependent | smart.disk.media_errors[{#NAME}] |
$.media_errors;6h |
| [{#NAME}]: Exit status | Dependent | smart.disk.es[{#NAME}] |
$.exit_status;6h |
需要说明的细节:
- Power on hours 的原始值语义:
$.power_on_time的原始值在不同厂商盘上可能以小时、分钟或秒计;官方文档对机械盘总预期寿命的定义是"完美状态下的 5 年"(24/7 模式即 1825 天 / 43800 小时);部分 2005 年之前的盘该值可能不规则增长或周期性地"回绕"归零。 - Percentage used 的 NVMe 语义:该字段是厂商对 NVM 子系统寿命消耗百分比的估计,100 表示标称寿命已耗尽(但并不必然代表盘已故障);数值允许超过 100,超过 254 的部分统一表示为 255;该值每个加电小时更新一次(控制器非睡眠状态时)。
- Self-test 的 JavaScript 预处理:模板将 JSON 的
true/false/null映射为数值 1/2/3,再配合值映射表Smart self-test(0=Undefined,1=True,2=False,3=Null)存储为可读文本。 - Exit status 的位掩码语义:
$.exit_status是 smartctl 退出状态的十进制位掩码,各 bit 含义(主要针对 ATA 盘,部分对 SCSI 同样适用):
| Bit | 十进制 | 含义 |
|---|---|---|
| 0 | 1 | 命令行解析失败 |
| 1 | 2 | 设备打开失败(未返回 IDENTIFY DEVICE 结构,或设备处于低功耗模式) |
| 2 | 4 | 某条 SMART/ATA 命令执行失败,或 SMART 数据结构校验和错误 |
| 3 | 8 | SMART 状态检查返回 "DISK FAILING" |
| 4 | 16 | 存在 prefail 属性 <= 阈值 |
| 5 | 32 | SMART 状态为 "DISK OK",但发现部分(usage 或 prefail)属性历史上曾 <= 阈值 |
| 6 | 64 | 设备错误日志包含错误记录 |
| 7 | 128 | 设备自检日志包含错误记录(仅 ATA;被更新的成功扩展自检覆盖的失败自检会被忽略) |
该位掩码正是模板中 8 个 exit-status 触发器的判断基础(见下文)。
属性发现(Attribute discovery)与厂商特定属性
除磁盘级监控项外,模板还通过属性发现为每块磁盘按预定义列表发现厂商特定属性,只有当属性实际存在于该盘时才会创建监控项。这些属性原型同样以 smart.disk.get[{#PATH},"{#RAIDTYPE}"] 为主项,通过 JSON Path 提取 .value 字段(如 $.raw_read_error_rate.value),并统一采用 6 小时 Discard unchanged 去重:
| 属性监控项原型 | Key | 属性含义 |
|---|---|---|
| Raw_Read_Error_Rate | smart.disk.attribute.raw_read_error_rate[{#NAME}] |
读取数据时的硬件读错误率;原始值结构随厂商而异,某些盘正常运行时该数值也会增长,未必代表错误 |
| Spin_Up_Time | smart.disk.attribute.spin_up_time[{#NAME}] |
主轴从 0 RPM 到完全就绪的平均起转时间(毫秒) |
| Start_Stop_Count | smart.disk.attribute.start_stop_count[{#NAME}] |
主轴启停次数累计(关机再开机与从休眠唤醒均会计数) |
| Power_Cycle_Count | smart.disk.attribute.power_cycle_count[{#NAME}] |
完整电源开/关循环次数 |
| Reported_Uncorrect | smart.disk.attribute.reported_uncorrect[{#NAME}] |
无法用硬件 ECC 恢复的错误计数 |
| Seek_Error_Rate | smart.disk.attribute.seek_error_rate[{#NAME}] |
磁头寻道错误率;原始值结构因厂商而异,部分盘正常运行时也可能增长 |
| Bad_Block_Rate | smart.disk.attribute.bad_block_rate[{#NAME}] |
已用保留块占全部保留块的百分比 |
| Program_Fail_Count_Chip | smart.disk.attribute.program_fail_count_chip[{#NAME}] |
自盘部署以来闪存编程操作失败的累计次数 |
| Reallocated_Sector_Ct | smart.disk.attribute.reallocated_sector_ct[{#NAME}] |
重映射扇区计数(磁盘发现的属性) |
这些属性原型在 YAML 中默认以 discover: NO_DISCOVER 存在,是否创建取决于 template_module_smart_agent2.yaml 中定义的 LLD overrides(覆盖规则)——共 11 条、按步骤 step 1–11 依次执行:
- Self-test:当
{#DISKTYPE}为nvme时,名中含 "Self-test" 的监控项不创建(NVMe 盘不适用 ATA 自检语义); - Not NVMe:当
{#DISKTYPE}不是nvme时,名匹配Media|Percentage|Critical的监控项不创建(这些字段仅 NVMe 提供); - Raw_Read_Error_Rate / Spin_Up_Time / Start_Stop_Count / Power_Cycle_Count / Reported_Uncorrect / Seek_Error_Rate / Bad_Block_Rate / Program_Fail_Count_Chip / Reallocated_Sector_Ct:当
{#ATTRIBUTES}中实际包含对应属性名时,才DISCOVER创建该属性监控项。
这一机制正是模板 README 所述"Attribute discovery LLD rule have pre-defined Vendor Specific Attributes for each disk, and will be discovered if attribute is present"(属性发现规则为每块磁盘预定义厂商特定属性,属性存在时才会被发现)的具体实现。
触发器原型(Trigger prototypes)与告警语义
磁盘替换与自检
| 触发器 | 表达式 | 严重性 | 说明 |
|---|---|---|---|
| SMART: [{#NAME}]: Disk has been replaced | last(...smart.disk.sn[{#NAME}],#1)<>last(...smart.disk.sn[{#NAME}],#2) and length(last(...smart.disk.sn[{#NAME}]))>0 |
Info | 序列号发生变化(且当前值非空)即告警,需手动关闭(Manual close: Yes),避免磁盘因故障被更换后问题自动恢复 |
| SMART: [{#NAME}]: Disk self-test is not passed | last(...smart.disk.test[{#NAME}])=2 and last(...smart.disk.test.progress[{#NAME}])=2 |
High | 自检结果为 False 且当前未在进行中(即已结束的自检失败) |
温度与 NVMe 寿命
| 触发器 | 表达式 | 严重性 | 依赖 |
|---|---|---|---|
| SMART: [{#NAME}]: Average disk temperature is too high | avg(...smart.disk.temperature[{#NAME}],5m)>{$SMART.TEMPERATURE.MAX.WARN} |
Warning | 依赖 "temperature is critical" 触发器 |
| SMART: [{#NAME}]: Average disk temperature is critical | avg(...smart.disk.temperature[{#NAME}],5m)>{$SMART.TEMPERATURE.MAX.CRIT} |
Average | — |
| SMART: [{#NAME}]: NVMe disk percentage using is over 90% of estimated endurance | last(...smart.disk.percentage_used[{#NAME}])>90 |
Average | — |
温度告警采用 5 分钟平均值(avg(...,5m)),可有效过滤瞬时温度尖峰;Warning 触发器声明了对 Critical 触发器的依赖,避免同盘同时出现重复告警。
smartctl 退出状态位掩码触发器
模板针对 exit status 的每一位(bit0–bit7)各定义一个 High 严重性触发器,表达式遵循同一模式(以 bit0 为例):
( count(/SMART by Zabbix agent 2/smart.disk.es[{#NAME}],#2) = 1 and bitand(last(/SMART by Zabbix agent 2/smart.disk.es[{#NAME}]),1) = 1 ) or ( bitand(last(/SMART by Zabbix agent 2/smart.disk.es[{#NAME}]),1) = 1 and bitand(last(/SMART by Zabbix agent 2/smart.disk.es[{#NAME}]),1) > bitand(last(/SMART by Zabbix agent 2/smart.disk.es[{#NAME}],#2),1) )
其语义为:首次出现该 bit 置位(count(...,#2)=1)或 该 bit 相比上次采样由 0 变为 1(当前值 > 上次值),即"新出现问题"时触发,而不是在问题持续存在时反复告警;所有此类触发器均为手动关闭。对应的 8 个触发器与位掩码含义一一对应:
| 触发器 | 判定 bit |
|---|---|
| Command line did not parse | bit0 (1) |
| Device open failed | bit1 (2) |
| Some command to the disk failed | bit2 (4) |
| Check returned "DISK FAILING" | bit3 (8) |
| Some prefail Attributes <= threshold | bit4 (16) |
| Some Attributes have been <= threshold | bit5 (32) |
| Error log contains records | bit6 (64) |
| Self-test log contains records | bit7 (128) |
底层实现:插件如何工作
模板之上的数据通路由 Zabbix agent 2 的 SMART 插件承载。从 plugin.go 可以看到:
- 插件注册了三个指标(metric):
smart.disk.discovery(带searchType参数,即name/id)、smart.attribute.discovery、smart.disk.get(带path、raidType两个参数),对应实现函数分别为diskDiscovery、attributeDiscovery、diskGet(handler.go)。 - 每次指标请求都会先经过
validateExport校验:既校验参数数量,也校验磁盘路径参数——plugin.go 中的pathRegex(^(?:\s*-|'*"*\s*-))会拒绝以空白/引号后跟-开头的"磁盘描述符",防止把插件参数误用为smartctl命令行选项(输入清洗)。 - 插件的
Export方法对参数求值后调用对应 handler,任何执行错误都会包装为zbxerr.ErrorCannotFetchData返回。
插件的控制器与测试数据位于 src/go/plugins/smart/ 目录:
controller.go/smartfs_linux.go/smartfs_darwin.go/smartfs_windows.go:负责跨平台调用smartctl与解析输出(Linux 默认走/usr/sbin/smartctl,macOS、Windows 有各自实现);- testdata/ 中包含了丰富的 JSON 测试样本:
discovery/下的 Linux/macOS/Windows 扫描结果(含 RAID 扫描macos_raid_scan.json、mixed_devices_scan.json、windows_nvme_scan.json等)、exit_status/下按位掩码构造的各类错误样本(command_line_error.json、device_open_error.json、self_test_error_scsi.json、success_nvme.json等),以及controller/device/下按控制器类型(3ware、areca、cciss、csmi、sat、scsi)划分的磁盘 JSON——这些样本直接印证了插件对 RAID 控制器、SCSI 与 NVMe 设备的解析能力,也解释了模板中{#RAIDTYPE}参数的由来。
联动运维建议
基于模板机制,以下实践点值得在落地时关注:
- 发现频率:磁盘发现 LLD 轮询间隔为 1h,物理换盘后最长 1 小时内完成新盘发现;结合 "Disk has been replaced" 触发器可感知序列号变化。
- 宏按主机覆盖:同一模板可链接到多台主机,通过主机级覆盖
{$SMART.DISK.NAME.NOT_MATCHES}排除不需要监控的盘(如系统盘),通过覆盖温度阈值适配不同机房散热条件。 - 过滤器与属性发现的配合:
{$SMART.DISK.NAME.MATCHES}/{$SMART.DISK.NAME.NOT_MATCHES}同时作用于磁盘发现与属性发现,可用于整体裁剪监控范围。 - 依赖型监控项的性能收益:所有属性均从单一
smart.disk.get主项派生,避免了每块盘、每个属性各执行一次smartctl,配合 Discard unchanged 预处理显著降低 agent 与 server 之间的数据流量。 - 版本约束:模板需 Zabbix 8.0+;若接入旧版 Server,请注意
Plugins.Smart.Timeout仅作为 7.0 之前请求的回退超时使用。
如需反馈模板问题,可通过 Zabbix 官方支持渠道提交;模板本身由官方 "Templator" 工具生成,对应 YAML 源文件 template_module_smart_agent2.yaml 与 README 均位于本仓库 templates/server/smart_agent2/ 目录,可结合 src/go/plugins/smart/ 的插件源码与测试样本深入研读。