rocprofiler-systems-discovering-profiling-options

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Discovering Profiling Options

发现性能分析选项

Maps a "what's available" or "how do I configure X" question to the exact
rocprof-sys-avail
/
rocprof-sys-run --help=<topic>
command that answers it.
rocprof-sys-avail
is self-updating and authoritative — prefer running it over reciting static documentation.
将“有哪些可用项”或“如何配置 X”类问题映射到能够给出答案的确切
rocprof-sys-avail
/
rocprof-sys-run --help=<topic>
命令。
rocprof-sys-avail
会自我更新,并且是权威信息源——应优先运行该命令, 而不是复述静态文档。

Prerequisites

前置条件

A working
rocprof-sys-avail
binary, built/installed alongside
rocprof-sys-run
/
rocprof-sys-sample
. If it is not on
PATH
, run
source <install-prefix>/share/rocprofiler-systems/setup-env.sh
first.
需要提供可正常工作的
rocprof-sys-avail
二进制文件,它应与
rocprof-sys-run
/
rocprof-sys-sample
一同构建或安装。如果它不在
PATH
中,请先运行
source <install-prefix>/share/rocprofiler-systems/setup-env.sh
。

Discovery command reference

发现命令参考

User questionCommandNotes
What settings/env vars exist, with descriptions?
rocprof-sys-avail -S -bd
-b
suppresses the current-value/availability column,
-d
adds the description column
What hardware counters are available on my system?
rocprof-sys-avail -H -bd -A
-A
/
--available
restricts to counters this machine can actually use; add
-c CPU
or
-c GPU
to split by device
What ROCm APIs can be traced?
rocprof-sys-avail -bd -r ROCM_DOMAINS
Regex-filters settings to the
ROCPROFSYS_ROCM_DOMAINS
row, listing every valid domain (
hip_runtime_api
,
hsa_api
,
kernel_dispatch
,
rccl_api
,
kfd_events
, ...)
What operations/API calls exist within one ROCm domain?
rocprof-sys-avail --list-domains
then
rocprof-sys-avail --list-operations <domain>
e.g.
--list-operations hip_runtime_api
lists individual HIP calls. Only domains printed by
--list-domains
are accepted: composites must be expanded (
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
→ the
kfd_*
domains;
roctx
→
marker_api
), and
kernel_dispatch
has no operation list
What Timemory components can I collect?
rocprof-sys-avail -C -bd
add
-A
to restrict to components usable on this build
What settings exist for one topic (tracing, sampling, output, ...)?
rocprof-sys-avail --list-categories
then
rocprof-sys-avail -S -bd -c settings::<category>
category names don't always match plain English — it's
settings::trace
, not
settings::tracing
— so always check
--list-categories
first
What GPU power/temp/utilization metrics can I sample?
rocprof-sys-avail -bd -r AMD_SMI_METRICS
surfaces
ROCPROFSYS_AMD_SMI_METRICS
choices (
busy, temp, power, mem_usage, ...
)
What CLI flags does
rocprof-sys-run
have for topic X?
rocprof-sys-run --help=<topic>
topics:
preset, general, tracing, profiling, output, sampling, process, counters, backend, execution, debug, misc, gpu, cpu, rocm, parallel
How do I persist chosen settings across runs?
rocprof-sys-avail -G ~/.rocprof-sys.cfg [--all]
then
export ROCPROFSYS_CONFIG_FILE=~/.rocprof-sys.cfg
--all
includes descriptions/categories in the generated file; formats are txt (default), json, xml via
-F
用户问题命令备注
存在哪些设置/环境变量及其说明?
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
行,并列出所有有效 domain(
hip_runtime_api
、
hsa_api
、
kernel_dispatch
、
rccl_api
、
kfd_events
等)
某个 ROCm domain 内有哪些 operation/API call?
rocprof-sys-avail --list-domains
,然后运行
rocprof-sys-avail --list-operations <domain>
例如,
--list-operations hip_runtime_api
会列出各个 HIP call。仅接受
--list-domains
输出的 domain:composite domain 必须展开(
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_*
domain;
roctx
→
marker_api
),并且
kernel_dispatch
没有 operation list
可以采集哪些 Timemory 组件?
rocprof-sys-avail -C -bd
添加
-A
可将结果限制为当前 build 可用的组件
某个主题(tracing、sampling、output 等)有哪些设置?
rocprof-sys-avail --list-categories
,然后运行
rocprof-sys-avail -S -bd -c settings::<category>
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 flags?
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
生成的配置文件中会包含说明/category;可通过
-F
选择 txt(默认)、json、xml 格式

