hyperpod-performance-debugger

HyperPod 性能调试器

1. 不同节点间 NCCL 性能不均——工作负载在某些节点组上比在其他节点组上更快、成对带宽存在差异，怀疑有拖慢进度的节点。
2. 文件系统性能不佳——训练因数据加载而停滞，检查点保存／加载占据大部分步时，FSx 吞吐量已饱和。

范围与委派

将范围外的发现转交给下方对应的技能所有者。

观察到的问题	转交给
GPU 硬件故障、ECC、NVLink、Xid、DCGM 诊断、排空／替换节点	hyperpod-node-debugger（§ F 硬件／自动修复、§ G GPU）
在 os.fork() 处出现 Cannot allocate memory、根卷空间耗尽	hyperpod-node-debugger（§ I 资源耗尽）
NCCL 超时、挂起、AllReduce 停滞、EFA 回退到 TCP、RDMA memlock	hyperpod-nccl
不同节点间 EFA／NCCL／CUDA／NVIDIA 驱动版本不一致	hyperpod-version-checker
缺少 EFA 自引用安全组规则——单节点	hyperpod-node-debugger § A（EFA／安全组）
缺少 EFA 自引用安全组规则——整个集群	hyperpod-cluster-debugger § A（EFA 健康检查）
Slurm 节点状态变更（排空／恢复／重启）	hyperpod-slurm-debugger
提供给 AWS Support 的诊断包	hyperpod-issue-report
访问节点 Shell	hyperpod-ssm

操作策略

• 只读。打印由客户运行的命令；不要执行会修改状态的命令。
• 容器与主机之间的版本比较通过 hyperpod-version-checker 进行。
• Xid 日志行、ECC 计数、NVLink 通道状态和温度读数会显示出来；目录和诊断结论由 hyperpod-node-debugger § G 提供。

工作流

1. 确认症状是 NCCL 性能不均 或 文件系统性能不佳。如果两者都不是，则转交给上方对应的同级技能。
2. 运行 scripts/perf-snapshot.sh（只读），收集疑似节点以及挂载在该节点上的 FSx 文件系统的主机侧信号。
3. 对脚本输出中的每一行 [CONCERN]，打开下方对应章节并阅读支持性参考资料。
4. 完成单个事件的诊断后，建议客户使用 § 持续健康覆盖 中的 HyperPod 平台健康功能，以获得持续保护。

步骤 1：运行快照

bash scripts/perf-snapshot.sh --cluster <CLUSTER_NAME_OR_ARN> --region <REGION>

# Scope to one suspect node:
bash scripts/perf-snapshot.sh --cluster <C> --region <R> --node <INSTANCE_ID>

该脚本默认对一个节点进行采样。它通过 hyperpod-ssm 收集主机侧数据：nvidia-smi 输出（温度、SM 时钟、PCIe 链路宽度、ECC、NVLink、topo -m）、近期 dmesg Xid 日志行、EFA 端口状态和 fi_info 提供程序可见性、EFA 安装程序及内核模块版本、CPU 调速器、NVL72 Fabric Manager 状态、FSx CloudWatch 使用情况、每个挂载点的 df -h／lfs df -h、主机 iowait、/dev/shm 大小以及根卷使用情况。所有操作均为只读。

标签：[OK] 健康 · [CONCERN] 值得调查的信号（附带指向所有者技能的 → 指针）· [INFO] 信息提示。

主机与容器范围。 脚本通过 SSM 在主机上运行，并报告主机范围内的值。许多设置会按设计将 EFA／libfabric／OFI-NCCL／CUDA 栈打包在训练容器中，因此主机值为 unknown 本身并不代表存在缺陷。对性能而言，关键在于工作负载实际使用的栈。在得出结论前，请通过 hyperpod-version-checker 验证容器内及各节点间的版本。

步骤 2：匹配信号 → 章节

观察结果	章节
不同节点对之间的 NCCL 带宽存在差异 / 怀疑有拖后腿的节点	A：NCCL 性能不均
节点分布在不同 AZ / 网络节点层标签 / UltraServer 边界	A
节点上的 EFA 端口未处于 ACTIVE 状态、缺少 OFI 插件，或无法看到 FI 提供程序	A + 转至 hyperpod-node-debugger § A；使用 hyperpod-version-checker 比较跨节点版本
iostat 显示 iowait 较高，FSx CloudWatch 利用率持续接近 100%	B：文件系统性能不佳
DataLoader 停滞，检查点占用的步时过长	B
dmesg 中出现 Xid 行、不可纠正的 ECC 错误、非活动 NVLink 通道、GPU ≥ 88°C	转至 hyperpod-node-debugger § G
怀疑容器与主机之间存在版本差异	转至 hyperpod-version-checker
os.fork() 时出现 Cannot allocate memory、根卷已满、发生 OOM 事件	转至 hyperpod-node-debugger § I
NCCL 超时、挂起、回退到 TCP（NET/OFI Using TCP）、RDMA memlock	转至 hyperpod-nccl

