perf-nsight-systems

用途

NVIDIA Nsight Systems（nsys）是一个系统级性能分析工具，用于采集 CPU/GPU 活动时间线、API 调用轨迹和操作系统级事件。与内核级的 Nsight Compute（ncu）不同，nsys 展示的是整体视图——内核、内存传输、通信与 CPU 工作在时间上如何重叠。

该技能适用于以下触发场景：用户希望端到端剖析训练脚本、分析 GPU 利用率、查找流水线瓶颈、检查通信/计算重叠，或解读 .nsys-rep 报告。常见症状包括：训练比预期慢、迭代之间 GPU 空闲、需要了解 CPU 与 GPU 的时间分布、分布式训练扩展性差。

不适用于：内核级优化（应使用 Nsight Compute / ncu）、GPU 硬件指标如 SM 吞吐量与缓存命中率（应使用 ncu）、无需剖析的 GPU 监控（应使用 nvidia-smi）、非 CLI 用法（GUI 工作流、IDE 集成，请查阅官方文档）。

主要能力

通过 nsys profile 采集训练脚本的性能数据，支持 CUDA、NVTX、cuDNN、cuBLAS、OSRT、MPI、UCX 等追踪目标。
使用 cudaProfilerApi 捕获范围跳过预热阶段，只采集稳态迭代。
通过 nsys stats 生成结构化统计报告，如 cuda_gpu_kern_sum、cuda_api_sum、cuda_gpu_mem_time_sum、cudnn_api_sum、cublas_api_sum、cuda_kern_exec_sum、nvtx_pushpop_sum、nvtx_gpu_proj_sum、nvtx_kern_sum 等。
通过 nsys analyze 检测反模式，如 cuda_memcpy_sync、gpu_gaps、gpu_time_util 等规则。
通过 nsys recipe 进行高级分析，如 nccl_gpu_overlap_trace、nccl_gpu_time_util_map、cuda_gpu_time_util_map、nvtx_pace。
通过 --backtrace=cuda 与 --python-backtrace=lbr 采集堆栈追踪，将 GPU 内核归因到 Python 函数或 PyTorch autograd 算子。
支持多种输出格式：stats 支持 column、csv、json、table、tsv、hdoc、htable；export 支持 sqlite、arrow/parquetdir、hdf、jsonlines、text；recipe 输出 CSV/Parquet 数据与 Plotly HTML 可视化及 .nsys-analysis Jupyter notebook。

使用方式

工作流 1：剖析深度学习训练脚本

在训练脚本中添加 profiler 标记以跳过预热：

for i, batch in enumerate(train_loader):
    if i == warmup_iters:
        torch.cuda.cudart().cudaProfilerStart()
    train_step(model, batch)
    if i == warmup_iters + profile_iters:
        torch.cuda.cudart().cudaProfilerStop()
        break

使用 cudaProfilerApi 捕获范围进行剖析：

nsys profile -c cudaProfilerApi \
    -t cuda,nvtx,cudnn,cublas \
    --pytorch=autograd-nvtx \
    -o train_profile -- python train.py

快速摘要：

nsys stats -r cuda_gpu_kern_sum,cuda_api_sum,cuda_gpu_mem_time_sum \
    train_profile.nsys-rep

检测反模式：

nsys analyze -r all train_profile.nsys-rep

工作流 2：诊断 GPU 空闲时间

nsys profile -t cuda,nvtx,osrt \
    --pytorch=autograd-nvtx \
    -o idle_debug -- python train.py

nsys analyze -r gpu_gaps,gpu_time_util idle_debug.nsys-rep

nsys stats -r cuda_kern_exec_sum idle_debug.nsys-rep

常见原因与修复：数据加载慢（增加 num_workers、使用 pin_memory=True）、同步 memcpy（使用 non_blocking=True）、过度同步（移除不必要的 sync 调用）、主机端计算（移至 GPU 或与异步操作重叠）、Python GIL 争用（使用多进程、减少 Python 开销）。

