rocprofiler-systems-discovering-profiling-options

プロファイリングの設定項目を調べる

「何が利用できますか」や「X をどう設定しますか」という質問に対し、回答となる正確な rocprof-sys-avail／rocprof-sys-run --help=<topic> コマンドを案内します。 rocprof-sys-avail は自動的に更新される信頼できる情報源です。静的なドキュメントの内容を 答えるより、実行することを優先してください。

前提条件

rocprof-sys-run／rocprof-sys-sample とともにビルドまたはインストールされた、 動作する rocprof-sys-avail バイナリが必要です。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 など）をすべて表示します
1 つの 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::tracing ではなく settings::trace です。そのため、必ず先に --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 トレース出力
ROCPROFSYS_USE_ROCPD	rocPD 出力
ROCPROFSYS_PROFILE、--help=profiling	timemory プロファイル出力
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 トレーシング（1 つの API の呼び出しを記録すること）を意味し、「trace output」は Perfetto ファイルを意味します。「どのようなトレーシングオプションがありますか？」という質問は、通常 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 からは読み込めません（実行すると「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> はその両方を上書きします。

検出した内容の使用

上記のコマンドで見つかった名前は、次の設定で適用します。

• 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 以下である必要があります。 この制限は、/proc/net/devを読み取る PAPI のnet:::ネットワークイベントなど、ほかのソースから読み取るメトリクスには適用されません。
• 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