[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 转成 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”的转换和发送。