工作流 3：剖析分布式训练

nsys profile -t cuda,nvtx,mpi,ucx \
    --pytorch=autograd-nvtx \
    -o profile_%q{RANK} \
    -- torchrun --nproc_per_node=8 train.py

nsys recipe nccl_gpu_overlap_trace -- profile_*.nsys-rep
nsys recipe nccl_gpu_time_util_map -- profile_*.nsys-rep
nsys recipe cuda_gpu_time_util_map -- profile_*.nsys-rep

工作流 4：分析迭代时间一致性

nsys profile --pytorch=autograd-nvtx -t cuda,nvtx \
    -o iter_check -- python train.py

nsys stats -r nvtx_pushpop_sum iter_check.nsys-rep
nsys stats -r nvtx_gpu_proj_sum iter_check.nsys-rep
nsys recipe nvtx_pace -- iter_check.nsys-rep

工作流 5：通过堆栈追踪将内核归因到源码

nsys profile -t cuda,nvtx \
    --backtrace=cuda \
    --python-backtrace=lbr \
    --pytorch=autograd-nvtx \
    -o stacktrace_profile -- python train.py

nsys stats -r cuda_gpu_kern_sum stacktrace_profile.nsys-rep
nsys stats -r nvtx_kern_sum stacktrace_profile.nsys-rep

适用场景

端到端剖析深度学习训练脚本，定位 CPU/GPU 时间分布。
诊断迭代之间 GPU 空闲的原因。
多 GPU/多节点分布式训练的通信与计算重叠分析。
检查训练迭代时间的稳定性与离群值。
将昂贵的 GPU 内核归因到具体的 Python 函数或 PyTorch autograd 算子。
区分 cuDNN 卷积时间与 cuBLAS GEMM 时间，测量库级开销。

限制

不用于内核级优化，应使用 Nsight Compute（ncu）。
不用于 GPU 硬件指标如 SM 吞吐量、缓存命中率，应使用 ncu。
不用于无需剖析的 GPU 监控，应使用 nvidia-smi。
非 CLI 用法（GUI 工作流、IDE 集成）需查阅官方文档。
nsys 可能需要 sudo 或 CAP_SYS_ADMIN 权限进行系统级追踪与 GPU 指标采集；在容器中需使用 --privileged 或 --cap-add=SYS_ADMIN。
报告原则要求每个数字必须有权威来源，需引用 nsys stats 报告输出、nsys analyze 规则输出、导出的 SQLite 查询结果、recipe CSV 或原始命令输出，不得合成、估计或外推。
应使用 nsys stats 进行结构化分析，而非直接读取原始 trace 数据。

依赖与要求

依赖	版本	说明
CUDA Toolkit	>=11.0	包含 nsys
nsys 二进制	匹配 CUDA 版本	用 nsys -v 验证
NVIDIA GPU	任意受支持型号

错误处理

错误	原因	修复
nsys: command not found	不在 PATH 中	export PATH=$PATH:/usr/local/cuda/bin
Permission denied 或需要 root	需要提升权限	sudo nsys ... 或容器中 --cap-add=SYS_ADMIN
未捕获 CUDA 活动	应用在采集窗口内未使用 GPU	调整 --delay/--duration，或使用 cudaProfilerApi 捕获范围
报告文件非常大	长时间剖析且追踪大量 API	使用聚焦捕获（-c cudaProfilerApi），减少 --duration
--pytorch 无效	nsys 版本或 Python 环境错误	验证 nsys 版本支持 --pytorch；检查 Python 在 PATH 中
nsys stats 显示空报告	报告中无匹配活动	检查 --trace 标志是否包含正确的 API
MPI rank 剖析不同步	节点间时钟偏差	使用 NTP 同步；独立分析每个 rank
cudaProfilerStart 未捕获	缺少 -c cudaProfilerApi 标志	添加 --capture-range=cudaProfilerApi
recipe 因导入错误失败	缺少 Python 依赖	安装 recipe 依赖：pip install pandas plotly

技能介绍

用途