ROCm Compute Profiler概述：源码、安装、CLI、TUI

 在 GPU 性能调优链路中，采集、分析与可视化三者组成了完整闭环。rocprofiler-compute（又称 ROCm Compute Profiler）提供了一个以 Python/Dash 为核心的轻量级 Profiling 方案：它负责从 HIP 应用采集低层硬件计数器与 trace，支持命令行（CLI）、终端交互（TUI）以及独立 Web GUI 的分析展示，是快速定位 GPU 内核性能瓶颈的实用工具。本文汇总了源码结构、安装部署、常用命令与分析工作流，并给出实践中易忽略的注意事项与示例。

1 ROC Profiler Compute 源码结构

官方文档：ROCm Compute Profiler documentation

官方仓库：

https://github.com/ROCm/rocm-systems/

 源码目录结构：

tree projects/rocprofiler-compute/ -L 2
projects/rocprofiler-compute/
 ├── AUTHORS -- 列出项目贡献者的文件。
 ├── CHANGELOG.md -- 项目更新历史记录说明文件。
 ├── cmake
 │   ├── Dockerfile -- 用于构建 ROCm Profiler Compute 的 Docker 镜像。
 │   ├── modfile.crusher.mod -- 针对 Crusher GPU 的模块文件模板。
 │   ├── modfile.thera.mod -- 针对 Thera GPU 的模块文件模板。
 │   ├── rocm_install.sh -- 安装 ROCm 相关依赖的脚本。
 │   ├── rocprofcompute.lua.in -- Lua 配置模板，用于生成最终配置。
 │   └── VERSION.sha.in -- 版本哈希模板文件。
 ├── CMakeLists.txt -- CMake 构建配置主文件。
 ├── CONTRIBUTING.md -- 项目贡献指南。
 ├── docker -- 包含 Docker 相关构建和运行文件的目录。
 ├── docs -- 项目文档目录。
 ├── grafana
 │   ├── dashboards -- Grafana 仪表盘配置文件目录。
 │   ├── docker-compose.yml -- Grafana 服务的 Docker Compose 配置。
 │   ├── docker-entrypoint.sh -- 启动 Grafana 容器的入口脚本。
 │   ├── Dockerfile -- 用于构建 Grafana 容器镜像。
 │   ├── grafana.ini -- Grafana 配置文件。
 │   └── plugins -- Grafana 插件目录。
 ├── LICENSE -- 项目许可证文件。
 ├── MAINTAINERS.md -- 项目维护者列表和联系方式。
 ├── pyproject.toml -- Python 构建和依赖配置文件。
 ├── README.md -- 项目概览和快速入门说明。
 ├── requirements-test.txt -- 测试环境依赖 Python 包列表。
 ├── requirements.txt -- 项目运行依赖 Python 包列表。
 ├── sample -- 示例代码或数据目录。
 ├── src
 │   ├── argparser.py -- 命令行参数解析模块。
 │   ├── config.py -- 项目配置管理模块。
 │   ├── pycache -- Python 字节码缓存目录。
 │   ├── README.md -- src 目录说明文档。
 │   ├── rocprof-compute -- 核心计算模块实现目录。
 │   ├── rocprof_compute_analyze -- 数据分析模块。
 │   ├── rocprof_compute_base.py -- 核心基础类与工具函数模块。
 │   ├── rocprof_compute_profile -- 性能分析与采样模块。
 │   ├── rocprof_compute_soc -- SOC/硬件相关接口模块。
 │   ├── rocprof_compute_tui -- 命令行 TUI 用户界面模块。
 │   ├── roofline.py -- Roofline 性能分析工具模块。
 │   └── utils -- 辅助工具函数模块目录。
 ├── tests -- 测试代码目录。
 ├── utils -- 项目通用工具脚本目录。
 ├── VERSION -- 项目版本号文件。
 └── VERSION.sha -- 项目版本哈希文件。

2 ROCm Profiler Compute安装目录结构

安装和环境搭建参考：https://rocm.docs.amd.com/projects/rocprofiler-compute/en/latest/install/core-install.html。

