prometheuscommunity/smartctl-exporter

smartctl_exporter

镜像概述和主要用途

smartctl_exporter是一个Prometheus exporter，用于将smartctl工具收集的存储设备S.M.A.R.T.统计信息导出为Prometheus可抓取的指标。该镜像封装了smartctl_exporter应用程序，便于在Docker环境中部署和运行。

核心功能和特性

• 从smartctl获取存储设备健康数据并转换为Prometheus指标
• 支持自动扫描系统存储设备或手动指定监控设备
• 可配置的设备扫描间隔和重新扫描周期
• 提供设备包含/排除的正则表达式过滤
• 支持TLS加密和基本身份验证保护
• 灵活的日志级别和格式配置

使用场景和适用范围

• 服务器存储设备健康状态监控
• 磁盘故障预警和预测
• 存储系统性能分析
• 集成到Prometheus监控体系中
• 适用于需要监控物理或虚拟存储设备的各类环境

要求

• smartmontools >= 7.0，因为JSON导出功能在7.0版本中引入

配置选项

命令行选项

如果未使用--smartctl.device标志，exporter将扫描系统中的可用设备。

usage: smartctl_exporter [<flags>]

Flags:
  -h, --help                   显示上下文相关帮助（也可尝试--help-long和--help-man）。
      --smartctl.path="/usr/sbin/smartctl"  
                               smartctl二进制文件路径
      --smartctl.interval=60s  smartctl轮询间隔
      --smartctl.rescan=10m    重新扫描新设备/已移除设备的间隔。如果间隔小于1秒，则不进行重新扫描。
                               如果使用smartctl.device配置了任何设备，也不会进行重新扫描。
      --smartctl.device=SMARTCTL.DEVICE ...  
                               要监控的设备（可重复）
      --smartctl.device-exclude=""
                               自动扫描中要排除的设备正则表达式。（与device-include互斥）
      --smartctl.device-include=""
                               自动扫描中要包含的设备正则表达式。（与device-exclude互斥）
      --web.telemetry-path="/metrics"  
                               公开指标的路径
      --web.systemd-socket     使用systemd套接字激活监听器代替端口监听器（仅Linux）。
      --web.listen-address=:9633 ...
                               公开指标和Web界面的地址。可重复指定多个地址。
      --web.config.file=""     [实验性] 可启用TLS或身份验证的配置文件路径。
      --log.level=info         仅记录给定严重性或更高级别的消息。选项：[debug, info, warn, error]
      --log.format=logfmt      日志消息的输出格式。选项：[logfmt, json]
      --version                显示应用程序版本。

Docker部署方案

docker-compose配置示例

最小功能的docker-compose.yml配置：

yaml
version: "3"

services:
  smartctl-exporter:
    image: docker.xuanyuan.run/prometheuscommunity/smartctl-exporter
    privileged: true
    user: root
    ports:
      - "9633:9633"

TLS和基本身份验证

该exporter支持TLS加密和基本身份验证。

要使用TLS和/或基本身份验证，需要通过--web.config.file参数传递配置文件。文件格式在https://github.com/prometheus/exporter-toolkit/blob/master/docs/web-configuration.md%E4%B8%AD%E6%9C%89%E8%AF%A6%E7%BB%86%E6%8F%8F%E8%BF%B0%E3%80%82

故障排除

数据不一致问题排查

smartctl_exporter使用smartctl的JSON输出向Prometheus提供数据。如果数据不正确，请查看smartctl的原始数据以确定问题应报告给smartmontools上游还是本项目。一般来说，smartctl_exporter不会修改传输中的数据。如果数据在smartctl中缺失，那么在smartctl_exporter中也不应出现。如果smartctl提供的数据不正确，应向上游报告。对于因smartctl提供的无效或缺失数据导致smartctl_exporter中出现多个无效或不正确数据的情况，需要根据具体情况进行研究。

smartctl输出与exporter输出对比

S.M.A.R.T.属性在https://github.com/prometheus-community/smartctl_exporter/blob/master/smartctl.go%E4%B8%AD%E8%BF%9B%E8%A1%8C%E6%98%A0%E5%B0%84%E3%80%82%E6%AF%8F%E4%B8%AA%E5%87%BD%E6%95%B0%E9%83%BD%E6%9C%89%E4%B8%80%E4%B8%AA%60prometheus.MustNewConstMetric%60%E6%88%96%E7%B1%BB%E4%BC%BC%E5%87%BD%E6%95%B0%EF%BC%8C%E7%AC%AC%E4%B8%80%E4%B8%AA%E5%8F%82%E6%95%B0%E6%98%AF%E6%8C%87%E6%A0%87%E5%90%8D%E7%A7%B0%E3%80%82%E5%9C%A8https://github.com/prometheus-community/smartctl_exporter/blob/master/metrics.go%E4%B8%AD%E6%9F%A5%E6%89%BE%E6%8C%87%E6%A0%87%E5%90%8D%E7%A7%B0%EF%BC%8C%E4%BB%A5%E4%BA%86%E8%A7%A3exporter%E5%A6%82%E4%BD%95%E6%98%BE%E7%A4%BA%E4%BF%A1%E6%81%AF%E3%80%82%E8%BF%99%E5%8F%AF%E8%83%BD%E5%90%AC%E8%B5%B7%E6%9D%A5%E5%BE%88%E6%8A%80%E6%9C%AF%EF%BC%8C%E4%BD%86%E5%AF%B9%E4%BA%8E%E7%90%86%E8%A7%A3%E6%95%B0%E6%8D%AE%E5%A6%82%E4%BD%95%E4%BB%8Esmartctl%E6%B5%81%E5%90%91smartctl_exporter%E5%86%8D%E5%88%B0Prometheus%E8%87%B3%E5%85%B3%E9%87%8D%E8%A6%81%E3%80%82