Terminology

术语

"Trace" and "tracing" overlap in the output, so map the name you see to what it controls before answering:
Name you seeWhat it controls
ROCPROFSYS_TRACE
,
settings::trace
and
--help=tracing
(its tuning options)
Perfetto trace output
ROCPROFSYS_USE_ROCPD
rocPD output
ROCPROFSYS_PROFILE
,
--help=profiling
timemory profile output
ROCPROFSYS_USE_SAMPLING
,
--help=sampling
call-stack sampling
ROCPROFSYS_ROCM_DOMAINS
,
--help=rocm
ROCm API tracing
ROCPROFSYS_USE_MPIP
,
_RCCLP
,
_OMPT
,
_KOKKOSP
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”在输出中存在重叠,因此回答前应先将看到的名称映射到它所控制的内容:
看到的名称控制内容
ROCPROFSYS_TRACE
、
settings::trace
和
--help=tracing
(及其调优选项)
Perfetto trace 输出
ROCPROFSYS_USE_ROCPD
rocPD 输出
ROCPROFSYS_PROFILE
、
--help=profiling
timemory profile 输出
ROCPROFSYS_USE_SAMPLING
、
--help=sampling
call-stack sampling
ROCPROFSYS_ROCM_DOMAINS
、
--help=rocm
ROCm API tracing
ROCPROFSYS_USE_MPIP
、
_RCCLP
、
_OMPT
、
_KOKKOSP
MPI、RCCL、OpenMP 和 Kokkos API tracing
“Tracing”表示 API tracing(记录某一 API 的调用);“trace output”指 Perfetto 文件。 “有哪些 tracing 选项?”之类的问题通常指 ROCm domains,因此如果不明确,应同时询问或回答两者。

How to answer a discovery question

如何回答发现类问题

  1. Identify which axis the question is about: settings/env-vars, Timemory components, hardware counters, ROCm API domains, GPU metrics, or CLI flags.
  2. Pick the matching row from the table above.
  3. 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>
    /
    -A
    to narrow first.
  4. If the result is still broad, suggest adding
    -A
    /
    --available
    (installed/ supported only) or a category/regex filter.
  1. 确定问题涉及哪个维度:设置/环境变量、Timemory 组件、硬件计数器、ROCm API domains、GPU 指标或 CLI flags。
  2. 从上表中选择对应的条目。
  3. 运行该命令(或将命令交给用户运行)并报告相关行—— 如果问题范围较窄,不要输出整张表;可先结合
    -r <regex>
    /
    -c <category>
    /
    -A
    缩小范围。
  4. 如果结果仍然过于宽泛,建议添加
    -A
    /
    --available
    (仅显示已安装/支持的项), 或使用 category/regex 进一步过滤。

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.cfg
Select the format with
-F txt|json|xml
; they load differently:
  • txt
    (default) and
    xml
    : load with
    ROCPROFSYS_CONFIG_FILE
    .
  • json
    : this is a hierarchical preset file. It does not load through
    ROCPROFSYS_CONFIG_FILE
    (the run fails with "missing the expected 'rocprofiler-systems' root object"); load it with
    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
ROCPROFSYS_SAMPLING_FREQ = 50
in the file,
ROCPROFSYS_SAMPLING_FREQ=77
in the environment beats it, and
rocprof-sys-run --sampling-freq=100 -- <app>
beats both.
确定正确的设置后,将它们固化到配置文件中,而不是每次运行都重新输入环境变量:
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
    加载。
  • json
    :这是一个分层 preset 文件。它不会通过
    ROCPROFSYS_CONFIG_FILE
    加载(运行会因“missing the expected 'rocprofiler-systems' root object”而失败);应使用
    rocprof-sys-run --preset=<file>.json -- <app>
    加载。