安装ROCm的时候已经安装了ROCm Compute Profiler，需要通过如下命令解决依赖关系：

sudo apt install rocprofiler-compute

sudo update-alternatives --install /usr/bin/rocprof-compute rocprof-compute /opt/rocm/bin/rocprof-compute 0

python3 -m pip install -r /opt/rocm-7.0.1/libexec/rocprofiler-compute/requirements.txt --break-system-packages

项目代码主要为 Python（Dash/Plotly）实现，但提供 CMake 构建/安装流程用于生成可用的 bin/、libexec/、share/ 布局——用户按说明执行 cmake/make/install 即可完成安装（并非编译内核代码，仅是打包与安装脚本的执行）。：

cd rocprofiler-compute
echo "Manual" > VERSION.sha
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=../install
make -j
make install

安装后主要目录：

.
 ├── bin
 │   ├── rocprof-compute -> ../libexec/rocprofiler-compute/rocprof-compute -- 可执行的 rocprof-compute 命令的符号链接。
 │   ├── roofline-rhel8-rocm6 -- 针对 RHEL8 + ROCm6 的 Roofline 分析可执行文件。
 │   ├── roofline-rhel8-rocm7 -- 针对 RHEL8 + ROCm7 的 Roofline 分析可执行文件。
 │   ├── roofline-sles15sp6-rocm6 -- 针对 SLES15 SP6 + ROCm6 的 Roofline 分析可执行文件。
 │   ├── roofline-sles15sp6-rocm7 -- 针对 SLES15 SP6 + ROCm7 的 Roofline 分析可执行文件。
 │   ├── roofline-ubuntu22_04-rocm6 -- 针对 Ubuntu 22.04 + ROCm6 的 Roofline 分析可执行文件。
 │   └── roofline-ubuntu22_04-rocm7 -- 针对 Ubuntu 22.04 + ROCm7 的 Roofline 分析可执行文件。
 ├── libexec
 │   └── rocprofiler-compute
 │       ├── argparser.py -- 命令行参数解析模块。
 │       ├── config.py -- 配置管理模块。
 │       ├── requirements.txt -- 依赖的 Python 包列表。
 │       ├── rocprof-compute -- 核心可执行模块。
 │       ├── rocprof_compute_analyze -- 数据分析模块。
 │       ├── rocprof_compute_base.py -- 核心基础类与工具函数模块。
 │       ├── rocprof_compute_profile -- 性能采样与分析模块。
 │       ├── rocprof_compute_soc -- SOC/硬件接口模块。
 │       ├── rocprof_compute_tui -- 命令行 TUI 界面模块。
 │       ├── roofline.py -- Roofline 性能分析工具模块。
 │       ├── utils -- 辅助工具函数模块目录。
 │       ├── VERSION -- 版本号文件。
 │       └── VERSION.sha -- 版本哈希文件。
 └── share
 ├── doc
 │   └── rocprofiler-compute -- 安装后的文档目录。
 └── rocprofiler-compute
 ├── grafana -- Grafana 仪表盘及配置文件目录。
 ├── modulefiles -- 模块文件目录，用于环境模块加载。
 └── sample -- 示例代码或数据目录。

安装后的产物包括：

组件	位置	作用（简化）
rocprof-compute（主入口）	bin/rocprof-compute	CLI 主命令，统一入口（profile / analyze / tui / soc）
rocprof_compute_profile	libexec/rocprofiler-compute/	负责采集 GPU Profiler 数据（trace、metrics）
rocprof_compute_analyze	libexec/rocprofiler-compute/	对采集结果进行分析、生成报告或供 Web/TUI 使用
rocprof_compute_tui	libexec/rocprofiler-compute/	终端 TUI 界面，提供可视化展示（类似小型“nsight compute terminal”）
requirements.txt / utils / py 脚本	libexec/rocprofiler-compute/	工具内部 Python 实现逻辑（配置、解析、格式化、公共方法）

 

3. ROCm Profiler Compute介绍

Compute的使用分为3种模式：

