GPU Monitor Exporter

一个用于监控 NVIDIA GPU 掉卡状态的 Prometheus Exporter。

功能特性

• 基线扫描: 首次启动时通过 nvidia-smi 建立 GPU 基线清单
• 实时检测: 使用 lspci 检测 GPU 状态，精准识别掉卡
• 详细指标: 提供多维度指标（存在性、Revision 状态、综合健康状态、PCIe 链路宽度）
• PCIe 监控: 监控 GPU PCIe 链路宽度，自动检测带宽降级问题
• 标签丰富: 包含 GPU index、UUID、PCI Bus ID、型号等完整信息
• 易于部署: 支持 systemd 和 Kubernetes DaemonSet 部署

工作原理

1. 基线建立: 首次运行时执行 nvidia-smi --query-gpu=index,uuid,pci.bus_id,name 获取所有 GPU 信息，保存为静态清单 JSON 文件
2. 实时监控: 每次 Prometheus 抓取时执行 lspci | grep -i nvidia 获取当前 GPU 列表，并通过 nvidia-smi -q 获取 PCIe 链路宽度信息
3. 状态判定:
   • GPU 在 lspci 中不存在 → 掉卡
   • GPU 存在但 revision 不是 a1 → 异常
   • GPU 存在且 revision 为 a1 → 正常
   • PCIe 当前链路宽度 < 最大链路宽度 → 带宽降级

快速开始

前置要求

• Linux 系统
• NVIDIA 驱动已安装（提供 nvidia-smi 命令）
• lspci 命令可用（通常来自 pciutils 包）
• Go 1.21+ (仅编译时需要)

编译

git clone https://github.com/huangfuzepeng/gpu_monitor_exporter.git
cd gpu_monitor_exporter

# 编译当前平台版本
make build

# 编译 Linux 版本（适用于从 macOS/Windows 交叉编译）
make build-linux

# 编译所有平台版本
make build-all

运行

# 首次运行会自动生成基线清单
./gpu-monitor-exporter

# 指定自定义参数
./gpu-monitor-exporter \
  --listen-address=0.0.0.0:9108 \
  --inventory-file=/etc/gpu-monitor-exporter/expected.json \
  --log-level=info

# 强制重新生成基线清单
./gpu-monitor-exporter --force-rebaseline

验证

访问 metrics 端点：

curl http://localhost:9108/metrics

输出示例：

# HELP gpu_expected Expected GPUs on this host (constant 1 per expected GPU)
# TYPE gpu_expected gauge
gpu_expected{index="0",model="NVIDIA H800",pci_bus_id="00000000:18:00.0",uuid="GPU-8da2eaff-02da-0958-43a0-622ba8a3fcd2"} 1
gpu_expected{index="1",model="NVIDIA H800",pci_bus_id="00000000:1B:00.0",uuid="GPU-5ef7916f-ef98-5051-b2ce-93e33ebd048c"} 1

# HELP gpu_present GPU is present in lspci output (1=present, 0=missing)
# TYPE gpu_present gauge
gpu_present{index="0",model="NVIDIA H800",pci_bus_id="00000000:18:00.0",uuid="GPU-8da2eaff-02da-0958-43a0-622ba8a3fcd2"} 1
gpu_present{index="1",model="NVIDIA H800",pci_bus_id="00000000:1B:00.0",uuid="GPU-5ef7916f-ef98-5051-b2ce-93e33ebd048c"} 0

# HELP gpu_rev_ok GPU revision is correct (1=rev a1, 0=other or missing)
# TYPE gpu_rev_ok gauge
gpu_rev_ok{index="0",model="NVIDIA H800",pci_bus_id="00000000:18:00.0",uuid="GPU-8da2eaff-02da-0958-43a0-622ba8a3fcd2"} 1
gpu_rev_ok{index="1",model="NVIDIA H800",pci_bus_id="00000000:1B:00.0",uuid="GPU-5ef7916f-ef98-5051-b2ce-93e33ebd048c"} 0

# HELP gpu_ok GPU is healthy (1=present and rev a1, 0=unhealthy)
# TYPE gpu_ok gauge
gpu_ok{index="0",model="NVIDIA H800",pci_bus_id="00000000:18:00.0",uuid="GPU-8da2eaff-02da-0958-43a0-622ba8a3fcd2"} 1
gpu_ok{index="1",model="NVIDIA H800",pci_bus_id="00000000:1B:00.0",uuid="GPU-5ef7916f-ef98-5051-b2ce-93e33ebd048c"} 0

指标说明