当同一项设置出现在多个位置时,优先级顺序为: 配置文件、环境变量、命令行参数,后面的依次覆盖前面的。例如,当文件中包含
ROCPROFSYS_SAMPLING_FREQ = 50
时,环境变量中的
ROCPROFSYS_SAMPLING_FREQ=77
会覆盖它,而
rocprof-sys-run --sampling-freq=100 -- <app>
又会覆盖前两者。

Using what you discover

应用发现的选项

Names found with the commands above are applied through these settings:
  • CPU counters (
    -H -c CPU
    ): set
    ROCPROFSYS_PAPI_EVENTS
    ,
    ROCPROFSYS_PROFILE=ON
    and add
    papi_array
    (or
    papi_vector
    ) to
    ROCPROFSYS_TIMEMORY_COMPONENTS
    , e.g.
    wall_clock,papi_array
    ; results are written to
    papi_array*.txt/json
    (or
    papi_vector*
    ). Without the component the run succeeds but writes no counter files. All events must come from one namespace — mixing
    PAPI_*
    presets with
    perf::*
    events only prints a "Failure to add named event" warning and drops the counters, the run still exits 0.
    • Host CPU counters read through Linux
      perf_event
      need
      /proc/sys/kernel/perf_event_paranoid
      <= 2. That limit does not apply to metrics read from other sources, such as the PAPI
      net:::
      network events, which read
      /proc/net/dev
      .
  • CPU overflow sampling: sample on a hardware event instead of a timer. Set
    ROCPROFSYS_USE_SAMPLING=ON
    ,
    ROCPROFSYS_SAMPLING_OVERFLOW=ON
    ,
    ROCPROFSYS_SAMPLING_OVERFLOW_EVENT=<event>
    (list events with
    rocprof-sys-avail -H -c CPU -r overflow
    ) and a large
    ROCPROFSYS_SAMPLING_OVERFLOW_FREQ
    (events per sample, e.g.
    10000000
    ). 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 needs
    perf_event_paranoid
    <= 2.
  • GPU counters (
    -H -c GPU
    ): names are listed per device, e.g.
    FETCH_SIZE:device=0
    . Set
    ROCPROFSYS_ROCM_EVENTS
    for kernel-dispatch counters (writes
    rocprof-device-<N>-<counter>.txt/json
    ), or
    ROCPROFSYS_GPU_PERF_COUNTERS
    for polled (PMC) sampling. A name without the
    :device=N
    suffix is collected on every device.
  • GPU metrics (power, temperature, utilization): collected via AMD SMI.
    ROCPROFSYS_AMD_SMI_METRICS
    selects which metrics to enable.
    • By default,
      busy,temp,power,mem_usage
      are enabled.
    • The value
      all
      collects everything.
    • ROCPROFSYS_USE_AMD_SMI=OFF
      disables this backend entirely.
  • ROCm API tracing: set
    ROCPROFSYS_ROCM_DOMAINS
    to a comma-separated list, e.g.
    hip_runtime_api,kernel_dispatch,memory_copy
    .
    • Copy names exactly from
      rocprof-sys-avail -bd -r ROCM_DOMAINS
      : one unknown name will fail produce a failure
    • kfd_events
      also needs
      HSA_XNACK=1
      and an XNACK-capable GPU; check with
      rocminfo | grep -i xnack
      (a
      xnack-
      /
      xnack+
      suffix on the GPU target means capable). On a GPU without XNACK it records nothing and prints nothing.