• Profile Mode：在应用运行期间收集底层 GPU 性能数据。
• Analyze Mode：对采集结果进行后处理与展示。
• Database Mode：统一存储与管理 profiling 结果。

暂时无法在飞书文档外展示此内容

由“数据库模式为可选/历史方案，当前主流使用文件结果直接分析或使用内置 Web UI（Dash）显示；Grafana 方案需要额外部署时序/数据库后端（并非开箱即用）。Compute大致流程描述如下：

3.1 ROCm Profiller Compute模式

ROCm Profiler Compute主要分为两个阶段：Profile Mode（采集阶段） 和 Analyze Mode（分析阶段）。 它完成从 GPU 应用运行数据的采集，到结果展示与性能瓶颈定位的完整闭环。

3.1.1 Profile Mode（采集阶段）

参考：Profile mode。

目标： 从 HIP 应用执行过程中收集 GPU 性能数据。

流程说明：

1. HIP APP
   1. 用户编写的基于 HIP 的 GPU 程序（类似 CUDA 应用）。
2. Customize Data Collection（自定义采集）
   1. 指定要收集的性能事件或计数器（如 wavefront、LDS、memory、stall、occupancy 等）。
   2. 通过底层 rocprofiler / roctracer 接口实现。
3. Profile Results（结果生成）
   1. 数据被采集并保存为文件（通常为 .csv 或 .json）。
   2. 结果文件包含每个 kernel 的性能统计信息和时间线。

3.1.2 Analyze Mode（分析阶段）

目标： 对 Profile 结果进行后处理与展示。

分析可通过多种前端实现：

1. CLI Analysis（命令行分析）：使用命令行工具 rocprof 查看关键性能指标；适合脚本化、自动化性能评估。
2. TUI Analysis（终端交互分析）：提供交互式界面，在终端中浏览和筛选结果。
3. Standalone GUI Analysis（独立图形分析）：独立 GUI 工具，支持 kernel timeline、性能指标可视化。

注：去掉 MongoDB 后，Grafana GUI Analysis 不再适用。

3.1 使用方法（典型命令）

参考Profile mode进行Profile，比如：

rocprof-compute profile --name vcopy -- ./vcopy -n 1048576 -b 256

 

常用选项：

选项	作用	典型使用场景
-n, --name <workload>	设置本次 profile 的名称，也是输出目录名称。	区分不同测试，便于目录管理，例如 vcopy / gemm / roofline。
-k, --kernel K1 K2 ...	按 kernel 名过滤，只采集指定 kernel。	只想分析单个 kernel 或排除无关 kernel 时使用。
-b, --block ID1 ID2 ...	指定采集的 metric 或 hardware block。	缩小采集范围，减少开销，提高速度。
--hip-trace	采集 HIP API trace，用来查看 Host/Device timeline。	调试 Host 调用到 GPU 的时间线、排查瓶颈。
--roof-only	只采集 Roofline 数据，不做完整 profile。	想快速生成 Roofline PDF 性能图时使用。

 

输出通常包括：

tests/workloads/vcopy/MI350/
├── log.txt
├── perfmon
│   ├── pmc_perf_0.txt
...
│   └── SQ_LEVEL_WAVES.yaml
├── pmc_dispatch_info.csv
├── pmc_kernel_top.csv
├── pmc_perf_0.csv
...
└── sysinfo.csv

3.2 Profiler 架构解析

• 概览

  • rocprof-compute 做三件事：解析参数/校验依赖、选择模式（profile/analyze/database）、调度相应流程。
  • 核心控制类：RocProfCompute（rocprof_compute_base.py）。

