XProf CLI工具手册:命令行快速提取KPI指标、Top HLO算子与利用率的完整清单
XProf CLI工具手册:命令行快速提取KPI指标、Top HLO算子与利用率的完整清单
🚀 XProf 是面向机器学习负载(JAX / TensorFlow / PyTorch)的开源性能分析工具,而其 XProf CLI(xprof 命令行)让你不用打开浏览器,就能快速提取 KPI 指标、Top HLO 算子和加速器利用率,是 TPU/GPU 性能调优的高效率入口。本文提供一份面向新手的完整命令清单,5 分钟上手。
一、3 步开始使用 XProf CLI
第 1 步:安装
pip install -U 'xprof>=2.24.0'
第 2 步:准备 Profile 数据
XProf 的 profile 数据存放在 <log_dir>/plugins/profile/<session_name>/ 目录下(内含 .xplane.pb 文件)。仓库自带两个示例会话,可以直接拿来练习:
第 3 步:运行子命令
# 查看可用子命令
xprof -h
# 基本调用格式:xprof <command> <path_to_trace_or_logdir> [flags...]
xprof get_kpi_metrics demo/plugins/profile/v6e-4-training
💡 所有子命令都以 JSON 输出到 stdout,可直接 | jq 做二次处理。命令清单的完整说明见 plugin/xprof/cli/README.md,入口实现在 xprof_cli.py。
二、一键提取 KPI 指标:get_kpi_metrics
想知道一次训练跑得快不快,先看 KPI(Key Performance Indicators):步长、设备忙闲比、峰值内存,一条命令全拿到:
xprof get_kpi_metrics <logdir> [--bypass_cache=True]
返回的 JSON 包含这些核心字段(定义见 get_kpi_metrics_tool.py):
| 字段 | 含义 |
|---|---|
step_time_ms |
平均步长(毫秒) |
duty_cycle_percent |
设备忙闲比(duty cycle,越高越好) |
mxu_utilization_percent |
硬件性能计数器测得的矩阵单元利用率;为 null 表示未采集到计数器,不是 0% |
compute_efficiency_percent |
程序 FLOP 速率相对设备峰值 FLOP 的比值(成本模型值) |
roofline_utilization |
相对 roofline 的 FLOP 速率利用率 |
peak_hbm_gib |
峰值 HBM 显存占用 |
accelerator_info |
设备类型与核心数 |
⚠️ 两个易踩的坑:
- 多机场景:
step_time_ms取的是所有 host 上每步的最大值,输出中会带step_time_scope: "per_step_max_across_hosts"和per_host_step_time_ms,排查慢节点(straggler)时重点看后者; - 计数器缺失:当
mxu_utilization_percent为null时,输出会附带mxu_utilization_status,里面有reason和how_to_get提示(例如重新用tpu_perf_counters=True采集)。
参数细节参考:skills/xprof/references/get_kpi_metrics.md
三、锁定耗时大户:Top HLO 算子(get_top_hlo_ops)
定位"时间都去哪儿了",最有效的方法是看 Top HLO 算子。该命令一次性给出三个排行榜:按 Self Time、按 FLOPs、按访存量(Bytes Accessed) 排序,直接暴露计算瓶颈和访存瓶颈:
# 每个榜单默认返回 Top 10
xprof get_top_hlo_ops <logdir>
# 指定数量 + 按类别过滤(如只看 convolution)
xprof get_top_hlo_ops <logdir> --limit=20 --category_filter=convolution
# 返回全部匹配算子
xprof get_top_hlo_ops <logdir> --limit=0
每个算子条目不仅包含 total_self_time_ms、flops、bytes_accessed 等指标,还会带上 Python 源码定位(source_file、source_line、stack_frame),可以直接跳转到模型代码:
{
"name": "by_program/jit_train_step/convolution fusion/fusion.822",
"category": "convolution fusion",
"total_self_time_ms": 84.15,
"flops": 5.9e13,
"bytes_accessed": 7.9e10,
"source_file": "layers/linears.py",
"source_line": 99
}
📌 注意:--limit 是每个榜单各自截断,统计总量请读 total_records / total_self_time_ms_all_records 字段,而不是自己累加列表。另外,若 trace 中缺少 HLO op profile 数据,需确保编译时使用了 XLA_FLAGS='--xla_dump_to=<logdir> --xla_dump_hlo_as_proto'。
四、查看硬件利用率:get_utilization_viewer 与 get_kernel_utilization
想确认 TPU 各计算单元(MXU、XLU、向量单元等)的真实忙闲程度,用 Utilization 类命令:
# 按 Host / Device / Node 过滤查看单元级利用率
xprof get_utilization_viewer <logdir> [--host=0] [--device=0] [--node=0]
# 基于硬件性能计数器的内核级利用率
xprof get_kernel_utilization <logdir>
📖 原理提示:get_kernel_stats 在 include_summary=True 时,会用**不相交区间并(Disjoint Interval Union)**扫描线算法合并多个硬件平面(计算、DMA/ICI 传输)的活跃区间,精确统计设备真实计算时长——既不会把重叠执行重复计数,也不会把步间空闲时间算进去。源码见 get_utilization_viewer_tool.py。
五、进阶:判断计算瓶颈还是带宽瓶颈(get_roofline_model)
拿到 KPI 后,下一个问题通常是"为什么 FLOP 利用率上不去"。用 Roofline 模型回答——它会给出程序级算术强度(FLOP/Byte)、瓶颈边界以及逐算子的 bound 分析:
xprof get_roofline_model <logdir> [--top_n=15]
输出中 program.bound_by 会直接告诉你当前是 "HBM"(带宽瓶颈)还是计算瓶颈,roofline_efficiency_percent 给出 roofline 效率。
六、完整命令速查清单
| 命令 | 用途 |
|---|---|
xprof get_kpi_metrics |
KPI 一键汇总(步长/忙闲比/利用率/峰值内存) |
xprof get_overview |
高层性能总览(Compute/Host/Communication 拆分、步长图) |
xprof get_top_hlo_ops |
Top HLO 算子三榜(Time / FLOPs / Bytes) |
xprof get_hlo_op_profile |
HLO 算子 profile 明细表 |
xprof list_hlo_modules / get_hlo_text |
列出 HLO 模块 / 查看编译后的 HLO 文本 |
xprof get_utilization_viewer |
单元级硬件利用率 |
xprof get_kernel_utilization |
基于硬件计数器的利用率 |
xprof get_roofline_model |
Roofline 效率与瓶颈分析 |
xprof get_memory_profile |
显存容量、峰值占用、碎片率 |
xprof get_peak_allocations |
按 HBM 用量排序的峰值分配列表 |
xprof list_xplane_events |
流式输出时间线执行事件 |
xprof get_hosts |
列出 session 中的主机与工作节点 |
xprof get_device_information |
硬件拓扑与理论峰值常量 |
xprof upload_trace |
把 .xplane.pb 导入 logdir |
🔍 每个子命令都支持
xprof <command> -h查看完整参数。
七、新手常见问题(避坑指南)
1️⃣ 时间戳形式的 session 名要加引号吗?
带下划线的时间戳(如 2026_08_17_22_58_50)会被参数解析器误认为数字字面量。CLI 已内置预处理自动加引号处理;手动指定 --session_id 时使用 --session_id='"2026_08_17_22_58_50"' 最稳妥。
2️⃣ 结果会缓存吗?
会。多数工具结果缓存 24 小时。对同一个 session 重复采集后重新分析,记得加 --bypass_cache=True,否则会拿到上次的结果。
3️⃣ 输出超过 10 MB 会怎样?
CLI 会自动把输出落盘并返回 status: "SAVED_TO_FILE" 的 JSON 信封(含 file_path),用 jq 直接查询该临时文件即可,避免撑爆终端缓冲区。
4️⃣ 多机 trace 如何看单台机器?
run 目录里每台主机/每个 rank 一个 .xplane.pb。直接传文件路径或 --host=<name>(名字可用 xprof get_hosts <dir> 查询)即可只看单台。
5️⃣ 找不到 .xplane.pb 文件?
CLI 会报 DATA_ABSENT。确认目录结构为 <log_dir>/plugins/profile/<session_name>/*.xplane.pb;目录内找不到 trace 时会明确列出原因。
八、总结
XProf CLI 把"打开网页 → 找图表 → 读数"的繁琐流程压缩成了三条命令:
get_kpi_metrics看整体表现(步长、duty cycle、利用率);get_top_hlo_ops锁定最贵的算子,并直接映射回 Python 源码行;get_utilization_viewer/get_roofline_model深挖硬件级瓶颈。
配合 jq 和脚本,这套命令行工具可以无缝接入 CI 性能回归。完整的命令参考文档在 skills/xprof/references/,工具实现在 plugin/xprof/cli/tools/,建议收藏备查 📚



