使用 MTDCGM 诊断 GPU
本指南介绍如何使用 dcgmi diag 检查 GPU、节点和系统部署状态，适用于节点上线前验证、故障定位和支持交接。故障正在发生时，请先执行 MT GPU 故障排查指南，再返回本指南运行 DCGM 诊断。
诊断可能占用 GPU、CPU、内存、PCIe/MTLink 和网络资源。一级诊断适合首次部署检查。二级及以上诊断只能在排空并隔离节点后执行。运行前请保存现场，不要在有业务作业时直接启动压力或硬件诊断。
快速运行一级诊断
节点已排空时，运行以下命令执行首次主动检查：
dcgmi diag -r 1 --debugLogFile ./dcgmi-diag.log
rc=$?
printf 'dcgmi exit code: %s\n' "$rc"
命令无法启动时，返回步骤 1：准备诊断环境。测试失败时，继续查看步骤 4：判定诊断结果。
步骤 1：准备诊断环境
1. 确认 Host Engine 和环境变量
dcgmi 必须连接正在运行的 mt-hostengine 或其他 MTDCGM 后台服务。启动 Host Engine 前，配置 MTDCGM 路径，并确认 MUSA Toolkit 动态库可以加载：
export PATH=/usr/local/mtdcgm/bin:${PATH}
export LD_LIBRARY_PATH=/usr/local/mtdcgm/lib/x86_64-linux-gnu:${LD_LIBRARY_PATH}
如果您在启动 Host Engine 后才设置环境变量，请按 MTDCGM 安装指南重新确认服务和环境，再运行诊断。
2. 确认目标 GPU 和作业状态
运行以下只读查询，确认 GPU 可见：
mthreads-gmi --query
dcgmi discovery -l
开始诊断前，记录 GPU 数量、设备 ID、正在运行的进程和作业分配。使用 -i 指定 GPU 列表，使用 -g 指定 GPU 组。两者不能同时使用。
3. 保存诊断前状态
保存以下信息，以便比较诊断前后的状态：
date --iso-8601=seconds
hostname
uname -a
mthreads-gmi --query -f mthreads-gmi-before.log
dcgmi discovery -l
另外保留问题发生时间附近的内核日志、/var/log/mt-hostengine.log、XID 和应用日志。需要记录完整事件时，转到 MT GPU 故障排查指南的记录步骤。
步骤 2：选择诊断级别
高一级诊断包含低一级检查。实际耗时取决于 GPU 数量、型号、拓扑、测试参数和节点负载，表中时间不能用作调度超时值。
| 级别 | 用途 | 参考时间 | 运行条件 |
|---|---|---|---|
1 | 快速系统验证和部署检查 | 数秒 | 用作首次主动检查。 |
2 | 扩展系统验证 | 最长约 2 分钟 | 排空作业，确认 GPU 没有业务负载。 |
3 | 系统硬件诊断 | 长时间 | 排空并隔离节点，在维护窗口执行。 |
4 | 更长时间的系统硬件诊断 | 更长时间 | 仅在受控维护窗口执行。 |
一级诊断检查以下部署条件：
- MTML Library；
- MUSA Main Library；
- Permissions and OS Blocks。
二级及以上诊断可能执行 GPU Memory、PCIe、Targeted Power、Targeted Stress、Memtest 和 Memory Bandwidth 等测试。以 dcgmi diag 输出为准，不要根据 NVIDIA 的插件名称推断 MTDCGM 的支持范围。
步骤 3：运行诊断
1. 运行一级诊断
对所有 GPU 运行一级诊断，并保存加密调试日志：
dcgmi diag -r 1 --debugLogFile ./dcgmi-diag.log
只诊断 GPU 0：
dcgmi diag -r 1 -i 0
2. 运行更高级别诊断
节点排空并隔离后，再选择级别：
dcgmi diag -r 2 -i 0
dcgmi diag -r 3 -i 0
dcgmi diag -r 4 -i 0
不要在生产节点上直接试运行二级、三级或四级诊断。运行前，确认维护窗口、节点隔离方式、测试时长和中止流程。
3. 运行指定测试
如需组合指定测试，请先排空并隔离节点，再使用 -r 的测试名称形式，并运行 dcgmi diag -h 确认当前构建接受的名称：
dcgmi diag -r "mp stress,diagnostic" -i 0
mp stress 和 diagnostic 可能占用 GPU 资源。不要在有业务作业的生产节点上运行这些测试。
测试名称和可用参数可能随 GPU 型号、构建配置和测试插件变化。要设置测试参数时，使用 -p test_name.variable_name=value，并保留完整命令和参数。
4. 保存结构化结果和统计信息
使用 JSON 输出，或在测试失败时保存插件统 计信息：
dcgmi diag -r 1 -j > dcgmi-diag.json
dcgmi diag -r 1 --statsonfail --statspath ./dcgmi-stats
保存命令退出码：
dcgmi diag -r 1 --debugLogFile ./dcgmi-diag.log
rc=$?
printf 'dcgmi exit code: %s\n' "$rc"
其他常用选项：
| 选项 | 用途 |
|---|---|
-v | 显示每项测试的信息和警告。 |
--debugLogFile <file> | 保存加密调试日志。 |
--statspath <path> | 指定插件统计文件目录。 |
--iterations <n> | 连续运行多次诊断。 |
--host <IP/FQDN> | 连接指定的 Host Engine；仅在远程服务已配置时使用。 |
客户端输出不包含全部诊断信息。完整诊断和验证日志还可能位于 Host Engine 的诊断工作目录和日志目录中。
5. 中止正在运行的诊断
如果诊断影响节点响应、维护窗口结束或需要立即停止，请向运行诊断的 Host Engine 发送停止请求：
DCGMI_STOP_DIAG_HOSTNAME=localhost dcgmi diag
将 localhost 替换为实际 Host Engine 的主机名或地址。该请求会停止目标 Host Engine 上的诊断进程。中止后，请保存终端输出、Host Engine 日志和节点状态，再确认 GPU 进程和作业状态。
6. 不要复制当前不支持的 NVIDIA 参数
当前 MTDCGM 诊断命令行帮助将以下选项标记为不支持：
-c/--configfile；-f/--fakeGpuList；--train；--throttle-mask；--fail-early；--check-interval。
这些选项即使出现在 NVIDIA DCGM 文档中，也不能据此推断 MTDCGM 支持生成黄金基线、忽略节流原因或提前失败。
步骤 4：判定诊断结果
1. 区分命令失败和测试失败
| 结果 | 含义 | 执行操作 |
|---|---|---|
| 命令无法启动 | Host Engine、环境变量、权限、参数或依赖存在问题。 | 保存终端输出和 Host Engine 日志，先修复运行环境。 |
| 部署检查失败 | MTML、MUSA Main Library 或 Permissions and OS Blocks 检查未通过。 | 不要继续提高诊断级别，先修复安装、驱动、库或权限问题。 |
| 某个 GPU 测试失败 | 具体 GPU 或测试插件返回失败。 | 保存测试名称、GPU ID、错误信息、错误 ID 和完整日志。 |
Skip | 测试未执行或前置条件不满足。 | 不要把 Skip 当作 Pass；记录跳过原因并确认是否需要补充前置条件。 |
| 全部通过 | 本次运行的测试通过。 | 结合健康监控、应用复现和历史基线判断；一次通过不能排除间歇性故障。 |
2. 读取 JSON 和错误信息
请保留 JSON 结果中的以下字段：
- 测试名称和结果状态；
- GPU ID；
- warning 或 error message；
- 错误 ID；
- 错误类别；
- 严重级别。
不要只提交终端最后一行。测试失败信息、节点隔离建议和 Host Engine 错误可能分布在不同日志中。
3. 按测试类型继续排查
| 失败测试或现象 | 下一步 |
|---|---|
| MTML Library、MUSA Main Library 或 Permissions and OS Blocks | 检查 MUSA Toolkit、MTDCGM 库、动态库路径、用户权限和 Host Engine 启动环境。 |
| PCIe、Targeted Power 或 Targeted Stress | 保存温度、功耗、频率、PCIe 链路、BMC 和内核日志；必要时隔离节点并联系平台支持。 |
| GPU Memory、Memtest 或 Memory Bandwidth | 保存 GPU ID、显存状态、ECC/页退役、温度和完整诊断日志，不要直接重试高等级压力测试。 |
| 多节点作业或通信相关问题 | 返回 MT GPU 故障排查指南的 MCCL 步骤。 |
| 单个应用失败而节点诊断通过 | 返回 MT GPU 故障排查指南的应用步骤。 |
步骤 5：收集诊断证据
提交诊断结果时，至少保留：
- 运行时间、主机名、GPU ID 和 GPU 数量；
dcgmi diag的完整命令和退出结果；- JSON 输出、终端输出、
--debugLogFile日志和插件统计文件； mthreads-gmi --query、dcgmi discovery -l和健康监控结果；/var/log/mt-hostengine.log、内核日志和 XID；- 驱动、MUSA Toolkit、MTDCGM、固件和应用版本；
- 节点是否排空、是否隔离，以及诊断期间是否有业务作业；
- 测试失败后执行的重试、重置、重启或恢复操作。
如果诊断要求隔离节点，或者多个 GPU/节点同时失败，请不要继续提高诊断级别，转到 MT GPU 故障排查指南的证据交接步骤。
步骤 6：验证恢复结果
诊断完成并执行修复后，在节点重新承载业务前：
- 运行
mthreads-gmi --query和dcgmi discovery -l，确认 GPU 数量和设备 ID 符合预期。 - 运行
dcgmi health -f查看监控项，完成监控窗口后运行dcgmi health -c。 - 使用受控工作负载验证原故障不再复现。
- 记录诊断级别、测试结果、修复动作和节点重新上线时间。
如果问题原因仍不明确或故障再次发生，请保持节点隔离，并按 MT GPU 故障排查指南提交完整证据。