• Profile 模式（数据流要点）

  1. 预处理：profiler.pre_processing() 生成 sysinfo.csv、准备 perfmon/ 文件夹并调用 SoC 的 profiling_setup()。
  2. 对每个 perfmon 输入，调用 get_profiler_options(fname, soc) 得到后端选项。
  3. 根据后端类型调用采集：
     • rocprofiler-sdk（SDK 分支）
       • 在 profiler_rocprofiler_sdk.py::get_profiler_options() 构造一个 dict，包含 APP_CMD（被测应用命令列表）和需写入的环境变量。
       • 关键：将 librocprofiler-sdk.so 与 librocprofiler-sdk-tool.so 放入 LD_PRELOAD，并设置 LD_LIBRARY_PATH、ROCP_TOOL_LIBRARIES、ROCPROFILER_* 等。
       • 在 utils.run_prof() / capture_subprocess_output() 中以 new_env 启动 APP_CMD，SDK .so 在被测进程被加载并在进程内初始化采集。
     • rocprofv1/v2/v3（Binary 分支）
       • 构造命令行参数列表并以 [rocprof_cmd] + args 启动子进程，由可执行文件完成采集。
  4. 后处理：profiler.post_processing()（合并 csv、格式化），调用 SoC 的 post_profiling()，生成最终输出。

• Analyze 模式

  • 选择分析器（CLI / web_ui / TUI），读取输入路径的 sysinfo.csv，调用 load_soc_specs(sysinfo)，运行 analyzer.run_analysis() 产出报告或 UI 展示。

• Database 模式

  • 使用 DatabaseConnector 做 import/remove（代码中标注为将弃用）。

• 关键文件定位（快速）

  • 参数解析：argparser.py（含 --rocprofiler-sdk-library-path）
  • 控制器：src/rocprof_compute_base.py::RocProfCompute
  • profiler 基类：profiler_base.py
  • SDK profiler：profiler_rocprofiler_sdk.py
  • 子进程与 env 管理：src/utils/utils.py::run_prof() 与 capture_subprocess_output()
  • SoC/平台：src/rocprof_compute_soc/ 各 soc_* 模块

3.3 Profiler 数据流程

一、配置如何使 profile 生效（简要链路）

1. 配置来源

   • 命令行参数（优先）：--rocprofiler-sdk-library-path、--path、--name、--kernel、--dispatch、--format-rocprof-output 等（定义在 argparser.py）。
   • 默认/静态配置：config.py 中的一些默认路径与常量。
   • 环境变量（影响 profiler 选择）：例如 ROCPROF（在 src/utils/utils.py::detect_rocprof() 中读取）。

2. 解析与初始化（使配置进入运行时）

   • 入口脚本实例化 RocProfCompute（rocprof_compute_base.py）。
   • RocProfCompute.parse_args() 调用 omniarg_parser 解析 CLI，解析结果放在 self.__args（后续全程使用）。
   • verify_deps() 检查 Python 依赖（入口脚本中调用），失败会退出。

3. 将配置固化到运行目录/文件（便于子进程/后续查看）

   • 在 profile 流程开始时写入 profiling_config.yaml（在 run_profiler() 中：把 vars(self.__args) 写到 <path>/profiling_config.yaml），并通过 setup_file_handler() 启用文件日志。

4. 根据配置选择 profiler 实现

   • detect_rocprof()（utils.py）结合 ROCPROF 环境与 --rocprofiler-sdk-library-path 决定使用哪种后端：rocprofv1/v2/v3（binary）或 rocprofiler-sdk（SDK 注入）。
   • RocProfCompute.run_profiler() 根据该选择实例化相应的 profiler 子类（例如 profiler_rocprofiler_sdk.py）。

5. 配置到运行时参数的转换（关键一步）

   • 对每个 perfmon 输入文件，调用 profiler.get_profiler_options(fname, soc)（不同 profiler 的实现不同）：
     • Binary 分支：返回命令行参数列表传递给 rocprof 可执行文件。
     • SDK 分支：返回一个 dict，包含 APP_CMD（被测应用命令列表）和要注入到子进程的环境变量（LD_PRELOAD、LD_LIBRARY_PATH、ROCP_TOOL_LIBRARIES、ROCPROFILER_* 等）。
   • 这些由 CLI / defaults 组合后形成最终的“运行时选项”。

二、profiler 的数据流（从输入到产出）
总体流程（高层）

