[NVSentinel] gpu-health-monitor模块调研

health-monitors/gpu-health-monitor/gpu_health_monitor/是gpu-health-monitor的 Python 包源码。它的职责是：连接 DCGM，周期性读取 GPU 健康状态，把 DCGM health incident 转成 NVSentinelHealthEvent，再通过 Unix socket 发给platform-connector。

整体运行链路是：

gpu_health_monitor CLI -> 读取 config.ini / dcgmerrorsmapping.csv / NODE_NAME -> 启动 Prometheus metrics server -> 创建 DCGMWatcher -> DCGMWatcher 连接 DCGM hostengine -> 周期性 dcgm_group.health.Check() -> PlatformConnectorEventProcessor 转换为 HealthEvent -> gRPC over UDS 发给 platform-connector

目录结构

cli.py是入口。pyproject.toml里定义了命令：

gpu_health_monitor = "gpu_health_monitor.cli:cli"

DaemonSet 里实际执行的是：

gpu_health_monitor --config-file ... --dcgm-addr ... --dcgm-error-mapping-config-file ...

它负责读取参数、读取 Helm 生成的config.ini、加载 DCGM error 到 RecommendedAction 的映射、初始化日志和 metrics，然后启动DCGMWatcher。

DCGM (NVIDIA Datacenter GPU Manager) │ 定期轮询 health check ▼ DCGMWatcher ──callback──▶ PlatformConnectorEventProcessor │ │ gRPC over UDS │ ▼ Prometheus 指标 platform-connector → fault-quarantine (cordon / drain / reset …)

dcgm_watcher/是 DCGM 采集核心：

• types.py定义内部数据结构，比如HealthStatus、HealthDetails、ErrorDetails、CallbackInterface。
• dcgm.py连接 DCGM，创建包含 GPU/NVSwitch entity 的 DCGM group，调用dcgm_group.health.Set(DCGM_HEALTH_WATCH_ALL)和dcgm_group.health.Check()。
• 它会把 DCGM incident 按 watch 分类，比如DCGM_HEALTH_WATCH_PCIE、DCGM_HEALTH_WATCH_NVLINK、DCGM_HEALTH_WATCH_MEM等。
• 它还支持 field monitor，目前有GpuThermalMarginWatch，读取 DCGM field 153DCGM_FI_DEV_GPU_TEMP_LIMIT，结合 metadata 中的 slowdown T.Limit 判断 thermal margin 是否低于阈值。

platform_connector/是事件转换和发送层：

• platform_connector.py实现PlatformConnectorEventProcessor，它是DCGMWatcher的 callback。
• 它把 DCGM watch 名转成 CheckName，例如DCGM_HEALTH_WATCH_PCIE->GpuPcieWatch。
• 它构造HealthEvent，字段包括agent=gpu-health-monitor、componentClass=GPU、checkName、isFatal、isHealthy、errorCode、entitiesImpacted、recommendedAction。
• 它通过HealthEventOccurredV1gRPC 接口发给platform-connector。
• 它有本地 cache，避免同一个 GPU 同一个 active error 每轮重复发送；只有新错误或恢复时才发事件。
• 如果 platform-connector socket 不存在，它不会更新 cache，下一轮会重新尝试发送。

metadata/reader.py读取 GPU metadata 文件，默认来自：

/var/lib/nvsentinel/gpu_metadata.json

它提供：

• get_gpu_uuid(gpu_id)
• get_pci_address(gpu_id)
• get_slowdown_tlimit_c(gpu_id)
• get_chassis_serial()

这些用于丰富HealthEvent.entitiesImpacted。尤其COMPONENT_RESET需要GPU_UUID，如果 metadata 里拿不到GPU_UUID/PCI，它会把 action 从COMPONENT_RESET降级成RESTART_VM，避免 node-drainer/fault-remediation 后面做 partial GPU reset 时缺实体信息。

protos/是生成的 protobuf Python 文件，对应HealthEvent、PlatformConnectorgRPC client 等。业务代码里通过这些类构造HealthEvent并调用PlatformConnectorStub.HealthEventOccurredV1。

metrics.py、dcgm_watcher/metrics.py、platform_connector/metrics.py是 Prometheus metrics 定义，分别覆盖 feature flag、DCGM API latency/failure、发送到 UDS 成功/失败、active events 等。

logger.py配置结构化 JSON 日志，给日志统一加module=gpu-health-monitor和版本号。

它具体监控什么

它使用 DCGM 的健康 watch：

DCGM_HEALTH_WATCH_ALL

所以会覆盖 DCGM 支持的 GPU/NVSwitch 健康类别，例如 PCIe、NVLink、memory/ECC、thermal、power、driver、NVSwitch 等。

DCGM 返回 incident 后，dcgm.py会提取：

• watch/system 类型
• GPU entity id
• DCGM error code
• error message

然后platform_connector.py根据dcgmerrorsmapping.csv把 DCGM error code 映射成RecommendedAction，比如：

DCGM_FR_VOLATILE_DBE_DETECTED -> COMPONENT_RESET DCGM_FR_VOLATILE_SBE_DETECTED -> NONE DCGM_FR_NVLINK_DOWN -> RESTART_VM DCGM_FR_THERMAL_VIOLATIONS -> CONTACT_SUPPORT

如果找不到映射，默认CONTACT_SUPPORT。

部署关系

Helm chart 会把这些配置挂进去：

• config.ini：poll interval、socket path、启用的 event processor、field monitoring 开关
• dcgmerrorsmapping.csv：DCGM error -> RecommendedAction 映射
• /var/run/nvsentinel.sock：platform-connector UDS socket
• /var/lib/nvsentinel/gpu_metadata.json：metadata collector 生成的 GPU 元数据

镜像基于 NVIDIA DCGM runtime image 构建，所以容器内有 DCGM Python binding。Dockerfile 会构建 Python wheel，然后安装到 DCGM runtime 镜像中。

一句话总结：这个目录就是gpu-health-monitor的运行时主体，负责“DCGM 健康检查 -> NVSentinel HealthEvent -> platform-connector”的转换和发送。