Zabbix SMART by Zabbix agent 2 模板实战:基于 smartctl 的磁盘健康监控与自动发现

原创2026-10-09 12:59:281,757 阅读
文章标签:运维指标监控可观测性告警监控大盘APM日志分析后端前端消息队列高可用分布式数据库

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 依次执行:

  1. Self-test:当 {#DISKTYPE} 为 nvme 时,名中含 "Self-test" 的监控项不创建(NVMe 盘不适用 ATA 自检语义);
  2. Not NVMe:当 {#DISKTYPE} 不是 nvme 时,名匹配 Media|Percentage|Critical 的监控项不创建(这些字段仅 NVMe 提供);
  3. 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} 参数的由来。

联动运维建议

基于模板机制,以下实践点值得在落地时关注:

  1. 发现频率:磁盘发现 LLD 轮询间隔为 1h,物理换盘后最长 1 小时内完成新盘发现;结合 "Disk has been replaced" 触发器可感知序列号变化。
  2. 宏按主机覆盖:同一模板可链接到多台主机,通过主机级覆盖 {$SMART.DISK.NAME.NOT_MATCHES} 排除不需要监控的盘(如系统盘),通过覆盖温度阈值适配不同机房散热条件。
  3. 过滤器与属性发现的配合:{$SMART.DISK.NAME.MATCHES} / {$SMART.DISK.NAME.NOT_MATCHES} 同时作用于磁盘发现与属性发现,可用于整体裁剪监控范围。
  4. 依赖型监控项的性能收益:所有属性均从单一 smart.disk.get 主项派生,避免了每块盘、每个属性各执行一次 smartctl,配合 Discard unchanged 预处理显著降低 agent 与 server 之间的数据流量。
  5. 版本约束:模板需 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/ 的插件源码与测试样本深入研读。

登录后查看全文
zabbix