![[NVSentinel] gpu-health-monitor模块调研](http://pic.xiahunao.cn/yaotu/[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:cliDaemonSet 里实际执行的是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字段包括agentgpu-health-monitor、componentClassGPU、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 日志给日志统一加modulegpu-health-monitor和版本号。它具体监控什么它使用 DCGM 的健康 watchDCGM_HEALTH_WATCH_ALL所以会覆盖 DCGM 支持的 GPU/NVSwitch 健康类别例如 PCIe、NVLink、memory/ECC、thermal、power、driver、NVSwitch 等。DCGM 返回 incident 后dcgm.py会提取watch/system 类型GPU entity idDCGM error codeerror 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.inipoll interval、socket path、启用的 event processor、field monitoring 开关dcgmerrorsmapping.csvDCGM error - RecommendedAction 映射/var/run/nvsentinel.sockplatform-connector UDS socket/var/lib/nvsentinel/gpu_metadata.jsonmetadata 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模块调研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:cliDaemonSet 里实际执行的是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字段包括agentgpu-health-monitor、componentClassGPU、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 日志给日志统一加modulegpu-health-monitor和版本号。它具体监控什么它使用 DCGM 的健康 watchDCGM_HEALTH_WATCH_ALL所以会覆盖 DCGM 支持的 GPU/NVSwitch 健康类别例如 PCIe、NVLink、memory/ECC、thermal、power、driver、NVSwitch 等。DCGM 返回 incident 后dcgm.py会提取watch/system 类型GPU entity idDCGM error codeerror 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.inipoll interval、socket path、启用的 event processor、field monitoring 开关dcgmerrorsmapping.csvDCGM error - RecommendedAction 映射/var/run/nvsentinel.sockplatform-connector UDS socket/var/lib/nvsentinel/gpu_metadata.jsonmetadata collector 生成的 GPU 元数据镜像基于 NVIDIA DCGM runtime image 构建所以容器内有 DCGM Python binding。Dockerfile 会构建 Python wheel然后安装到 DCGM runtime 镜像中。一句话总结这个目录就是gpu-health-monitor的运行时主体负责“DCGM 健康检查 - NVSentinel HealthEvent - platform-connector”的转换和发送。