通过上述命令发现的名称可使用以下设置来应用:
  • 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*
    )。如果缺少该组件,运行会成功,但不会写入任何 counter 文件。所有 events 必须来自同一个 namespace——混用
    PAPI_*
    presets 与
    perf::*
    events 只会打印“Failure to add named event”警告并丢弃 counters,而运行仍会以 0 退出。
    • 通过 Linux
      perf_event
      读取的 Host CPU counters 要求
      /proc/sys/kernel/perf_event_paranoid
      <= 2。 该限制不适用于从其他来源读取的 metrics,例如 PAPI
      net:::
      network events,后者读取
      /proc/net/dev
      。
  • CPU overflow sampling:在 hardware event 而非 timer 上进行采样。 设置
    ROCPROFSYS_USE_SAMPLING=ON
    、
    ROCPROFSYS_SAMPLING_OVERFLOW=ON
    、
    ROCPROFSYS_SAMPLING_OVERFLOW_EVENT=<event>
    (使用
    rocprof-sys-avail -H -c CPU -r overflow
    列出 events),并且设置较大的
    ROCPROFSYS_SAMPLING_OVERFLOW_FREQ
    (每次 sample 的 event 数,例如
    10000000
    )。 仅设置 event 不起作用(会回退到 CPU-time sampling),而测试中如果将 interval 保留为默认的 300 events,会导致运行中止。 还需要满足
    perf_event_paranoid
    <= 2。
  • GPU 计数器(
    -H -c GPU
    ):名称按 device 列出,例如
    FETCH_SIZE:device=0
    。为 kernel-dispatch counters 设置
    ROCPROFSYS_ROCM_EVENTS
    (写入
    rocprof-device-<N>-<counter>.txt/json
    ),或为轮询式(PMC)sampling 设置
    ROCPROFSYS_GPU_PERF_COUNTERS
    。不带
    :device=N
    后缀的名称将在每个 device 上采集。
  • GPU 指标(功耗、温度、利用率):通过 AMD SMI 采集。
    ROCPROFSYS_AMD_SMI_METRICS
    用于选择要启用的指标。
    • 默认启用
      busy,temp,power,mem_usage
      。
    • 值
      all
      表示采集全部指标。
    • ROCPROFSYS_USE_AMD_SMI=OFF
      会完全禁用此 backend。
  • ROCm API tracing:将
    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 target 上带有
      xnack-
      /
      xnack+
      后缀表示支持)。 在不支持 XNACK 的 GPU 上,它不会记录或打印任何内容。

Common Mistakes

常见错误

MistakeFix
Guessing a category name for
-c
(e.g.
settings::tracing
)
Run
rocprof-sys-avail --list-categories
first — category names don't always match the obvious English word (it's
settings::trace
)
Dumping the full
-S
/
-C
/
-H
table for a narrow question
Combine with
-r <regex>
or
-c <category>
/
-A
to filter before reporting
Confusing this skill with picking a profiling presetPreset selection is
choosing-a-profiling-preset
; this skill is for exploring/fine-tuning individual options, including on top of a chosen preset
Typing a ROCm domain name from memoryAn unknown
ROCPROFSYS_ROCM_DOMAINS
name silently disables the whole list; copy names from
rocprof-sys-avail -bd -r ROCM_DOMAINS
Forgetting
-A
/
--available
Without it,
-H
/
-C
list counters/components the current build or hardware doesn't actually support, which can overwhelm the answer
rocprof-sys-avail
is the source of truth for names and descriptions. For topics beyond option discovery (unified memory profiling, causal profiling), see the online docs: https://rocm.docs.amd.com/projects/rocprofiler-systems/en/develop/how-to/configuring-runtime-options.html
错误修复方法
猜测
-c
的 category 名称(例如
settings::tracing
)
先运行
rocprof-sys-avail --list-categories
——category 名称不一定与显而易见的英文单词一致(实际是
settings::trace
)
针对范围较窄的问题输出完整的
-S
/
-C
/
-H
表格
先结合
-r <regex>
或
-c <category>
/
-A
进行过滤,然后再报告结果
将本 skill 与选择 profiling preset 混淆Preset 选择应使用
choosing-a-profiling-preset
;本 skill 用于探索/微调单个选项,包括在已选 preset 的基础上进一步调整
凭记忆输入 ROCm domain 名称未知的
ROCPROFSYS_ROCM_DOMAINS
名称会悄悄禁用整个列表;请从
rocprof-sys-avail -bd -r ROCM_DOMAINS
复制名称
忘记
-A
/
--available
否则,
-H
/
-C
会列出当前 build 或 hardware 实际不支持的 counters/components,可能使回答过于庞杂
rocprof-sys-avail
是名称与说明的 source of truth。对于选项发现之外的主题 (unified memory profiling、causal profiling),请参阅在线文档: https://rocm.docs.amd.com/projects/rocprofiler-systems/en/develop/how-to/configuring-runtime-options.html