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 で確認してください。1 行目は 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
プロファイル出力	timemory プロファイルファイル（フラット形式またはコールスタック形式）を書き出します	ROCPROFSYS_PROFILE
コールスタックサンプリング	CPU のコールスタックを一定の頻度でサンプリングします	ROCPROFSYS_USE_SAMPLING
API トレーシング	1 つの API の呼び出しをインターセプトして記録します	下記を参照

API トレーシングは API ごとに選択します。ROCm（ROCPROFSYS_ROCM_DOMAINS）、MPI（ROCPROFSYS_USE_MPIP）、RCCL（ROCPROFSYS_USE_RCCLP）、OpenMP（ROCPROFSYS_USE_OMPT）、Kokkos（ROCPROFSYS_USE_KOKKOSP）が対象です。すべての組み込みプリセットでは、デフォルトで HIP ランタイム API、ROCTx マーカー、カーネルディスパッチ、メモリーコピー、スクラッチメモリーを対象とする ROCm API トレーシングが有効です。プリセットによって対象を絞ったり広げたりでき、--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	CPU カウンター（PAPI）を含む、計算負荷の高い MPI/OpenMP/Kokkos/RCCL アプリ
trace-openmp	HPC	OpenMP の GPU ターゲットオフロードアプリ
profile-mpi	HPC	MPI 通信レイテンシー、フラットプロファイル、Perfetto トレースなし
sys-trace	トレーシング	ランタイムレイヤー間のやり取りのデバッグ、最も広範な ROCm API トレーシング（HIP、HSA、ROCTx、RCCL）
runtime-trace	トレーシング	HSA/コンパイラー API を除く sys-trace と同じ

選び方

次の質問に順番に答え、1つのプリセットに絞り込めた最初の項目を選びます。項目に当てはまる前に、MPI などのランタイム名をユーザーに指定させる必要はありません。

1. API のトレースまたはデバッグ。 HIP、HSA、またはランタイム層の動作に関する質問（例：「HIP 呼び出しの動作がおかしいのはなぜか」「内部で HSA は何をしているのか」）→ sys-trace（ROCm API 全体のトレース）、または HSA とコンパイラー API のノイズを除外する場合は runtime-trace。

2. 特定の測定項目が1つ。

   • 占有率や VALU 使用率など、GPU ハードウェアカウンター → trace-hw-counters。
   • MPI 通信レイテンシだけが対象で、Perfetto トレースファイルが不要 → profile-mpi。
   • OpenMP の GPU ターゲットオフロードカーネル → trace-openmp。

3. 長時間実行される GPU ワークロード。 AI/ML トレーニング、または MPI と RCCL API のトレースが必要な、長時間実行される GPU アクセラレーテッド HPC ジョブで、大容量の Perfetto トレースバッファーが必要な場合 → 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. command -v による確認や && チェーンを前に付けず、rocprof-sys-run --explain=<name>（または rocprof-sys-sample --explain=<name>）を単独のコマンドとして実行します。プリセットの事実として、その 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

推奨するプリセットで何が有効になり、何が無効になるかを、上記の用語を使って1行で説明し、得られるものと失うものがユーザーに伝わるようにします。たとえば、profile-only はフラットプロファイルを書き出しますが、Perfetto トレースファイル、rocPD データベース、コールスタックのサンプリングは含まれません。一方、ROCm API 呼び出しとカーネルは引き続きプロファイルに表示されます。

必要に応じて、次の点にも触れます：

• ドメインフラグ（--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 スキーマに従います。

よくある間違い

間違い	修正
rocprofiler-systems をビルドするための CMake の --preset debug|release|ci と混同する	ビルド用プリセットはコンパイルを設定し、プロファイリング用プリセットはプロファイリングの実行を設定します。このスキルで扱うのは後者だけです。
編集するために、組み込みプリセットの JSON ファイルを探す	組み込みプリセットはバイナリにコンパイルされており、ファイルとしてはインストールされません。--explain=<name> で内容を確認し、--export-config で編集可能なコピーを作成します。
「とにかくデータが欲しい」という場合に、デフォルトで detailed を選ぶ	ユーザーが明示的に最大限の詳細を求め、オーバーヘッドの増加を許容できる場合を除き、balanced をデフォルトにします。