指标名	类型	说明	取值	标签
gpu_expected	gauge	基线清单中的预期 GPU（静态）	恒为 1	index, uuid, pci_bus_id, model
gpu_present	gauge	GPU 是否在 lspci 中出现	1=存在，0=掉卡	index, uuid, pci_bus_id, model
gpu_rev_ok	gauge	GPU revision 是否正确	1=rev a1，0=其他或缺失	index, uuid, pci_bus_id, model
gpu_ok	gauge	GPU 综合健康状态	1=健康，0=异常	index, uuid, pci_bus_id, model
gpu_pcie_link_width_max	gauge	GPU 最大 PCIe 链路宽度	数值（如 16 表示 16x）	index, uuid, pci_bus_id, model
gpu_pcie_link_width_current	gauge	GPU 当前 PCIe 链路宽度	数值（如 16 表示 16x）	index, uuid, pci_bus_id, model
gpu_pcie_link_width_ok	gauge	PCIe 链路宽度是否正常	1=Max 与 Current 一致，0=不一致	index, uuid, pci_bus_id, model
gpu_nvidia_smi_error	gauge	nvidia-smi 命令输出包含 ERR	1=检测到错误，0=正常	hostname
gpu_nvidia_smi_error_count_total	counter	nvidia-smi 错误累计次数	累计值	hostname

GPU 相关指标标签：

• index: GPU 索引号
• uuid: GPU UUID
• pci_bus_id: PCI Bus ID
• model: GPU 型号

nvidia-smi 错误指标标签：

• hostname: 主机名

部署

systemd 部署

# 使用自动安装脚本
cd deploy/systemd
sudo ./install.sh

# 启动服务
sudo systemctl start gpu-monitor-exporter
sudo systemctl enable gpu-monitor-exporter

# 查看状态
sudo systemctl status gpu-monitor-exporter
sudo journalctl -u gpu-monitor-exporter -f

Kubernetes 部署

# 应用 DaemonSet
kubectl apply -f deploy/kubernetes/daemonset.yaml

# 查看运行状态
kubectl get pods -n gpu-monitoring
kubectl logs -n gpu-monitoring -l app=gpu-monitor-exporter -f

Docker 部署

# 构建镜像
make docker-build

# 运行容器（需要特权模式访问 PCI 设备）
docker run -d \
  --name gpu-monitor-exporter \
  --privileged \
  -p 9108:9108 \
  -v /var/lib/gpu-monitor-exporter:/data \
  gpu-monitor-exporter:v1.0.0

Prometheus 配置

在 Prometheus 配置文件中添加抓取任务：

scrape_configs:
  - job_name: 'gpu-monitor-exporter'
    scrape_interval: 30s
    static_configs:
      - targets:
        - 'gpu-node-1:9108'
        - 'gpu-node-2:9108'

完整配置和告警规则见 deploy/prometheus/ 目录。

告警规则

项目提供了预定义的告警规则（deploy/prometheus/alert-rules.yaml）：

• GPUCardMissing: GPU 掉卡告警（critical）
• GPURevisionAbnormal: GPU Revision 异常告警（warning）
• GPUUnhealthy: GPU 综合健康告警（critical）
• NodeHasUnhealthyGPU: 节点级别异常告警（critical）
• GPUMonitorExporterDown: Exporter 自身不可用告警（warning）
• NvidiaSMIError: nvidia-smi 检测到错误告警（critical）
• NvidiaSMIErrorPersistent: nvidia-smi 错误持续出现告警（warning）
• GPUPCIeLinkWidthMismatch: PCIe 链路宽度不匹配告警（warning）
• GPUPCIeLinkWidthSevereDegradation: PCIe 链路宽度严重降级告警（critical）
• NodeHasGPULinkWidthIssue: 节点存在链路宽度异常的 GPU（warning）

Makefile 命令

make build          # 编译当前平台版本
make build-linux    # 编译 Linux amd64 版本
make build-all      # 编译所有平台版本
make test           # 运行测试
make clean          # 清理编译产物
make run            # 直接运行（不编译）
make docker-build   # 构建 Docker 镜像
make fmt            # 格式化代码
make lint           # 代码检查

命令行参数

--listen-address string
    监听地址和端口 (默认: "0.0.0.0:9108")

--inventory-file string
    GPU 基线清单文件路径 (默认: "/etc/gpu-monitor-exporter/expected.json")

--force-rebaseline
    强制重新生成基线清单（覆盖现有文件）

--log-level string
    日志级别: debug, info, warn, error (默认: "info")

--version
    显示版本信息

常见问题

1. nvidia-smi 命令找不到

确保已安装 NVIDIA 驱动：

# Ubuntu/Debian
sudo apt-get install nvidia-driver-XXX

# CentOS/RHEL
sudo yum install nvidia-driver-XXX

2. lspci 命令找不到

安装 pciutils：

# Ubuntu/Debian
sudo apt-get install pciutils

# CentOS/RHEL
sudo yum install pciutils

3. 权限不足

Exporter 需要 root 权限来执行 nvidia-smi 和 lspci：

sudo ./gpu-monitor-exporter

4. 重新生成基线清单

如果更换了 GPU 硬件，需要重新生成基线：

./gpu-monitor-exporter --force-rebaseline

或者直接删除清单文件后重启：

sudo rm /etc/gpu-monitor-exporter/expected.json
sudo systemctl restart gpu-monitor-exporter

开发

运行测试

make test

代码格式化

make fmt

代码检查

make lint

License

MIT License