rocprofiler-systems-choosing-a-profiling-preset

选择性能分析预设

根据所描述的工作负载，推荐一个 rocprofiler-systems 内置的运行时性能分析预设，并返回运行该预设的准确命令。

前提条件

要根据下表首次给出建议，无需满足任何条件。要确认某个预设的设置（参见“使用 --explain 确认”）并运行命令，必须已安装或构建 rocprof-sys-run 或 rocprof-sys-sample。

版本检查

预设需要 ROCm Systems Profiler 1.6.0 或更高版本（ROCm 7.13.0）。使用 rocprof-sys-run --version 检查，输出首行格式为 rocprof-sys-run v<major>.<minor>.<patch> ...。

已安装版本	告知用户的内容
1.6.0 或更高版本	--preset=<name>、--list-presets 和 --explain=<name> 均可使用。
1.5.x（ROCm 7.12.0）	预设仅可通过 --<name> 标志使用（例如 --balanced），不支持 --preset=、--list-presets 或 --explain。提供这种形式并建议升级。
低于 1.5.0	不支持预设。建议升级，或手动配置设置。

较新的预设名称可能不受较旧版本支持，因此 --list-presets 列出的是已安装版本支持的预设。如果无法检查版本，提供 --preset= 命令，并说明需要 1.6.0 或更高版本。

术语

此处的“Trace”和“tracing”含义不同。回答中务必将二者区分开来。

术语	含义	设置
Perfetto 跟踪输出	写入 Perfetto 格式的时间线文件	ROCPROFSYS_TRACE
rocPD 输出	写入 rocPD 数据库	ROCPROFSYS_USE_ROCPD
Profile 输出	写入 timemory 性能分析文件（扁平或基于调用栈）	ROCPROFSYS_PROFILE
调用栈采样	以固定频率对 CPU 调用栈进行采样	ROCPROFSYS_USE_SAMPLING
API 跟踪	拦截并记录某个 API 的调用	见下文

API 跟踪按 API 分别选择：ROCm（ROCPROFSYS_ROCM_DOMAINS）、MPI（ROCPROFSYS_USE_MPIP）、RCCL（ROCPROFSYS_USE_RCCLP）、OpenMP（ROCPROFSYS_USE_OMPT）和 Kokkos（ROCPROFSYS_USE_KOKKOSP）。所有内置预设默认都会启用 ROCm API 跟踪，跟踪 HIP 运行时 API、ROCTx 标记、内核调度、内存复制和暂存内存。预设可能会缩小或扩大此范围，而 --rocm=<domains> 会覆盖该设置。

API 跟踪与输出选择无关。预设中的 tracing.enabled: false（或 ROCPROFSYS_TRACE=false）会关闭 Perfetto 跟踪输出，而非 API 跟踪。采集到的数据会写入已启用的输出：Perfetto、rocPD 或性能分析文件。说某个预设“关闭了 tracing”时，务必说明指的是哪一种。

预设参考

此处仅用于选择：说明哪种需求适合哪个预设，并不确切说明每个预设具体设置了什么。具体设置以已安装的二进制文件为准（参见“使用 --explain 确认”）。

预设	类别	用例
balanced	通用	推荐的默认预设，开销适中
profile-only	通用	开销最低的扁平性能分析（生产环境）
detailed	通用	最大深度，开销高
trace-gpu	GPU	GPU 活动时间线（内核调度、内存复制）
trace-hw-counters	GPU	GPU 硬件计数器（占用率、VALU 利用率）
workload-trace	GPU	AI/ML 训练、长时间运行的 GPU/HPC 工作负载
trace-hpc	HPC	计算密集型 MPI/OpenMP/Kokkos/RCCL 应用，包含 CPU 计数器（PAPI）
trace-openmp	HPC	OpenMP GPU 目标卸载应用
profile-mpi	HPC	MPI 通信延迟、扁平性能分析，不生成 Perfetto 跟踪
sys-trace	跟踪	调试运行时层交互，最广泛地跟踪 ROCm API（HIP、HSA、ROCTx、RCCL）
runtime-trace	跟踪	与 sys-trace 相同，但不包含 HSA/编译器 API

如何选择

按顺序判断；第一个能将选项缩小到单个预设的问题就是答案。不要要求用户在某个步骤适用前先说出 MPI 之类的运行时。

1. API 跟踪或调试。 关于 HIP、HSA 或运行时层行为的问题（例如“为什么我的 HIP 调用行为异常”“HSA 在底层做了什么”）→ sys-trace（完整的 ROCm API 跟踪），或者在应排除 HSA 和编译器 API 噪声时使用 runtime-trace。

