rocprofiler-systems-discovering-profiling-options
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDiscovering Profiling Options
发现性能分析选项
Maps a "what's available" or "how do I configure X" question to the exact
/ command that answers it.
is self-updating and authoritative — prefer running it over
reciting static documentation.
rocprof-sys-availrocprof-sys-run --help=<topic>rocprof-sys-avail将“有哪些可用项”或“如何配置 X”类问题映射到能够给出答案的确切
/ 命令。
会自我更新,并且是权威信息源——应优先运行该命令,
而不是复述静态文档。
rocprof-sys-availrocprof-sys-run --help=<topic>rocprof-sys-availPrerequisites
前置条件
A working binary, built/installed alongside
/. If it is not on , run
first.
rocprof-sys-availrocprof-sys-runrocprof-sys-samplePATHsource <install-prefix>/share/rocprofiler-systems/setup-env.sh需要提供可正常工作的 二进制文件,它应与
/ 一同构建或安装。如果它不在 中,请先运行
。
rocprof-sys-availrocprof-sys-runrocprof-sys-samplePATHsource <install-prefix>/share/rocprofiler-systems/setup-env.shDiscovery command reference
发现命令参考
| User question | Command | Notes |
|---|---|---|
| What settings/env vars exist, with descriptions? | | |
| What hardware counters are available on my system? | | |
| What ROCm APIs can be traced? | | Regex-filters settings to the |
| What operations/API calls exist within one ROCm domain? | | e.g. |
| What Timemory components can I collect? | | add |
| What settings exist for one topic (tracing, sampling, output, ...)? | | category names don't always match plain English — it's |
| What GPU power/temp/utilization metrics can I sample? | | surfaces |
What CLI flags does | | topics: |
| How do I persist chosen settings across runs? | | |
| 用户问题 | 命令 | 备注 |
|---|---|---|
| 存在哪些设置/环境变量及其说明? | | |
| 系统上有哪些可用的硬件计数器? | | |
| 可以跟踪哪些 ROCm API? | | 使用正则表达式将设置过滤到 |
| 某个 ROCm domain 内有哪些 operation/API call? | | 例如, |
| 可以采集哪些 Timemory 组件? | | 添加 |
| 某个主题(tracing、sampling、output 等)有哪些设置? | | category 名称不一定与普通英语一致——它是 |
| 可以采样哪些 GPU 功耗/温度/利用率指标? | | 显示 |
| | 主题包括: |
| 如何跨多次运行持久化已选设置? | | 生成的配置文件中会包含说明/category;可通过 |
Terminology
术语
"Trace" and "tracing" overlap in the output, so map the name you see to what it
controls before answering:
| Name you see | What it controls |
|---|---|
| Perfetto trace output |
| rocPD output |
| timemory profile output |
| call-stack sampling |
| ROCm API tracing |
| MPI, RCCL, OpenMP and Kokkos API tracing |
"Tracing" means API tracing (recording the calls of one API); "trace output" means the
Perfetto file. A question like "what tracing options are there?" usually means the ROCm
domains, so ask or answer both if it is unclear.
“Trace”和“tracing”在输出中存在重叠,因此回答前应先将看到的名称映射到它所控制的内容:
| 看到的名称 | 控制内容 |
|---|---|
| Perfetto trace 输出 |
| rocPD 输出 |
| timemory profile 输出 |
| call-stack sampling |
| ROCm API tracing |
| MPI、RCCL、OpenMP 和 Kokkos API tracing |
“Tracing”表示 API tracing(记录某一 API 的调用);“trace output”指 Perfetto 文件。
“有哪些 tracing 选项?”之类的问题通常指 ROCm domains,因此如果不明确,应同时询问或回答两者。
How to answer a discovery question
如何回答发现类问题
- Identify which axis the question is about: settings/env-vars, Timemory components, hardware counters, ROCm API domains, GPU metrics, or CLI flags.
- Pick the matching row from the table above.
- Run the command (or hand it to the user) and report the relevant rows —
don't dump the entire table if the question was narrow; combine with
/
-r <regex>/-c <category>to narrow first.-A - If the result is still broad, suggest adding /
-A(installed/ supported only) or a category/regex filter.--available
- 确定问题涉及哪个维度:设置/环境变量、Timemory 组件、硬件计数器、ROCm API domains、GPU 指标或 CLI flags。
- 从上表中选择对应的条目。
- 运行该命令(或将命令交给用户运行)并报告相关行——
如果问题范围较窄,不要输出整张表;可先结合
/
-r <regex>/-c <category>缩小范围。-A - 如果结果仍然过于宽泛,建议添加 /
-A(仅显示已安装/支持的项), 或使用 category/regex 进一步过滤。--available
Persisting configuration
持久化配置
Once the right settings are identified, freeze them into a config file instead
of re-typing environment variables every run:
bash
rocprof-sys-avail -G ~/.rocprof-sys.cfg --all # --all adds descriptions/categories
export ROCPROFSYS_CONFIG_FILE=~/.rocprof-sys.cfgSelect the format with ; they load differently:
-F txt|json|xml- (default) and
txt: load withxml.ROCPROFSYS_CONFIG_FILE - : this is a hierarchical preset file. It does not load through
json(the run fails with "missing the expected 'rocprofiler-systems' root object"); load it withROCPROFSYS_CONFIG_FILE.rocprof-sys-run --preset=<file>.json -- <app>
When the same setting is given in more than one place, the order of priority is:
config file, then environment variable, then command-line parameter, each overriding
the one before. For example, with in the file,
in the environment beats it, and
beats both.
ROCPROFSYS_SAMPLING_FREQ = 50ROCPROFSYS_SAMPLING_FREQ=77rocprof-sys-run --sampling-freq=100 -- <app>确定正确的设置后,将它们固化到配置文件中,而不是每次运行都重新输入环境变量:
bash
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 - :这是一个分层 preset 文件。它不会通过
json加载(运行会因“missing the expected 'rocprofiler-systems' root object”而失败);应使用ROCPROFSYS_CONFIG_FILE加载。rocprof-sys-run --preset=<file>.json -- <app>
当同一项设置出现在多个位置时,优先级顺序为:
配置文件、环境变量、命令行参数,后面的依次覆盖前面的。例如,当文件中包含
时,环境变量中的 会覆盖它,而
又会覆盖前两者。
ROCPROFSYS_SAMPLING_FREQ = 50ROCPROFSYS_SAMPLING_FREQ=77rocprof-sys-run --sampling-freq=100 -- <app>Using what you discover
应用发现的选项
Names found with the commands above are applied through these settings:
- CPU counters (): set
-H -c CPU,ROCPROFSYS_PAPI_EVENTSand addROCPROFSYS_PROFILE=ON(orpapi_array) topapi_vector, e.g.ROCPROFSYS_TIMEMORY_COMPONENTS; results are written towall_clock,papi_array(orpapi_array*.txt/json). Without the component the run succeeds but writes no counter files. All events must come from one namespace — mixingpapi_vector*presets withPAPI_*events only prints a "Failure to add named event" warning and drops the counters, the run still exits 0.perf::*- Host CPU counters read through Linux need
perf_event<= 2. That limit does not apply to metrics read from other sources, such as the PAPI/proc/sys/kernel/perf_event_paranoidnetwork events, which readnet:::./proc/net/dev
- Host CPU counters read through Linux
- CPU overflow sampling: sample on a hardware event instead of a timer.
Set ,
ROCPROFSYS_USE_SAMPLING=ON,ROCPROFSYS_SAMPLING_OVERFLOW=ON(list events withROCPROFSYS_SAMPLING_OVERFLOW_EVENT=<event>) and a largerocprof-sys-avail -H -c CPU -r overflow(events per sample, e.g.ROCPROFSYS_SAMPLING_OVERFLOW_FREQ). Setting only the event does nothing (it falls back to CPU-time sampling), and leaving the interval at its default of 300 events aborted the run when tested. It also needs10000000<= 2.perf_event_paranoid - GPU counters (): names are listed per device, e.g.
-H -c GPU. SetFETCH_SIZE:device=0for kernel-dispatch counters (writesROCPROFSYS_ROCM_EVENTS), orrocprof-device-<N>-<counter>.txt/jsonfor polled (PMC) sampling. A name without theROCPROFSYS_GPU_PERF_COUNTERSsuffix is collected on every device.:device=N - GPU metrics (power, temperature, utilization): collected via
AMD SMI. selects which metrics to enable.
ROCPROFSYS_AMD_SMI_METRICS- By default, are enabled.
busy,temp,power,mem_usage - The value collects everything.
all - disables this backend entirely.
ROCPROFSYS_USE_AMD_SMI=OFF
- By default,
- ROCm API tracing: set to a comma-separated list, e.g.
ROCPROFSYS_ROCM_DOMAINS.hip_runtime_api,kernel_dispatch,memory_copy- Copy names exactly from : one unknown name will fail produce a failure
rocprof-sys-avail -bd -r ROCM_DOMAINS - also needs
kfd_eventsand an XNACK-capable GPU; check withHSA_XNACK=1(arocminfo | grep -i xnack/xnack-suffix on the GPU target means capable). On a GPU without XNACK it records nothing and prints nothing.xnack+
- Copy names exactly from
通过上述命令发现的名称可使用以下设置来应用:
- 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)。如果缺少该组件,运行会成功,但不会写入任何 counter 文件。所有 events 必须来自同一个 namespace——混用papi_vector*presets 与PAPI_*events 只会打印“Failure to add named event”警告并丢弃 counters,而运行仍会以 0 退出。perf::*- 通过 Linux 读取的 Host CPU counters 要求
perf_event<= 2。 该限制不适用于从其他来源读取的 metrics,例如 PAPI/proc/sys/kernel/perf_event_paranoidnetwork events,后者读取net:::。/proc/net/dev
- 通过 Linux
- CPU overflow sampling:在 hardware event 而非 timer 上进行采样。
设置 、
ROCPROFSYS_USE_SAMPLING=ON、ROCPROFSYS_SAMPLING_OVERFLOW=ON(使用ROCPROFSYS_SAMPLING_OVERFLOW_EVENT=<event>列出 events),并且设置较大的rocprof-sys-avail -H -c CPU -r overflow(每次 sample 的 event 数,例如ROCPROFSYS_SAMPLING_OVERFLOW_FREQ)。 仅设置 event 不起作用(会回退到 CPU-time sampling),而测试中如果将 interval 保留为默认的 300 events,会导致运行中止。 还需要满足10000000<= 2。perf_event_paranoid - GPU 计数器():名称按 device 列出,例如
-H -c GPU。为 kernel-dispatch counters 设置FETCH_SIZE:device=0(写入ROCPROFSYS_ROCM_EVENTS),或为轮询式(PMC)sampling 设置rocprof-device-<N>-<counter>.txt/json。不带ROCPROFSYS_GPU_PERF_COUNTERS后缀的名称将在每个 device 上采集。:device=N - GPU 指标(功耗、温度、利用率):通过 AMD SMI 采集。
用于选择要启用的指标。
ROCPROFSYS_AMD_SMI_METRICS- 默认启用 。
busy,temp,power,mem_usage - 值 表示采集全部指标。
all - 会完全禁用此 backend。
ROCPROFSYS_USE_AMD_SMI=OFF
- 默认启用
- ROCm API tracing:将 设置为逗号分隔的列表, 例如
ROCPROFSYS_ROCM_DOMAINS。hip_runtime_api,kernel_dispatch,memory_copy- 从 中准确复制名称:出现任何未知名称都会导致失败。
rocprof-sys-avail -bd -r ROCM_DOMAINS - 还需要
kfd_events和支持 XNACK 的 GPU;可通过HSA_XNACK=1检查(GPU target 上带有rocminfo | grep -i xnack/xnack-后缀表示支持)。 在不支持 XNACK 的 GPU 上,它不会记录或打印任何内容。xnack+
- 从
Common Mistakes
常见错误
| Mistake | Fix |
|---|---|
Guessing a category name for | Run |
Dumping the full | Combine with |
| Confusing this skill with picking a profiling preset | Preset selection is |
| Typing a ROCm domain name from memory | An unknown |
Forgetting | Without it, |
rocprof-sys-avail| 错误 | 修复方法 |
|---|---|
猜测 | 先运行 |
针对范围较窄的问题输出完整的 | 先结合 |
| 将本 skill 与选择 profiling preset 混淆 | Preset 选择应使用 |
| 凭记忆输入 ROCm domain 名称 | 未知的 |
忘记 | 否则, |
rocprof-sys-avail