---

A：NCCL 性能不均

客户反馈：相同的训练作业在不同节点组上运行时步时不同、节点对之间的带宽存在差异，或者尽管代码相同，某些分配始终比其他分配慢。

根据官方故障排查指南，常见影响因素包括节点间网络拓扑差异（跨 AZ、跨机架、跨 UltraServer）、部分节点的 EFA 性能下降、实例组内混用不同实例类型或代际，以及 CPU 频率调节差异。

诊断检查（只读）

主机侧数据点——GPU 热状态/ECC/PCIe/时钟、Xid、NVLink 通道、EFA 端口状态和提供程序可见性、CPU 调速器、EFA/OFI/驱动程序版本、nvidia-smi topo -m——均由 scripts/perf-snapshot.sh（上文步骤 1）收集。该脚本会根据阈值标记 [CONCERN] 并输出后续处理指引；可通过 --node <INSTANCE_ID> 对每个可疑节点重新运行。

如需检查节点间驱动程序 / CUDA / NCCL / EFA / OFI 版本差异，请运行 hyperpod-version-checker 技能。

成对 NCCL 带宽测试

运行 awslabs/awsome-distributed-training 中的标准 nccl-tests 测试方案。对于包含 N 个节点的集群，在每一对节点之间运行 all-reduce，并记录每对节点的 busbw。低于本次运行均值约 5% 以上的节点对（AWS 验证脚本标记问题的阈值）是可能存在问题的候选对象。

每种 SKU 的预期 busbw 已发布在 AI-on-HyperPod NCCL test guide 中。在依赖某个数值之前，请先对特定实例类型进行基准测试。

成对测试脚本、HyperPod 拓扑信息（HyperPod API、EKS 标签、Slurm topology.conf）以及 GB200 NVL72 相关信息，见 references/perf-details.md § Uneven NCCL。

拓扑验证

HyperPod 通过三个运维人员可见的界面提供拓扑信息：

• HyperPod API：aws sagemaker describe-cluster-node 会返回 NodeDetails.Placement.AvailabilityZone / AvailabilityZoneId 和 NodeDetails.UltraServerInfo.Id（仅适用于 UltraServer SKU）。
• EKS 标签：topology.kubernetes.io/zone、topology.k8s.aws/network-node-layer-{1,2,3}（编号最大的一层 = 距实例最近）和 topology.k8s.aws/ultraserver-id。
• Slurm：HyperPod 会自动生成 topology.conf。通过 scontrol show topology 检查。

紧密耦合的工作负载应使用相同的 AZ、相同的编号最高的 network-node-layer 标签（EKS）或相同的 Slurm 拓扑块；对于 NVL72 作业，还应使用相同的 UltraServerInfo.Id / topology.k8s.aws/ultraserver-id。如果集群分布在多个 AZ 或网络层，则必须在预置时重新建立拓扑。将预置变更交由 hyperpod-cluster-debugger § B（容量与 AZ）处理。

---

B：文件系统性能不佳

客户报告训练受数据加载瓶颈影响、检查点保存/加载占用了大部分步进时间、可执行文件/脚本加载缓慢，或 iowait 偏高。

根据官方故障排除指南，解决流程按以下顺序进行：

1. 检查文件系统的 CloudWatch 指标。
2. 根据工作负载要求检查已预置的性能配置。
3. 调查哪些操作导致了 I/O——是工作负载需求，还是低效的访问模式。
4. 考虑提升已预置的性能。
5. 选择符合 I/O 模式的文件系统类型。

此技能涵盖第 1–3 步。第 4–5 步由客户决定；提供相关数据，由客户选择。

诊断检查（只读）

scripts/perf-snapshot.sh（上文第 1 步）涵盖此检查中的节点侧工作：它会发现 FSx 挂载点、调用 aws cloudwatch get-metric-statistics 查询 DataReadBytes 和（对于 OpenZFS）FileServerDiskIopsUtilization，打印 /fsx /opt/dlami/nvme /opt/sagemaker 的 df -h 输出，对每个 Lustre 挂载点运行 lfs df -h，并报告 iostat iowait。当 OpenZFS IOPS 利用率持续 ≥ 80% 或 iowait > 20% 时，会标记 [CONCERN]。

如需查询更长时间范围或其他指标（DataWriteBytes、Lustre DiskIopsUtilization、OpenZFS FileServerDiskThroughputUtilization），请直接执行查询：

aws cloudwatch get-metric-statistics --region <REGION> \
  --namespace AWS/FSx --metric-name DataReadBytes \
  --dimensions Name=FileSystemId,Value=<FSID> \
  --start-time "$(date -u -d '3 hours ago' +%Y-%m-%dT%H:%M:%S)" \
  --end-time   "$(date -u +%Y-%m-%dT%H:%M:%S)" \
  --period 60 --statistics Sum Maximum

