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

$NVSentinel$ gpu-health-monitor模块调研

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

整体运行链路是：

text 复制代码

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 里定义了命令：

toml 复制代码

gpu_health_monitor = "gpu_health_monitor.cli:cli"

DaemonSet 里实际执行的是：

text 复制代码

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

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

plaintext 复制代码

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 153 DCGM_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。
它通过 HealthEventOccurredV1 gRPC 接口发给 platform-connector。
它有本地 cache，避免同一个 GPU 同一个 active error 每轮重复发送；只有新错误或恢复时才发事件。
如果 platform-connector socket 不存在，它不会更新 cache，下一轮会重新尝试发送。

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

text 复制代码

/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、PlatformConnector gRPC 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：

text 复制代码

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，比如：

text 复制代码

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"的转换和发送。

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