2. 一项指定的测量。

   • GPU 硬件计数器，例如占用率或 VALU 利用率 → trace-hw-counters。
   • MPI 通信延迟是唯一关注点，不需要 Perfetto 跟踪文件 → profile-mpi。
   • OpenMP GPU target-offload 内核 → trace-openmp。

3. 长时间运行的 GPU 工作。 AI/ML 训练，或需要 MPI 和 RCCL API 跟踪以及大型 Perfetto 跟踪缓冲区的长时间运行、GPU 加速型 HPC 作业 → workload-trace。即使训练作业完全没有提到 MPI，也符合此选项；如果提示词同时提到 MPI 或 OpenMP，则优先于第 4 步。

4. HPC 运行时。 计算密集型 MPI、OpenMP、Kokkos 或 RCCL 应用 → trace-hpc。它会生成 Perfetto 跟踪，跟踪这些运行时的 API，并设置 CPU 硬件计数器事件（PAPI）。如果用户既不需要跟踪文件，也不需要计数器，profile-mpi 或 balanced 不会生成 Perfetto 跟踪。

5. GPU 活动。 内核分派或设备活动（GPU 活动时间线），且未说明上述目标 → trace-gpu。

6. 通用性能分析。 根据开销容忍度和深度选择：

   • 最低开销、快速的扁平性能分析（例如生产环境）→ profile-only；它会关闭 Perfetto 跟踪输出、rocPD 输出和调用栈采样，但 ROCm API 调用和内核仍会出现在扁平性能分析中。
   • 追求最大深度，且愿意接受高开销 → detailed。
   • 其他情况，或通用性能分析的良好默认选项（性能分析输出、rocPD 输出、调用栈采样和 GPU 指标，不生成 Perfetto 跟踪）→ balanced。

使用 --explain 确认

这些预设已编译到已安装的二进制文件中，因此 --explain 与用户的构建版本完全匹配，而上表可能滞后于实际情况。确定候选项后：

1. 将 rocprof-sys-run --explain=<name>（或 rocprof-sys-sample --explain=<name>）作为单条命令运行，前面不要加 command -v 检查或 && 链。将其 ROCPROFSYS_* 列表作为该预设的事实依据。引用与用户目标相关的设置；如果这些设置与表格或你的首选不一致，则以 --explain 为准。
2. 如果找不到命令或命令无法运行，则使用表格，并说明这些设置尚未确认。

输出

返回确切的调用命令。默认使用 rocprof-sys-run：

rocprof-sys-run --preset=<name> -- ./myapp

两个工具都接受相同的 --preset，而启用 sampling.enabled 的预设会覆盖任一工具的默认行为：balanced 会让两者都以 50 Hz 采样，profile-only 则会让两者都关闭调用栈采样。只有当预设未指定采样行为时（例如 trace-gpu），两个工具才有所不同：rocprof-sys-sample 会开启调用栈采样，而 rocprof-sys-run 会保持关闭。因此，当用户需要调用栈采样，且预设尚未启用该功能时，应使用 rocprof-sys-sample：

rocprof-sys-sample --preset=<name> -- ./myapp

用一行说明推荐的预设会开启哪些功能、会关闭哪些功能，并使用上述术语，让用户了解能获得什么以及需要放弃什么。例如，profile-only 会生成一份平面分析报告，不会生成 Perfetto 跟踪文件或 rocPD 数据库，也不会进行调用栈采样；但 ROCm API 调用和内核仍会出现在分析报告中。

如适用，请说明：

• Domain 标志（--gpu、--rocm、--cpu、--parallel）可叠加到任意预设上，以添加或覆盖特定指标，例如 rocprof-sys-run --preset=balanced --gpu=temp,power -- ./myapp。当用户的需求无法很好地匹配某个预设时，可采用这种方式：从 balanced 开始并进行扩展。
• 用户可以通过 --explain=<name> 和 --list-presets 自行验证选择。
• --export-config=<file>.json 会将解析后的预设和覆盖项保存为可重复使用的 JSON 配置——这是自定义预设的受支持方式，不应手动编辑随附的 JSON 文件。
• 自定义预设的文件格式遵循安装在 <install-prefix>/share/rocprofiler-systems/presets/schema.json 的 JSON schema。

常见错误

错误	修正方法
将其与用于 构建 rocprofiler-systems 的 CMake --preset debug|release|ci 混淆	构建预设用于配置编译；分析预设用于配置分析 运行。此技能仅介绍后者。
查找内置预设的 JSON 文件并尝试编辑	内置预设已编译进二进制文件，并未作为文件安装。使用 --explain=<name> 查看预设，并使用 --export-config 生成可编辑副本。
只是想“获取一些数据”时默认选择 detailed	除非用户明确需要最大深度且能接受更高开销，否则默认使用 balanced。