rocprofiler-systems-discovering-profiling-options

发现性能分析选项

将“有哪些可用选项”或“如何配置 X”这类问题，映射到能够回答问题的确切 rocprof-sys-avail / rocprof-sys-run --help=<topic> 命令。 rocprof-sys-avail 会自动更新，且是权威信息来源——优先运行它，而不是 复述静态文档。

前提条件

需要有可正常使用的 rocprof-sys-avail 二进制文件，并与 rocprof-sys-run/rocprof-sys-sample 一同构建或安装。如果它不在 PATH 中，请先运行 source <install-prefix>/share/rocprofiler-systems/setup-env.sh。

发现命令参考

用户问题	命令	备注
有哪些设置/环境变量，以及它们的说明？	rocprof-sys-avail -S -bd	-b 会隐藏当前值/可用性列，-d 会添加说明列
我的系统上有哪些硬件计数器可用？	rocprof-sys-avail -H -bd -A	-A/--available 将结果限制为此机器实际可用的计数器；添加 -c CPU 或 -c GPU 可按设备分类
可以跟踪哪些 ROCm API？	rocprof-sys-avail -bd -r ROCM_DOMAINS	使用正则表达式筛选设置，仅显示 ROCPROFSYS_ROCM_DOMAINS 行，其中列出所有有效域（hip_runtime_api、hsa_api、kernel_dispatch、rccl_api、kfd_events 等）
一个 ROCm 域中有哪些操作/API 调用？	rocprof-sys-avail --list-domains，然后运行 rocprof-sys-avail --list-operations <domain>	例如，--list-operations hip_runtime_api 会列出各个 HIP 调用。只接受 --list-domains 输出的域：复合域必须展开（hip_api → hip_runtime_api、hip_compiler_api；hsa_api → hsa_core_api、hsa_amd_ext_api、hsa_image_ext_api、hsa_finalize_ext_api；kfd_events → kfd_* 域；roctx → marker_api），而 kernel_dispatch 没有操作列表
可以收集哪些 Timemory 组件？	rocprof-sys-avail -C -bd	添加 -A 可将结果限制为此构建中可用的组件
某个主题（跟踪、采样、输出等）有哪些设置？	先运行 rocprof-sys-avail --list-categories，然后运行 rocprof-sys-avail -S -bd -c settings::<category>	类别名称不一定与普通英语表达相符——例如应使用 settings::trace，而不是 settings::tracing——因此务必先查看 --list-categories
可以采样哪些 GPU 功耗/温度/利用率指标？	rocprof-sys-avail -bd -r AMD_SMI_METRICS	显示 ROCPROFSYS_AMD_SMI_METRICS 的选项（busy, temp, power, mem_usage, ...）
rocprof-sys-run 有哪些主题 X 对应的 CLI 标志？	rocprof-sys-run --help=<topic>	主题：preset, general, tracing, profiling, output, sampling, process, counters, backend, execution, debug, misc, gpu, cpu, rocm, parallel
如何让所选设置在多次运行之间保持生效？	rocprof-sys-avail -G ~/.rocprof-sys.cfg [--all]，然后运行 export ROCPROFSYS_CONFIG_FILE=~/.rocprof-sys.cfg	生成的文件中添加说明/类别需使用 --all；格式可通过 -F 指定为 txt（默认）、json 或 xml

术语

“Trace”和“tracing”在输出中含义有所重叠，因此回答前应先将看到的名称对应到它所控制的内容：

看到的名称	控制内容
ROCPROFSYS_TRACE、settings::trace 和 --help=tracing（其调优选项）	Perfetto trace 输出
ROCPROFSYS_USE_ROCPD	rocPD 输出
ROCPROFSYS_PROFILE、--help=profiling	timemory profile 输出
ROCPROFSYS_USE_SAMPLING、--help=sampling	调用栈采样
ROCPROFSYS_ROCM_DOMAINS、--help=rocm	ROCm API 跟踪
ROCPROFSYS_USE_MPIP、_RCCLP、_OMPT、_KOKKOSP	MPI、RCCL、OpenMP 和 Kokkos API 跟踪

“Tracing”指 API 跟踪（记录某个 API 的调用）；“trace 输出”指 Perfetto 文件。像“有哪些 tracing 选项？”这样的问题，通常指 ROCm 域；如果含义不明确，请先询问，或同时回答两者。

如何回答发现类问题

1. 确定问题涉及哪个维度：设置/环境变量、Timemory 组件、硬件计数器、ROCm API 域、GPU 指标或 CLI 标志。
2. 从上表中选择对应的行。
3. 运行命令（或交给用户运行），并报告相关行——如果问题范围较窄，不要输出整个表；先使用 -r <regex> / -c <category> / -A 缩小范围。
4. 如果结果仍然太宽泛，建议添加 -A/--available（仅显示已安装/受支持的项目），或使用类别/正则表达式筛选。

持久化配置

确定合适的设置后，将其保存到配置文件中，而不是每次运行都重新输入环境变量：

rocprof-sys-avail -G ~/.rocprof-sys.cfg --all   # --all adds descriptions/categories
export ROCPROFSYS_CONFIG_FILE=~/.rocprof-sys.cfg

