指标监控可观测性告警运维【免费下载链接】zabbixReal-time monitoring of IT components and services, such as networks, servers, VMs, applications and the cloud.项目地址https://gitcode.com/gh_mirrors/zabbix2/zabbix点击查看免费下载本篇技术指南以 Zabbix 官方仓库中的 SMART by Zabbix agent 2 active 模板说明 为主线系统讲解如何在 Zabbix 8.0 中通过 Zabbix agent 2 的主动active模式借助 Smartmontools 的smartctl工具实现 HDD、SSD、NVMe 磁盘 S.M.A.R.T. 健康状态的全自动监控。读完本文你将掌握模板的部署步骤、五个核心宏的用法、磁盘发现与属性发现 LLD 规则、全部监控项与触发器的含义以及底层 SMART 插件Go 实现的工作原理可直接落地一套无需任何外部脚本的磁盘监控方案。模板概述与工作原理该模板的设计目标是开箱即用只要正确安装了 Zabbix agent 2 与 Smartmontools无需编写任何外部脚本即可自动完成磁盘发现、属性采集、告警触发与仪表盘展示。其工作机制可以概括为两个层次发现层LLDsmart.disk.discovery低级别发现规则会找出系统中所有启用了 S.M.A.R.T. 的 HDD、SSD 与 NVMe 磁盘随后smart.attribute.discovery属性发现为每块磁盘携带预定义的厂商特定属性Vendor Specific Attributes只有当磁盘上真实存在该属性时才会被发现并启用对应监控项。采集层Dependent items模板以smart.disk.get[{#PATH},{#RAIDTYPE}]作为主采集项master item一次性拉取单块磁盘的完整 SMART JSON 数据其余几十个监控项均为依赖项Dependent item通过 JSON Path 预处理从主采集项的结果中提取具体字段配合心跳去重Discard unchanged with heartbeat机制降低数据冗余。从模板的完整定义文件 template_module_smart_agent2_active.yaml 可以看到该模板归属于Templates/Server hardware模板组由官方模板工具 Templator 生成并带有classstorage、targethdd、targetssd等标签便于在 Zabbix 8.0 的模板库中检索和复用。环境与版本要求根据模板说明使用前提如下Zabbix 版本Zabbix 8.0 及更高版本模板导出格式为zabbix_exportversion8.0。Zabbix agent 2 版本5.0 及更高版本即可采集指标但模板本体需要 8.0 前端支持。Smartmontools 版本7.1 及以上模板已在 Smartmontools 7.1 及更高版本上验证通过用于提供smartctl命令行工具。操作系统模板说明同时覆盖 Linux 与 Windows 平台。注意模板明确要求通过Zabbix agent 2主动模式运行因此在配置主机时需要为主机添加类型为Zabbix agent主动的接口并确保 agent 2 配置了正确的ServerActive参数。Zabbix 端应按官方Templates out of the box章节的通用流程导入模板并链接到主机。部署与配置Setup模板的部署流程共三步全部在 agent 2 所在主机上完成。1. 安装依赖在目标主机上安装 Zabbix agent 2 与 Smartmontools 7.1 或更新版本。以 LinuxDebian/Ubuntu 系为例apt-get install zabbix-agent2 smartmontoolsWindows 平台则安装官方 Zabbix agent 2 安装包与 Smartmontools 的 Windows 发行版。2. 指定 smartctl 可执行文件路径agent 2 的 SMART 插件需要调用smartctl因此必须让插件能找到该可执行文件。有两种方式任选其一在配置文件中显式指定完整路径推荐可避免 PATH 环境差异将smartctl所在目录加入系统 PATH 环境变量。配置文件zabbix_agent2.conf或插件专用配置smart.conf中的写法如下。Linux 示例Plugins.Smart.Path/usr/sbin/smartctlWindows 示例注意路径含空格需加引号Plugins.Smart.PathC:\Program Files\smartctl\smartctl.exe从源码看该参数定义于 config.go 的Options结构体Path string \conf:optional属于可选参数。若未配置插件会回退到在 PATH 中查找smartctl默认值即为smartctl。3. 授予 smartctl 的执行权限Linuxsmartctl读取磁盘 SMART 数据通常需要 root 权限而 agent 2 进程默认以zabbix用户运行。因此需要为zabbix用户配置免密 sudo 执行smartctl的权限Windows 平台不需要此步骤。先执行visudo编辑 sudoers 文件sudo visudo然后添加如下权限行并保存zabbix ALL(ALL) NOPASSWD:/usr/sbin/smartctl该行表示允许zabbix用户在任意主机上以任意用户身份、免密码执行/usr/sbin/smartctl这一个命令。此配置应严格限定在smartctl本身避免过度授权。插件级配置参数补充除Path外SMART 插件还提供两个超时参数详见 config.go 与 插件 README参数说明取值范围默认值Plugins.Smart.Pathsmartctl可执行文件路径任意路径smartctl依赖 PATHPlugins.Smart.Timeout等待 SMART 数据请求完成的最大秒数1–30 秒继承 agent 全局 TimeoutPlugins.Smart.ConnectionTimeout同上等待 SMART 数据请求完成的最大秒数1–30 秒继承 agent 全局 Timeout需要特别注意的是Plugins.Smart.Timeout在源码中已被标记为deprecated已弃用配置加载时若检测到该参数会输出Plugins.Smart.Timeout is deprecated的调试日志且仅当ConnectionTimeout未设置时才将其作为兼容回退值目前只服务于来自Zabbix Server 7.0 之前版本的请求。新配置应使用Plugins.Smart.ConnectionTimeout。示例Plugins.Smart.ConnectionTimeout10模板宏Macros模板共定义 5 个宏用于控制发现行为与告警阈值既可在模板级覆盖也可在具体主机上按需覆盖。在 Zabbix 8.0 中这些宏还带有界面配置元数据如ThresholdsFilters配置分区及输入校验正则。宏描述默认值{$SMART.DISK.DISCOVERY.TYPE}控制 SMART 磁盘的发现方式仅允许name或id两个取值name{$SMART.TEMPERATURE.MAX.WARN}温度告警Warning阈值用于触发器表达式可在主机级覆盖50{$SMART.TEMPERATURE.MAX.CRIT}温度严重Critical阈值用于触发器表达式可在主机级覆盖65{$SMART.DISK.NAME.MATCHES}磁盘发现与属性发现过滤器中的包含匹配正则^.*$匹配全部{$SMART.DISK.NAME.NOT_MATCHES}磁盘发现与属性发现过滤器中的排除匹配正则CHANGE_IF_NEEDED按需修改其中{$SMART.DISK.DISCOVERY.TYPE}直接对应插件smart.disk.discovery的参数源码 params.go 中该参数默认值为name并由SetValidator{Set: []string{name, id}}严格限定取值传入其他值会导致参数校验失败。取name时按设备名如/dev/sda扫描取id时按 SMART 设备 ID 扫描。温度宏的输入在模板中被配置了正则校验^-?([0-9]|(([0-9])\.([0-9])))$即允许负数、整数或小数可防止非法输入。{$SMART.DISK.NAME.MATCHES}/{$SMART.DISK.NAME.NOT_MATCHES}则被用在 Disk discovery 规则的过滤器中AND逻辑组合实现按磁盘名包含/排除特定磁盘。磁盘发现 LLD 规则模板只内置了一条 LLD 规则用于驱动整个监控体系名称描述类型键值Disk discovery发现 SMART 磁盘Zabbix agent主动smart.disk.discovery[{$SMART.DISK.DISCOVERY.TYPE}]规则属性来自模板 YAML更新间隔delay: 1h每小时扫描一次磁盘过滤器基于{#NAME}宏同时应用{$SMART.DISK.NAME.MATCHES}包含与{$SMART.DISK.NAME.NOT_MATCHES}排除两个条件。smart.disk.discovery返回的每个发现实体macro包括详见 插件 README 与 smart.go 的diskDiscovery实现{#NAME}磁盘名称或 SMART ID{#DISKTYPE}磁盘类型如nvme、ata、ssd、hdd{#MODEL}磁盘型号{#SN}序列号{#PATH}设备路径如/dev/sda{#RAIDTYPE}RAID 类型如megaraid,0不适用时为空{#ATTRIBUTES}磁盘上存在的 SMART 属性名列表空格分隔供属性发现覆盖规则使用。发现出的每块磁盘都会实例化一组监控项原型 触发器原型。监控项原型Item prototypesDisk discovery 下共定义了 21 个监控项原型分为两类1 个主动采集主项master itemsmart.disk.get[{#PATH},{#RAIDTYPE}]20 个依赖项Dependent item全部挂靠在该主项之上通过 JSON Path 从主项 JSON 中取值。主采集项Get disk attributes名称类型键值[{#NAME}]: Get disk attributesZabbix agent主动smart.disk.get[{#PATH},{#RAIDTYPE}]该主项由 agent 2 的 SMART 插件直接执行对 Linux 设备路径如/dev/sda调用smartctl -a path -j若{#RAIDTYPE}非空如 MegaRAID、3ware、areca 等控制器则追加-d raid_type参数例如smartctl -a /dev/sda -d megaraid,0 -j。注意参数中的{#PATH}前不能带-前缀插件源码 plugin.go 的validateParams会以正则^(?:\s|-|*\s*-)拒绝以-开头的设备描述符这是为了防止smartctl命令行参数注入。主项在模板中被配置为history: 0不保留历史、值类型 TEXT保存完整 JSON只作为依赖项的数据中转站。主项返回的 JSON 字段来自 smart.go 的setSingleDiskFields包括字段含义disk_type磁盘类型nvme / hdd / ssd 等firmware_version固件版本model_name型号serial_number序列号exit_statussmartctl 退出状态十进制位掩码errorsmartctl 输出的错误信息多个消息以逗号连接self_test_passed上次自检是否通过true/false/nullself_test_in_progress是否正在执行自检true/false/nulltemperature当前温度NVMe 取自健康日志ATA 取自温度传感器power_on_time累计通电小时数critical_warning控制器关键警告NVMe 专有ATA 恒为 0media_errors介质错误次数NVMe 专有ATA 恒为 0percentage_usedNVM 寿命已用百分比NVMe 专有ATA 恒为 0属性名小写每个 SMART 属性的对象{value, str, normalized_value}依赖型监控项与预处理除主项外的 20 个依赖项均为同一模式JSON Path提取字段 Discard unchanged with heartbeat去重。汇总如下监控项原型键值JSON Path去重心跳[{#NAME}]: Smartctl errorsmart.disk.error[{#NAME}]$.error1h[{#NAME}]: Device modelsmart.disk.model[{#NAME}]$.model_name6h[{#NAME}]: Serial numbersmart.disk.sn[{#NAME}]$.serial_number6h[{#NAME}]: Self-test passedsmart.disk.test[{#NAME}]$.self_test_passed JavaScript6h[{#NAME}]: Self-test in progresssmart.disk.test.progress[{#NAME}]$.self_test_in_progress JavaScript6h[{#NAME}]: Temperaturesmart.disk.temperature[{#NAME}]$.temperature6h[{#NAME}]: Power on hourssmart.disk.hours[{#NAME}]$.power_on_time6h[{#NAME}]: Percentage usedsmart.disk.percentage_used[{#NAME}]$.percentage_used6h[{#NAME}]: Critical warningsmart.disk.critical_warning[{#NAME}]$.critical_warning6h[{#NAME}]: Media errorssmart.disk.media_errors[{#NAME}]$.media_errors6h[{#NAME}]: Exit statussmart.disk.es[{#NAME}]$.exit_status6h[{#NAME}]: Raw_Read_Error_Ratesmart.disk.attribute.raw_read_error_rate[{#NAME}]$.raw_read_error_rate.value6h[{#NAME}]: Spin_Up_Timesmart.disk.attribute.spin_up_time[{#NAME}]$.spin_up_time.value6h[{#NAME}]: Start_Stop_Countsmart.disk.attribute.start_stop_count[{#NAME}]$.start_stop_count.value6h[{#NAME}]: Power_Cycle_Countsmart.disk.attribute.power_cycle_count[{#NAME}]$.power_cycle_count.value6h[{#NAME}]: Reported_Uncorrectsmart.disk.attribute.reported_uncorrect[{#NAME}]$.reported_uncorrect.value6h[{#NAME}]: Seek_Error_Ratesmart.disk.attribute.seek_error_rate[{#NAME}]$.seek_error_rate.value6h[{#NAME}]: Bad_Block_Ratesmart.disk.attribute.bad_block_rate[{#NAME}]$.bad_block_rate.value6h[{#NAME}]: Program_Fail_Count_Chipsmart.disk.attribute.program_fail_count_chip[{#NAME}]$.program_fail_count_chip.value6h[{#NAME}]: Reallocated_Sector_Ctsmart.disk.attribute.reallocated_sector_ct[{#NAME}]$.reallocated_sector_ct.value6h其中两个自检类监控项在 JSON Path 之后还有一段 JavaScript 预处理模板 README 中标注为The text is too long. Please see the template.其完整内容在模板 YAML 中const idx { true: 1, false: 2, null: 3, }; return typeof idx[value] undefined ? 0 : idx[value];即把 JSON 中的布尔值/null映射为数值true→1、false→2、null→3、无法识别→0。随后模板内置的值映射表valuemapSmart self-test再将其翻译为可读文本值显示文本0Undefined1True2False3Null厂商特定属性的按需发现属性监控项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 等在模板中默认discover: NO_DISCOVER不自动发现而是通过 LLD 规则的overrides覆盖规则按磁盘实际情况激活针对{#ATTRIBUTES}宏匹配如Raw_Read_Error_Rate的 override会将对应属性监控项置为DISCOVER因此只有磁盘真实存在该属性时才会被发现针对{#DISKTYPE}的 override对非 NVMe 磁盘禁用Media errors、Percentage used、Critical warning等 NVMe 专有项正则Media|Percentage|Critical对 NVMe 磁盘则禁用Self-test相关项NVMe 不适用 ATA 自检语义。这正是 README 中Attribute discovery LLD rule have pre-defined Vendor Specific Attributes for each disk, and will be discovered if attribute is present这一描述的落地实现也是模板在 HDD/SSD/NVMe 混合环境下的自适应关键。触发器原型Trigger prototypes模板内置 13 个触发器原型全部使用{#NAME}宏作用于被发现的每一块磁盘。磁盘替换检测名称表达式级别SMART: [{#NAME}]: Disk has been replacedlast(/.../smart.disk.sn[{#NAME}],#1)last(/.../smart.disk.sn[{#NAME}],#2) and length(last(/.../smart.disk.sn[{#NAME}]))0Info原理比较序列号的最新值与上一值若不同且新序列号非空说明设备被更换。该触发器手动关闭Manual close: Yes需要人工确认后关闭问题。自检失败检测名称表达式级别SMART: [{#NAME}]: Disk self-test is not passedlast(/.../smart.disk.test[{#NAME}])2 and last(/.../smart.disk.test.progress[{#NAME}])2High条件自检状态为False值 2且当前没有正在执行的自检self_test_in_progress也为 2即已完成的自检失败。操作数据opdata会显示自检结果与进度Result: {ITEM.LASTVALUE1}, test in progress: {ITEM.LASTVALUE2}。温度告警WARN / CRIT名称表达式级别依赖SMART: [{#NAME}]: Average disk temperature is too highavg(/.../smart.disk.temperature[{#NAME}],5m){$SMART.TEMPERATURE.MAX.WARN}Warning依赖 criticalSMART: [{#NAME}]: Average disk temperature is criticalavg(/.../smart.disk.temperature[{#NAME}],5m){$SMART.TEMPERATURE.MAX.CRIT}Average—使用 5 分钟平均温度避免瞬时波动误报。默认阈值 50°C 报警、65°C 严重均可在主机或模板级通过宏调整。NVMe 寿命耗尽检测名称表达式级别SMART: [{#NAME}]: NVMe disk percentage using is over 90% of estimated endurancelast(/.../smart.disk.percentage_used[{#NAME}])90Average当 NVMe 磁盘的 NVM 寿命已用百分比超过 90% 时触发该字段由厂商根据实际使用情况与预期寿命估算值允许超过 100大于 254 以 255 表示。smartctl 退出状态位掩码Exit status这是模板最核心的故障诊断触发器组。smart.disk.es[{#NAME}]保存smartctl的退出状态——一个十进制数其二进制位bitmask各代表一种错误对 ATA 磁盘的定义部分位也适用于 SCSI 磁盘位十进制值含义Bit 01命令行解析失败Bit 12设备打开失败未返回 IDENTIFY DEVICE 结构或设备处于低功耗模式Bit 24某些 SMART 或 ATA 命令执行失败或 SMART 数据结构校验和错误Bit 38SMART 状态检查返回 DISK FAILINGBit 416发现 prefail 属性值 ≤ 阈值Bit 532SMART 状态检查返回 DISK OK但发现某些属性在过去某时刻 ≤ 阈值Bit 664设备错误日志中包含错误记录Bit 7128设备自检日志中包含错误记录仅 ATA被更新的成功扩展自检覆盖的失败自检会被忽略基于该位掩码模板为每个位生成一个触发器且使用统一的新错误才触发表达式模式以 Bit 3值 8为例( count(/SMART by Zabbix agent 2 active/smart.disk.es[{#NAME}],#2) 1 and bitand(last(/SMART by Zabbix agent 2 active/smart.disk.es[{#NAME}]),8) 8 ) or ( bitand(last(/SMART by Zabbix agent 2 active/smart.disk.es[{#NAME}]),8) 8 and bitand(last(/SMART by Zabbix agent 2 active/smart.disk.es[{#NAME}]),8) bitand(last(/SMART by Zabbix agent 2 active/smart.disk.es[{#NAME}],#2),8) )该表达式的语义是count(...,#2)1表示仅有 1 个样本首次出现该位或该位从上一采样值#2到当前值#1之间发生了0→1或数值上升的变化。这保证了只有当新的错误位出现时才告警持续保持的错误状态不会反复报警。这类触发器全部为 High 级别且需手动关闭。名称对应位级别SMART: [{#NAME}]: Command line did not parseBit 0 (1)HighSMART: [{#NAME}]: Device open failedBit 1 (2)HighSMART: [{#NAME}]: Some command to the disk failedBit 2 (4)HighSMART: [{#NAME}]: Check returned DISK FAILINGBit 3 (8)HighSMART: [{#NAME}]: Some prefail Attributes thresholdBit 4 (16)HighSMART: [{#NAME}]: Some Attributes have been thresholdBit 5 (32)HighSMART: [{#NAME}]: Error log contains recordsBit 6 (64)HighSMART: [{#NAME}]: Self-test log contains recordsBit 7 (128)High底层实现SMART 插件源码剖析模板依赖的 agent 2 SMART 插件位于 src/go/plugins/smart是整个方案的后端引擎可以从源码层面印证模板中的每个细节。插件注册与指标在 plugin.go 的init()中插件注册了 3 个指标smart.attribute.discovery无参数返回 SMART 设备 JSON 数组smart.disk.discovery参数typename/id返回磁盘发现 JSON 数组smart.disk.get参数path与raid返回单盘或全盘 SMART JSON 数据。入口Export()会先调用validateExport校验参数数量与设备描述符格式见上文pathRegex防注入逻辑再根据指标参数分派给对应 handlerhandler.go。磁盘发现与属性发现实现diskDiscoverysmart.go会扫描设备并组装发现宏{#NAME}、{#DISKTYPE}、{#MODEL}、{#SN}、{#PATH}、{#RAIDTYPE}、{#ATTRIBUTES}由getAttributes拼接该盘全部属性名。attributeDiscovery则遍历每块盘的SmartAttributes.Table输出{#NAME}、{#DISKTYPE}、{#ID}属性 ID如 5、9、12、{#ATTRNAME}、{#THRESH}阈值。磁盘类型判定逻辑getType/getTypeByRateAndAttr的判定规则值得留意设备类型为 NVMe 时直接返回nvme否则根据旋转速率rotation rate判断——速率大于 0 即为 HDD若速率为 0 但属性表中存在Spin_Up_Time也判为 HDD其余情况判为 SSD。这与模板中{#DISKTYPE}相关的 overridesNVMe 专属项启用/禁用直接关联。自检状态判定selfTestPassed与selfTestInProgress的实现细节若设备不支持自检SelfTestsSupported为假则返回null自检进行中状态值高 4 位为0xf时passed返回null。这与模板 JS 预处理中的null: 3分支一一对应解释了值映射表中Null的语义来源。测试与数据样例插件目录下还包含完整的测试数据 testdata覆盖了 3ware/areca/cciss/csmi/sat/scsi 等 RAID 控制器设备、SSD/HDD/NVMe 扫描、device_open_error、combined_health_errors_scsi、自检错误等多种真实场景的smartctl -jJSON 输出配合 smart_test.go、controller_test.go 等测试文件验证解析与字段映射逻辑。若排查模板数据异常可参考这些样例对比smartctl -j的真实输出结构。模板自带仪表盘与值映射模板 YAML 末尾还附带了一个名为SMART: Overview的仪表盘原型含两个页面Temperature 页以smart.disk.temperature[{#NAME}]为数据源的图原型graph prototype每页展示 5 行随磁盘发现自动展开各盘温度曲线Power On 页以smart.disk.hours[{#NAME}]为数据源的图原型展示各盘累计通电时间。由于这些图均为原型组件链接模板后无需额外配置即可自动覆盖所有被发现的磁盘。模板级值映射Smart self-test的语义已在前文说明。常见问题与故障排查发现不到磁盘先手动执行sudo smartctl --scan确认系统可识别 SMART 设备再以zabbix用户执行sudo -u zabbix smartctl -a /dev/sda -j验证权限最后检查 agent 2 日志中Plugins.Smart相关报错。smartctl找不到确认Plugins.Smart.Path配置正确或把smartctl所在目录加入 PATHWindows 下注意路径引号。权限不足Linux确认 sudoers 中zabbix ALL(ALL) NOPASSWD:/usr/sbin/smartctl已生效注意smartctl的实际路径which smartctl核实必须与 sudoers 条目一致。出现 Command line did not parse 告警多为smart.disk.get参数格式问题——{#PATH}不应以-开头插件会拒绝该类输入RAID 场景需正确填写{#RAIDTYPE}如megaraid,0。旧版 Zabbix Server 请求超时若与 7.0 之前版本的 Server 协同Plugins.Smart.Timeout作为兼容参数仍会生效但新部署请改用Plugins.Smart.ConnectionTimeout。属性监控项未出现属性项采用按需发现overrides 基于{#ATTRIBUTES}与{#DISKTYPE}只有磁盘真实存在该属性且磁盘类型匹配时才会被发现这是设计行为而非故障。反馈渠道模板的使用问题与建议可通过 Zabbix 官方支持站点提交或参与 Zabbix 官方论坛中关于 SMART 磁盘监控模板的讨论帖。官方模板的生成版本、标签与完整定义均可直接查看仓库内的 template_module_smart_agent2_active.yamlREADME 原文见 README.md。赞分享指标监控可观测性告警运维【免费下载链接】zabbixReal-time monitoring of IT components and services, such as networks, servers, VMs, applications and the cloud.项目地址https://gitcode.com/gh_mirrors/zabbix2/zabbix点击查看免费下载相关推荐Zabbix SMART by Zabbix agent 2 模板实战基于 smartctl 的磁盘健康监控与自动发现Zabbix SMART by Zabbix agent 2 模板实战基于 smartctl 的磁盘健康监控与自动发现 导读 本文围绕官方仓库中的 SMART指标监控可观测性告警运维Zabbix 8.0「MSSQL by Zabbix agent 2」模板详解零脚本部署 SQL Server 深度监控Zabbix 8.0「MSSQL by Zabbix agent 2」模板详解零脚本部署 SQL Server 深度监控 本文系统讲解 Zabbix 官方开箱指标监控可观测性告警运维Zabbix 8.0 MySQL by Zabbix agent 2 模板部署指南基于官方模板与 MySQL 插件的无脚本监控实战Zabbix 8.0 MySQL by Zabbix agent 2 模板部署指南基于官方模板与 MySQL 插件的无脚本监控实战 本指南基于当前仓库中 Za指标监控可观测性告警运维上一篇League Akari 实战指南LOL 辅助四大件——自动选人、死亡计时、局内快捷发言与队友分析下一篇Oumi 训练方法完全指南从 SFT、DPO 到 GRPO 的配置与实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