如果数据看起来不正确，请查看https://www.smartmontools.org/wiki/FAQ%EF%BC%8C%E6%82%A8%E7%9A%84%E9%97%AE%E9%A2%98%E5%8F%AF%E8%83%BD%E5%B7%B2%E6%9C%89%E7%AD%94%E6%A1%88%E3%80%82%E5%A6%82%E6%9E%9C%E4%BB%8D%E6%9C%89%E7%96%91%E9%97%AE%EF%BC%8C%E8%AF%B7%E6%8F%90%E4%BA%A4%5Bissue]()。

收集smartctl数据

按照以下步骤收集smartctl数据以进行故障排除。如果您有独特的驱动器/数据/边缘情况并希望"***"数据，请提交包含已编辑JSON文件的PR。

1. 运行scripts/collect-smartctl-json.sh将所有驱动器导出到当前目录下的smartctl-data目录。
2. 运行scripts/redact_fake_json.py编辑敏感数据。
3. 提供相关驱动器的JSON文件。

bash
cd scripts
./collect-smartctl-json.sh
./redact-fake-json.py smartctl-data/*.json

使用JSON数据运行smartctl_exporter

smartctl_exporter可以使用本地JSON数据运行。设备名称从机器中的实际设备获取，而数据重定向到debug目录。使用实际设备名称将JSON数据保存在debug目录中，保持1:1对应关系。如果有3个设备sda、sdb和sdc，smartctl_exporter将需要3个文件：debug/sda.json、debug/sdb.json和debug/sdc.json。

准备好"假设备"(JSON文件)后，通过命令行传递隐藏的--smartctl.fake-data开关运行exporter。指定端口以避免与默认端口上已存在的smartctl_exporter冲突。

bash
smartctl_exporter --web.listen-address 127.0.0.1:19633 --smartctl.fake-data

常见问题解答

如何使用JSON文件运行smartctl_exporter？

如果您在帮助他人，可以请求提供上述smartctl命令的输出。使用隐藏的--smartctl.fake-data标志将此数据输入smartctl_exporter。如果smartctl_exporter已在运行，请使用不同的端口；在本例中为19633。首先运行collect_fake_json.sh为您的设备收集JSON文件。将请求的JSON文件复制到其中一个假文件中。启动exporter后，可以查询它以查看生成的数据。

bash
# 将设备的JSON文件转储到debug/目录
./collect_fake_json.sh

# 将测试JSON复制到debug/中的一个文件
cp extracted-from-above-sda.json debug/sda.json

# 确保拥有最新版本
go build
# 使用不同的端口，以防smartctl_exporter已在运行
sudo ./smartctl_exporter --web.listen-address=127.0.0.1:19633 --log.level=debug --smartctl.fake-data

# 使用curl和grep查询
curl --silent 127.0.0.1:19633/metrics | grep -i nvme
# 或使用xh和ripgrep
xh --body :19633/metrics | rg nvme

为什么需要root权限？不能将用户添加到"disk"组吗？

一位博主曾提出同样的问题，并在smartmontools上提交了工单。以下是他们的回应：smartctl需要以root身份运行。

https://www.smartmontools.org/ticket/1064

根据当前内核源代码中的blk_verify_command()函数（参见https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/block/scsi_ioctl.c%EF%BC%89%EF%BC%8C 如果设备以root（或CAP_SYS_RAWIO）身份打开，O_RDONLY或O_RDWR没有区别。

blk_set_cmd_filter_defaults()函数中列出的SCSI命令显示，对于非root用户，某些smartctl -d scsi功能可能使用O_RDONLY工作。更多功能可能使用O_RDWR工作。

但是smartctl -d sat（用于访问SATA设备）根本无法工作，因为SCSI命令ATA_12和ATA_16 （参见https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/scsi/scsi_proto.h%EF%BC%89 始终对非root用户阻塞。

NVMe驱动器支持情况

来自smartmontools FAQ：https://www.smartmontools.org/wiki/FAQ#MyNVMedriveisnotinthesmartctlsmartddatabase

SCSI/SAS和NVMe驱动器不提供类似ATA/SATA的SMART属性。 因此驱动器数据库不包含这些驱动器的任何条目。 未来可能会改变，因为某些驱动器通过供应商特定命令提供类似信息（参见ticket #870）。

smartmontools还有一个关于https://www.smartmontools.org/wiki/NVMe_Support%E8%AE%BE%E5%A4%87%E7%9A%84wiki%E9%A1%B5%E9%9D%A2%E3%80%82

如何向上游smartmontools报告问题？

请查看他们的FAQ：https://www.smartmontools.org/wiki/FAQ#Howtocreateabugreport%E3%80%82