使用 -F txt|json|xml 选择格式；不同格式的加载方式也不同：

• txt（默认）和 xml：使用 ROCPROFSYS_CONFIG_FILE 加载。
• json：这是分层预设文件，不能通过 ROCPROFSYS_CONFIG_FILE 加载（运行会因“缺少预期的 'rocprofiler-systems' 根对象”而失败）；请使用 rocprof-sys-run --preset=<file>.json -- <app> 加载。

同一设置在多个位置出现时，优先级顺序为：配置文件、环境变量，然后是命令行参数；后者会覆盖前者。例如，若文件中设置了 ROCPROFSYS_SAMPLING_FREQ = 50，环境中的 ROCPROFSYS_SAMPLING_FREQ=77 会覆盖它，而 rocprof-sys-run --sampling-freq=100 -- <app> 会覆盖两者。

使用发现的内容

通过上述命令找到的名称可通过以下设置应用：

• CPU 计数器（-H -c CPU）：设置 ROCPROFSYS_PAPI_EVENTS、ROCPROFSYS_PROFILE=ON 并且将 papi_array（或 papi_vector）添加到 ROCPROFSYS_TIMEMORY_COMPONENTS，例如 wall_clock,papi_array；结果会写入 papi_array*.txt/json（或 papi_vector*）。如果未添加该组件，运行会成功，但不会写入计数器文件。所有 事件必须来自同一个命名空间——混用 PAPI_* 预设和 perf::* 事件只会打印“Failure to add named event”警告并丢弃计数器，但运行仍会以 0 退出。
  • 通过 Linux perf_event 读取主机 CPU 计数器时，/proc/sys/kernel/perf_event_paranoid 必须 <= 2。 此限制不适用于从其他来源读取的指标，例如 PAPI net::: 网络事件，它们读取 /proc/net/dev。
• CPU 溢出采样：基于硬件事件采样，而非计时器。 设置 ROCPROFSYS_USE_SAMPLING=ON、ROCPROFSYS_SAMPLING_OVERFLOW=ON、 ROCPROFSYS_SAMPLING_OVERFLOW_EVENT=<event>（使用 rocprof-sys-avail -H -c CPU -r overflow 列出事件）并且设置较大的 ROCPROFSYS_SAMPLING_OVERFLOW_FREQ（每次采样的事件数，例如 10000000）。 仅设置事件不起作用（会回退到 CPU 时间采样），而测试时将间隔保留为默认的 300 个事件会导致运行中止。 此外还要求 perf_event_paranoid <= 2。
• GPU 计数器（-H -c GPU）：按设备列出名称，例如 FETCH_SIZE:device=0。为内核分派计数器设置 ROCPROFSYS_ROCM_EVENTS （会写入 rocprof-device-<N>-<counter>.txt/json），或为轮询式（PMC）采样设置 ROCPROFSYS_GPU_PERF_COUNTERS。不带 :device=N 后缀的名称会在每台设备上采集。
• GPU 指标（功耗、温度、利用率）：通过 AMD SMI 采集。ROCPROFSYS_AMD_SMI_METRICS 用于选择要启用的指标。
  • 默认启用 busy,temp,power,mem_usage。
  • 值 all 会采集所有指标。
  • ROCPROFSYS_USE_AMD_SMI=OFF 会完全禁用此后端。
• ROCm API 跟踪：将 ROCPROFSYS_ROCM_DOMAINS 设置为以逗号分隔的列表， 例如 hip_runtime_api,kernel_dispatch,memory_copy。
  • 从 rocprof-sys-avail -bd -r ROCM_DOMAINS 中准确复制名称：只要有一个未知 名称，就会导致失败。
  • kfd_events 还需要 HSA_XNACK=1 和支持 XNACK 的 GPU；使用 rocminfo | grep -i xnack 检查（GPU 目标名称带有 xnack-/xnack+ 后缀表示 支持）。在不支持 XNACK 的 GPU 上，它不会记录任何内容，也不会打印任何内容。

常见错误

错误	修正方法
为 -c 猜测类别名称（例如 settings::tracing）	先运行 rocprof-sys-avail --list-categories——类别名称不一定与直观的英文单词相符（这里应为 settings::trace）
针对范围较窄的问题输出完整的 -S/-C/-H 表格	结合 -r <regex> 或 -c <category>/-A 进行筛选后再报告
将此技能与选择分析预设混淆	预设选择对应 choosing-a-profiling-preset；此技能用于探索和微调单个选项，包括在已选预设的基础上进行调整
凭记忆输入 ROCm 域名称	未知的 ROCPROFSYS_ROCM_DOMAINS 名称会静默禁用整个列表；请从 rocprof-sys-avail -bd -r ROCM_DOMAINS 中复制名称
忘记 -A/--available	不使用该选项时，-H/-C 会列出当前构建或硬件实际不支持的计数器/组件，可能导致回答内容过多

rocprof-sys-avail 是名称和说明的权威来源。有关选项发现以外的主题（统一内存分析、因果分析），请参阅 在线文档： https://rocm.docs.amd.com/projects/rocprofiler-systems/en/develop/how-to/configuring-runtime-options.html