bash-metric 0.4.0

Nsight Systems + Nsight Compute profiling pipeline and analyzers.

ncu_nsys_profiler_pack（bash_metric 子仓库）

本子仓库提供一套以 Bash 为主的 Nsight Systems（nsys）+ Nsight Compute（ncu）采集与汇总流水线，适用于对深度学习推理/训练脚本进行端到端的 GPU 性能画像与瓶颈分析。

一键采集并汇总以下 GPU 性能指标：

• 算力单元利用率（SM/Tensor/FP32）
• Cache 命中率（L1/TEX/L2）
• 内存带宽（DRAM 吞吐占峰值）
• Warp 效率（Barrier/Short/Long Scoreboard stalls）
• Kernel 耗时（来自 Nsight Systems cuda_gpu_kern_sum）
• 整体推理瓶颈（基于 SM/DRAM/Cache 的启发式：Compute / Memory / Mixed / Memory/Latency）

目录结构与作用

• bash_metric/：Python 包源码
  • run_profiling.py：端到端采集（nsys + ncu）主流程，提供 bash-metric-run CLI。
  • parse_and_plot.py：解析 ncu/nsys CSV 并绘制图表，提供 bash-metric-parse CLI。
  • methods/nsys_ncu_all/：全流程捕获与 Top-N 解析脚本（Python + Bash），提供 bash-metric-capture-all 与 bash-metric-analyze-topk CLI。
  • targets.tsv：默认目标列表示例，安装后可作为模板复制修改。
  • fonts/：内置常用中文字体（若系统缺字形时自动注册）。
• requirements.txt：与 pixi 默认环境一致的依赖清单，可供手工安装参考。
• out/：示例输出目录（包安装后不会自动创建，可通过环境变量自定义）。

依赖

建议使用 pixi 默认环境（python 3.10 + Nsight CLI）。如单独安装，可执行：

pip install bash-metric

运行时仍需确保系统已安装 nsys 与 ncu 并可在 PATH 中找到。

目标列表

编辑 targets.tsv（TSV 四列，使用 TAB 分隔）： NAME<TAB>CMD<TAB>WORKDIR<TAB>ENVS

示例：

NAME	CMD	WORKDIR	ENVS
bert_inf	python infer.py --bs 8 --seq 128	./models	CUDA_VISIBLE_DEVICES=0
resnet_train	python train.py --epochs 1	./cv	CUDA_VISIBLE_DEVICES=0

WORKDIR 或 ENVS 可留空（用 - 表示）。ENVS 多个变量用逗号分隔，如 A=1,B=2；留空或 - 不会传给 env，避免破坏 PATH。

运行

推荐：安装后直接使用 CLI

bash-metric-run --targets /path/to/targets.tsv --topn 10

完成采集后，可单独解析历史结果：

bash-metric-parse /path/to/out_group --log /path/to/out_group/run.log

若只想执行捕获阶段或后处理阶段，可分别调用：

bash-metric-capture-all --targets xxx.tsv
bash-metric-analyze-topk --targets xxx.tsv

源码运行（任选）

python -m bash_metric.run_profiling
python -m bash_metric.parse_and_plot ./out --log ./out/run.log

运行后默认在 out/ 会看到：

• nsys/<id>.nsys-rep 与 <id>_cuda_gpu_kern_sum.csv（Kernel 耗时/占比）；
• ncu/<kernel>/*.ncu-rep 与 *_ncu_raw.csv、*_metrics_id.csv；
• profile_and_report.log：单一全局日志，记录所有目标的全部阶段输出，重复执行会覆盖重写；
• summary_*.csv/.md 与 figs/*.png。

运行阶段与进度打印

bash-metric-run 会将每个目标的执行划分为 6 个阶段，并打印进度：

1. 准备目录与上下文
2. nsys 采集
3. nsys 导出 CSV
4. 生成 TopN kernel 正则
5. ncu 采集
6. ncu 导出 raw CSV

每步开始会打印 [STEP x/6] 开始：...，完成后打印 [STEP x/6] 完成：...；剩余 n 步，失败时打印 [STEP x/6] 失败：... 并依据 CONTINUE_ON_ERROR 决定是否继续。

日志记录与配置

• 全局日志：out/profile_and_report.log（每次运行覆盖重写）。
• 自定义路径：运行前设置 GLOBAL_LOG=/path/to/run.log。
• 自定义输出根目录：设置 OUT_DIR（默认 ./out）。
• 自定义目标表路径：设置 TARGETS_TSV（默认读取脚本同目录的 targets.tsv）。
• 查看运行过程：
  • tail -f out/profile_and_report.log
  • 或 less +F out/profile_and_report.log

附加开关（方法脚本）：

• NCU_MULTI_RUN：1（默认）逐核运行，多份 .ncu-rep 与 *_raw.csv；0 单次运行合并正则，生成一份 .ncu-rep 与 *_raw.csv。
• BASH_BIN：指定 Bash 解析器（默认 /bin/bash），用于应用命令的 -lc 执行。

重要开关（健壮性与可重复）

• NVTX 非强依赖：默认 CAPTURE_RANGE=none。若你给应用插了 NVTX，可设：
  • CAPTURE_RANGE=nvtx，并可选 NVTX_NAME="range@domain"（同 nsys -p）。
  • 若使用 NVTX 动态字符串，建议 export NSYS_NVTX_PROFILER_REGISTER_ONLY=0 以捕获非注册字符串。
• 重复运行/覆盖输出：nsys stats 已加 --force-export=true --force-overwrite=true，确保从最新的 .nsys-rep 重新导出并覆盖同名 CSV。
• ncu 多进程：默认 --target-processes all。需要更强可比性时，可改用 --replay-mode application 与合适的 --app-replay-match。
• ncu 指标集：为兼容不同 ncu 版本，默认使用 --set speed-of-light（当 NCU_FAST=1）或 --set full，避免 section 名称差异造成错误。可通过 NCU_SET 覆盖。
  • 相关开关：NCU_FAST、NCU_SET、NSYS_TRACE、NSYS_CAPTURE_RANGE/NSYS_CAPTURE_RANGE_END、NSYS_DURATION、NSYS_QUIET。
• 缓存/频率控制：默认 --cache-control all --clock-control base 以提高多次回放的一致性；若想保留“真实缓存状态”，可把 cache-control 改为 none。

参考（命令出处）

• Nsight Systems 用户指南（--capture-range/NVTX 捕获、TMPDIR、stats 报表/CSV、--force-export 与 --force-overwrite 等）。
• Nsight Compute CLI 文档（--page raw --csv、--import、--metrics、--kernel-name-base/--kernel-name、--target-processes all、--cache-control、--clock-control、回放与匹配等）。

本子仓库即用于批量采集与汇总 GPU 指标，适合在 ncu_dir 环境中，对 YOLO 或其它脚本进行快速端到端画像。