• 输入：perfmon/*.txt（定义要采集的 counters）、命令行（-- 后的被测程序命令）。
• 核心函数顺序（关键文件）：
  1. RocProfCompute.run_profiler()（rocprof_compute_base.py）：
     • 调用 profiler.pre_processing() 进行环境/文件准备（调用 gen_sysinfo、SoC 的 profiling_setup() 等）。
     • 写 profiling_config.yaml 并启用文件日志。
     • 遍历 perfmon/*.txt，对每个文件执行一次采集（调用 profiler.get_profiler_options() -> run_prof()）。
  2. profiler.get_profiler_options()（在对应 profiler 文件，例如 profiler_rocprofiler_sdk.py 或 v1/v2/v3 实现）：
     • 将 CLI/filters/SoC 信息转换为后端可用的选项（二进制命令或 env dict）。
  3. utils.run_prof() / capture_subprocess_output()（utils.py）：
     • Binary：执行 [rocprof_cmd] + args（子进程），由 rocprofvX 可执行生成 csv/json。
     • SDK：取出 APP_CMD，把 options 的 env 写入 new_env（复制当前 env），然后以 capture_subprocess_output(APP_CMD, new_env=new_env) 启动被测程序子进程。因为 LD_PRELOAD 包含 librocprofiler-sdk.so 与 tool.so，动态链接器会在该子进程加载这些 .so，SDK 在目标进程 ctor 中初始化并开始采集。
  4. 采集输出：SDK 或 rocprof binary 将生成中间输出（如 out/pmc_1/ 下的 json/csv/timestamps 等）。
  5. 后处理：
     • profiler.post_processing()（在 profiler 实现中）与 profiler.join_prof()（合并 pmc_perf_*.csv 等，见 profiler_base.py）。
     • SoC 的 post_profiling() 执行平台相关收尾。
     • 最终写出 results_<workload>.csv、日志和分析输入。

3.4 Profiler 使用到的技术

技术	用途（在项目中）	关键文件 / 函数
Python 3.8+	主实现语言与运行时	整个 src/ 目录
argparse	命令行解析、子命令与选项	argparser.py、RocProfCompute.parse_args()
自定义 logger	控制台与文件日志、级别控制	utils/logger.py、setup_file_handler()
subprocess + selectors	启动子进程并实时读取 stdout/stderr	utils.capture_subprocess_output()、utils.run_prof()
LD_PRELOAD / LD_LIBRARY_PATH	将 librocprofiler-sdk.so 注入被测进程	profiler_rocprofiler_sdk.get_profiler_options()、utils.run_prof()
rocprof / rocprofiler‑sdk	采集后端（binary 或 SDK 注入）	utils.detect_rocprof()、profiler_* 实现
PyYAML (yaml)	读写 counter 定义与 profiling_config.yaml	run_profiler() 写 config、utils 中读取/写入 counter defs
Pandas	读取/合并/处理 CSV 结果	utils.v3_json_to_csv()、profiler_base.join_prof()
JSON	解析 SDK/v3 输出并转为 CSV	utils.v3_json_to_csv()
importlib (动态导入)	按架构加载 soc_* 和插件式模块	rocprof_compute_base.load_soc_specs()
pathlib / shutil / tempfile / glob	文件/目录管理、临时文件、查找中间产物	utils.run_prof()、profiler_base.join_prof()
shlex / sed (shell 工具)	解析应用命令字符串；在子进程前修改 perfmon 文件	profiler_rocprofiler_sdk.get_profiler_options()（shlex）；profiler_base.run_profiling()（sed 调用）
re (正则)	解析/规范化文本、CSV 列名处理	多处（utils、profiler_base.join_prof()）
CMake / CTest / pytest	构建与集成测试（rocprofiler-sdk 测试）	rocprofiler-sdk/.../CMakeLists.txt（见附件）
importlib.metadata	检查已安装包与版本（依赖校验）	入口脚本 verify_deps() 使用
mi_gpu_specs / MachineSpecs	GPU/SoC 规格建模及平台特化	utils.mi_gpu_spec、utils.specs、rocprof_compute_soc/

 

 

3.5 CLI Analysis

主要功能如下：

• 加载已采集的 profiling 结果（指定 --path 或 -p 指定目录）用于命令行分析。
• 支持过滤分析对象，比如按内核名（kernel）、按 dispatch ID、按硬件模块块（block）等进行子集分析。
• 支持生成不同报表形式：例如总结各内核执行时间、各硬件模块指标、统计聚合视图。
• 附带轻量的终端交互界面（TUI）选项，用于在终端里对结果进行交互查看。
• 支持将分析结果导入数据库或 GUI 模式，以便在 Grafana 等可视化平台中进一步分析。即使这是偏 “analyze” 模式之外，但分析命令为分析流程的一部分。

查看Metric：

rocprof-compute analyze -p workloads/vcopy/MI200/ --list-metrics gfx90a

查看报告：

rocprof-compute analyze -p workloads/vcopy/MI300X_A1/ > vcopy_MI300X_A1.txt

4 TUI（终端界面）详细介绍

4.1 使用方法

使用如下命令启动TUI：

rocprof-compute analyze --tui

启动后会显示：工作目录选择、分析运行日志、中心分析面板（Top Kernels、Dispatch 列表、System Info、Roofline、Memory Chart、各类 metric 表格）、可交互终端和指标详细描述面板。

4.2 TUI 技术点

技术	用途（在项目中）	关键文件 / 函数（可定位）
Textual (TUI 框架)	构建 TUI 界面、容器、事件与生命周期	main_view.py、tui_app.py、各 src/rocprof_compute_tui/widgets/*
Rich (渲染/ANSI)	渲染终端富文本与 ANSI 输出（与 Textual 配合）	tabs_terminal.py（Text.from_ansi）
Pandas	处理分析数据表（DataFrame），供表格与图表渲染	tui_utils.py（process_panels_to_dataframes 等）
YAML (PyYAML)	配置 TUI 面板/布局（驱动哪些 section/subsection 显示）	analyze_config.yaml；加载于 widgets/collapsibles.py::load_config
plotext + textual_plotext	在终端绘制 ASCII 图（柱状、箱线等）并嵌入 Textual	charts.py（simple_bar、MemoryChart 使用 plotext / PlotextPlot）
Plotly (plotly.express)	生成复杂图表（用于导出或更丰富展示）	charts.py（px_simple_bar 等）
DataTable / Collapsible widgets (Textual)	折叠面板与数据表展示（表格交互、行选择）	collapsibles.py（create_table）、analyze_view.py
自定义 Logger（UI 日志）	将运行日志写入 TUI 下方 Output 区	src/rocprof_compute_tui/utils/tui_utils.py::Logger；main_view.py 中使用
subprocess / shell	终端面板执行 shell 命令并显示输出	src/rocprof_compute_tui/widgets/tabs/tabs_terminal.py::run_command
importlib.resources / pathlib	载入内置资源（如 YAML）与路径管理	analyze_view.py（加载 analyze_config.yaml），多处用到 pathlib
正则 / 文本解析	解析分析输出的 ASCII 表格并转换为 DataFrame	tui_utils.py（parse_ascii_table / parse_file）
plot_mem_chart (自定义)	绘制内存图表（由项目工具生成 ASCII 输出）	charts.py 调用 utils.mem_chart.plot_mem_chart
UI 交互事件	表格行点击、背景线程更新 UI、菜单交互	views/main_view.py::on_data_table_cell_selected、run_analysis（使用 @work(thread=True)）

 

5 补充

5.1 为什么 SQLite 是最适合 Profiler 数据的？

支持：

• 查询大（100–500MB）数据依然快
• SQL 适合 timeline/metric 按 kernel 查询
• 支持索引、事务
• 跨平台
• TUI/WebUI 可以共享同一数据层

如果你要开发自己的 profiling 工具，SQLite 必须优先考虑。

5.2 架构复用建议

通用的 GPU/CPU profiler架构：

• Runtime（数据采集）
• Engine（metric 计算）
• Storage（SQLite）
• Tools：
  • CLI（采集，查看）
  • TUI（快速分析）
  • WebUI（深度可视化）