每种文件系统类型的完整指标目录见 references/perf-details.md § Filesystem。

分支

预置容量已饱和。 在整个工作负载时间段内，CloudWatch 利用率持续接近 100%。客户决定：扩展文件系统。

• FSx for Lustre 的吞吐量随 StorageCapacity × PerUnitStorageThroughput 增长；更改容量不会造成中断。
• FSx for OpenZFS — 增加预置 IOPS 或吞吐量。

I/O 模式效率低下。 CloudWatch 显示仍有余量，但工作负载仍受 I/O 限制。客户决定：更改应用程序。

• DataLoader：增大 num_workers，设置 pin_memory=True、persistent_workers=True。
• 检查点：使用异步 + 分片（torch.distributed.checkpoint.async_save，以及 FSDP SHARDED_STATE_DICT）。FULL_STATE_DICT 会通过 rank 0 序列化，是常见的根本原因。
• 小文件工作负载：Lustre 针对大型顺序 I/O 进行了优化。对于数百万个小文件，请使用 WebDataset / tar 分片、FSx for OpenZFS 或 NVMe 临时存储。

文件系统选择指南和异步检查点模式见 references/perf-details.md § 文件系统。

---

持续健康保障

诊断完当前事件后，建议启用 HyperPod 的内置健康功能，以便在下一次训练运行之前发现问题，而不是等客户再次报告性能回退后才处理。

• 在集群上启用 NodeRecovery=Automatic。 健康监控代理（HMA）会持续监控基于 GPU 和 Trainium 的实例，并在检测到故障时将实例标记为不健康。启用自动恢复后，HyperPod 会重启或替换节点 — 无需操作员介入。

• 为每个 GPU 实例组启用 OnStartDeepHealthChecks，并启用以下两类检查：

  • InstanceStress — 在 CPU/内存/磁盘上运行 stress-ng，验证 GPU 和 PCI 设备数量，执行 DCGM 4 级诊断（包括内存测试），并检查 EFA 环回带宽/延迟。
  • InstanceConnectivity — 多节点 NCCL all-reduce。

  每个新预置或自动替换的节点在接受作业之前，都会通过相同的硬件标准检查。

• 在此技能或任何同级技能发现硬件问题，但集群仍在运行工作负载时，按需运行深度健康检查。 aws sagemaker start-cluster-health-check 会针对指定实例组运行相同的检查；节点会被置于 Slurm 维护预留中，检查会排队等待任何正在运行的作业完成（不会抢占作业）。控制台：HyperPod → Clusters → Instances → Run deep health checks。

  NodeProvisioningMode=Continuous 时不支持；每个集群同一时间只能提交一个按需请求。需要使用最新 AMI — 请先运行 UpdateClusterSoftware。

日志会写入 CloudWatch 中的 /aws/sagemaker/Clusters/<cluster_name>/<cluster_id>，位于 DeepHealthCheckResults/<log_stream_id> 下；每个节点上也会写入 /var/log/aws/clusters/sagemaker-deep-health-check.log。

参考资料

• references/perf-details.md — NCCL 成对测试方案、HyperPod 拓扑检查、GB200 NVL72 放置；按文件系统类型分类的 CloudWatch 指标目录、异步检查点模式、文件系统选择指南。

外部资料：

• Amazon SageMaker HyperPod 故障排查指南（官方）：https://github.com/aws/sagemaker-hyperpod-cluster-setup/blob/troubleshooting-doc-20250917/troubleshoot/index.md
• AI-on-HyperPod NCCL 性能测试（各 SKU 的预期 busbw）：https://awslabs.github.io/ai-on-sagemaker-hyperpod/docs/slurm-orchestration/validation-and-testing/performance-testing/nccl-tests
• Amazon SageMaker HyperPod 弹性功能（NodeRecovery、HMA、自动恢复）：https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-hyperpod-resiliency.html
• Amazon SageMaker HyperPod 深度运行状况检查：https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-hyperpod-resiliency-slurm-deep-health-checks.html
• StartClusterHealthCheck API：https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_StartClusterHealthCheck.html
• Amazon EC2 实例拓扑／network-node-layer 标签：https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/how-ec2-instance-topology-works.html
• Amazon FSx for Lustre 性能：https://docs.aws.amazon.com/fsx/latest/LustreGuide/performance.html
• Amazon FSx for OpenZFS 指标：https://docs.aws.amazon.com/fsx/latest/OpenZFSGuide/fsx-openzfs-metrics.html
• AWS Elastic Fabric Adapter 和 NCCL：https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/efa-start-nccl.html
• awslabs/awsome-distributed-training NCCL 测试：https://github.com/awslabs/awsome-distributed-training/tree/main/micro-benchmarks/nccl-tests