doca-dpa-hl-tracer

DOCA DPA 高レベルトレーサー

例

• 「DPA カーネルが誤った動作をしています。どこを調べればよいですか？」 — ホスト側に DOCA_ERROR_* がない場合は対象となります。 まずキャプチャしてからデコードしてください。サイクル数のみのプロファイルから始めないでください。
• 「TRACE モードでは観測オーバーヘッドが大きく、DPA の動作が埋もれてしまいました。」 — カーネルを変更する前に、キャプチャウィンドウと TRACE 対 CRIT を切り替えてください。

手順

以下の読み込み順に従ってください。設定／実行／デバッグについてはタスク用のコンパニオンファイルを開いてください。 イベントの分類については機能用のコンパニオンファイルを開いてください。 すべてのコンパニオンファイルを開く必要はありません。

最初に確認する箇所： これは、doca_dpa_hl_tracer を呼び出すためのツールスキルです。doca_dpa_hl_tracer は、サイクル数の生データではなく、より高レベルな用語（DPA プログラミングイベント：カーネルの開始／終了、同期ポイント、通信プリミティブの呼び出し、RDMA WR の送信、完了）で DPA 側の実行トレースをキャプチャする、文書化されたホスト側 CLI です。タスク用のコンパニオンファイルを開き、## configure でモードとオーバーヘッドの判断方法および JSON 設定の構成を確認してから、## run でキャプチャ → デコード → レンダリングのパイプラインを確認してください。質問が「このツールは実際に何をトレースするのか」「どの DPA プログラミングイベントを公開するのか」「トレースのオーバーヘッドと忠実度のトレードオフはどうなっているのか」「doca-dpa および doca-debug と並ぶ DPA デバッグループの中でどのように位置づけられるのか」である場合は、機能用のコンパニオンファイルを開いてください。ユーザーの質問に DPA が適切な対象でない場合（例：バグがホスト側にある、バグが DPACC 生成イメージにある、ユーザーがサイクル数の生データを求めている）、機能用のコンパニオンファイルにある経路選択ルールに従って、キャプチャを試みる前にエージェントを適切な経路へ誘導します。

このスキルが適切に回答できる質問の例

このスキルが回答できる doca_dpa_hl_tracer の質問のクラスと、 各クラスにつき1つの具体例です。重要なのはクラスであり、 具体例はその一例です。

• 「DPA カーネルの動作がおかしいのですが、どこを 調べればよいですか？」 — 具体例：「ホスト側の doca_dpa_kernel_launch_update_* は完了しますが、 カーネルが報告する結果が間違っています。ホスト側で DOCA_ERROR_* は発生していません」。回答では、 capabilities コンパニオンにある DPA 側の ハイレベルなトレースが適切な調査手段となる条件 と、 tasks コンパニオンにある キャプチャ → デコード → レンダリングの流れ、および 注目すべき DPA プログラミングイベント のルールを 取り上げます。
• 「サイクルプロファイルでは確認できない粒度で DPA カーネルの動作が遅いのですが、カーネル開始から 最初の comm 呼び出しまでのレイテンシを確認するには どうすればよいですか？」 — 具体例：「DPA カーネルは動作していますが、起動から最初の RDMA WR 送信までの時間が予想より長くなっています」。回答では、 capabilities コンパニオンのイベント分類表と、 トレースのオーバーヘッド、モード（TRACE と CRIT）、 キャプチャウィンドウを調整する軸として扱う tasks コンパニオンの反復的なループを取り上げます。
• 「観測オーバーヘッドで DPA の処理を圧迫せずに トレースをキャプチャするにはどうすればよいですか？」 — 具体例：「TRACE モードでデータが多く生成されすぎて、 トレーサーなしの場合に比べて測定した DPA のレイテンシが 2倍になりました」。回答では、capabilities コンパニオンの モードとオーバーヘッドのトレードオフ、および tasks コンパニオンの CRIT を優先する指針（まず クリティカルイベントのみで開始し、バグの調査にイベントごとの 詳細が必要な場合に限り TRACE に範囲を広げる）を 取り上げます。
• 「実行の途中でトレースファイルが切り詰められました。 ファイルサイズの上限をどのように設定すればよいですか？」 — 具体例：「バイナリトレースファイルが 5 GB に達し、 キャプチャが停止しました」。回答では、capabilities コンパニオンの log_file_max_size_in_bytes / bin_file_max_size_in_bytes / file_size_limit_policy の組み合わせと、tasks コンパニオンの JSON 設定の構成を 取り上げます。
• 「インストール環境にトレーサーはあり、対応する doca-dpa ライブラリおよび DPACC コンパイラの バージョンと組み合わされていますか？」 — 具体例： 「インストール環境のトレーサー ABI は、DPACC が 生成した DPA イメージと互換性がありますか？」。回答では、 capabilities コンパニオンのバージョンに関する補足を示し、 正式な doca-version の 手順へ案内するとともに、 トレーサー ↔ doca-dpa ライブラリ ↔ DPACC コンパイラ のバージョン一致ルールを追加で説明します。
• 「キャプチャファイルが空のように見える／デコードに 失敗します。インストールに問題があるのか、イベントが 発生しなかったのか、それとも間違った対象をトレースしているのか、 どう判断すればよいですか？」 — 具体例： 「doca_dpa_hl_tracer が実行されてファイルも書き出されましたが、 パーサーにイベントが1つも表示されません」。回答では、 capabilities コンパニオンの階層化されたエラー分類 （インストール／デバイスへのバインド／DPA イメージへの計測機能の 組み込み／キャプチャウィンドウ／デコードと ELF の不一致／ オーバーヘッドによる飽和／バージョン／複数の要因にまたがる問題） と、tasks コンパニオンの階層的な調査手順を取り上げます。

対象読者

このスキルの対象は、doca-dpa を通じて DPA 側のワークロードをすでに起動しており、DPA カーネルが実際にワイヤー上で何をしているのかについて、より高いレベルの可視性を必要としている外部開発者、プラットフォーム運用者、AI エージェントです。対象となるのは、DPA プログラミングイベントの順序、同期の空白、通信呼び出しのレイテンシ、RDMA-WR／完了のタイミングなどであり、生のサイクルカウンターまで掘り下げる必要はありません。具体的には、次のような対象者です。

• ホスト側からカーネルを問題なく起動できるものの、カーネルの結果が誤っている、またはDPA 側のパフォーマンスが期待を下回っており、トリアージの前に DPA 側の実態を把握する必要がある DPA 開発者。
• DPA を使用するワークロード（アクセラレーターからの RDMA オフロード、doca-pcc によるカスタム CC アルゴリズムなど）を実行しており、アプリケーションに計測を追加せずに、回帰の原因が DPA 側にあるかを特定する必要があるプラットフォーム運用者。
• ホスト側で完了が正常に報告されているのに DPA 側の動作が誤っている場合に、ホスト側の doca-dpa の調査手順を裏付ける証拠として、DPA 側のトレースレポートを作成する AI エージェント。

このスキルは、トレーサーバイナリ自体のデバッグを行うユーザー向けではありません。DOCA DPA Tools の公開ガイドに代わるものでもありません。DPA カーネルの書き方を学ぶユーザーに適した場所でもありません（その対象者には、doca-dpa と、公開されている DOCA DPA／DPACC／DPA-Comms／DPA-Verbs ガイドが適しています）。また、命令ごとの生のサイクルプロファイリングに適した場所でもありません（別の領域、別のツールです。こちらは doca-public-knowledge-map ## DOCA tools を参照してください）。

トレーサは、リンクして使用するライブラリではなく、/opt/mellanox/doca/tools/ 配下にあるCLI バイナリとして提供されます。このスキルは、バンドル内の他の要素と同じ kind: tool の3ファイル構成を採用しており、ライブラリ、サービス、ツールを通じてエージェントのタスク動詞の契約が統一されています。

対象言語

doca_dpa_hl_tracer は C++ のホスト側 CLI です。入力は JSON 設定ファイル、DPA 側の ELF（DPACC が生成する doca_dpa_app クラスのイメージ）、そしてホスト側の doca-dpa ライフサイクルですでに起動済みの DPA 側ワークロードです。出力はバイナリのトレースファイル（bin_file）と、人が読めるログファイル（log_file）です。このスキルでは、ワークフローのガイダンスを言語に依存しないものとしています。トレース対象の DPA 側ワークロードは、DPACC でコンパイルした C、または DPACC が受け入れるその他の DPA 翻訳単位で記述できます。言語ごとの質問は、doca-public-knowledge-map を通じて公開されている DPA／DPACC ガイドを参照するよう案内します。

このスキルを読み込むタイミング

ユーザーが、またはエージェントが、DOCA がインストールされた実機ホスト上で、ホストから DPA プロセッサーが認識できる BlueField に対して doca_dpa_hl_tracer を呼び出す必要があり、ホスト側の doca-dpa のライフサイクルで DPA ワークロードを少なくとも一度起動済みの場合に、このスキルを読み込みます。具体的には、次のような場合です。

• ホスト側の doca-dpa のライフサイクルで正常に完了したと報告されているにもかかわらず、DPA カーネルの誤った結果や順序動作の原因を特定するため、DPA 側のトレースを取得する場合。
• 生のサイクルカウントよりも高い粒度で、DPA 側のパフォーマンス上のギャップ（カーネルへの進入から最初の通信レイテンシまで、RDMA WR の発行から完了までのギャップ、同期ポイントでの滞留時間）の原因を特定するため、DPA 側のトレースを取得する場合。
• バグとオーバーヘッドのトレードオフ、および利用可能なキャプチャ時間枠に基づいて、TRACE と CRIT のキャプチャモードから選択する場合。
• キャプチャ自体が、調査対象のバグ以上にワークロードへ影響を与えないよう、JSON 設定（スレッド優先度、コアアフィニティ、ファイルサイズ制限、ファイルサイズ制限ポリシー）を調整する場合。
• 人間が読み取れるイベントストリームを表示するため、取得した bin_file を対応する DPA 側 ELF に対してデコードする場合。
• ホスト側の doca-dpa の段階的手順に必要な証拠として、副作用を抑えたトレースを取得する場合。

DOCA 全般の概要、DPA 側のプログラミングモデルに関する質問、生のサイクルプロファイリング、または DOCA／DPACC のインストールには、このスキルを読み込まないでください。その場合は、 doca-public-knowledge-map、 doca-dpa、または doca-setup を参照してください。

このスキルでできること

これは薄いローダーです。実質的な内容は、次の 2 つの関連ファイルにあります。

• 機能に関する関連ファイル — doca_dpa_hl_tracer が取得する内容：DPA プログラミングイベントの分類（カーネルへの進入／終了、同期ポイント、通信プリミティブの呼び出し、RDMA WR の送信と完了処理）、文書化されている 2 つのキャプチャモード（イベントごとにすべてを記録する TRACE、重要なイベントのみを記録する CRIT）、トレースのオーバーヘッドと忠実度のトレードオフ、設定ファイルの形式（優先度とコアアフィニティを指定するレシーバー／バイナリーライター／ファイルライター／プリンタースレッド、ファイルサイズ制限、file_size_limit_policy）、キャプチャ時間枠とワークロード実行中でなければならないという不変条件、デコード時に ELF がイメージと一致していなければならないというルール、バージョンの対応関係（トレーサー ↔ doca-dpa ライブラリー ↔ DPACC コンパイラー）、階層化されたエラー分類（インストール／デバイスのバインド／イメージへの計測の組み込み／キャプチャ時間枠／デコード／オーバーヘッド飽和／バージョン／横断的な問題）、可観測性の対象（バイナリートレースファイル＋ログファイル＋ツール自体の標準エラー出力）、および安全ポリシー（キャプチャは範囲が限定されており、トレースは本番環境向けの可観測性機能ではありません）。
• タスクに関する関連ファイル — 対象となるタスク動詞の手順を追ったワークフロー：install（ホスト側の DOCA インストールと DPA の前提条件を参照）、configure（モード＋JSON 設定の構成＋キャプチャ時間枠）、build（インストールを参照 — バイナリーは同梱されており、DPA 側のアプリケーションはユーザーが DPACC でビルドします）、modify（拒否 — バイナリーにパッチを適用せず、JSON 設定と呼び出し方法を変更します）、run（--mode、--config-file、--output-file を使用したキャプチャの流れ）、test（モード、時間枠、オーバーヘッドを調整する反復ループ）、debug（エラー分類に沿って確認）、use（デコード済みトレースを doca-dpa のデバッグセッションで使用）、および Deferred task verbs ブロック。

このスキルは、DOCA が標準の場所にインストール済みのホスト、DPA プロセッサーを搭載してホストから認識できる BlueField、ホスト側の DOCA に対応するバージョンの DPACC コンパイラー、ディスク上にあり doca-dpa のライフサイクルで読み込まれたものと一致する DPA 側アプリケーションイメージ（トレーサーがデコードに使用する ELF）、および公開されている DOCA DPA Tools ガイドで要求される権限を持つオペレーターを前提とします。

このスキルに意図的に含めていないもの

このスキルはエージェント向けガイダンスであり、サンプルやスクリプトの バンドルではありません。境界を明確にするため、意図的に以下を 含めていません。また、プルリクエストで追加しないでください。

• 公開されている DOCA DPA Tools ページおよび --help に記載されているもの以外の、具体的なフラグ文字列、イベント名、モードトークン。 DPA プログラミングのイベントの内容はリリースごとに変化します。 インストール済みバイナリの --help が、正式な一覧です。
• あらかじめ用意されたトレースの例や、想定されるイベントのタイミング。 トレースの出力は、ワークロード、DPA イメージ、BlueField、ファームウェアに固有です。 ある構成で取得した例を固定して掲載すると、別の環境のオペレーターに誤解を与えます。
• バイナリのトレース形式を読み取る、あらゆる言語のラッパー、パーサー、レンダリングスクリプト。 形式はドキュメントに記載されています。スクリプトで利用したいユーザーは、 最新のガイドを読み、インストール済みのバージョンに合わせてパーサーを作成してください。
• 単一のトレースから導き出した特定のチューニング推奨事項。 DPA 側のパフォーマンスに関する判断（同期処理の移動、通信呼び出しのバッチ化、起動引数の変更）は ワークロードに関する問題です。このスキルでは、トレースの取得と読み取りの方法を説明します。 ユーザー自身の分析を経ずに、取得した間隔をカーネル書き換えの推奨事項に置き換えることはしません。
• samples/ または reference/ サブツリー。 これは同梱 CLI を読み込む薄い ローダーです。実質的な情報は、公開ページ、--help、および doca-dpa に記載されています。

読み込み順序

1. まずこのスキルを読み、ユーザーの質問が対象範囲内（DPA 側の高レベルなトレース。DPA 側の プログラミングや生のサイクルプロファイリングではない）であることを確認します。
2. イベント分類、取得モード、オーバーヘッドのトレードオフ、JSON 設定のレイアウト、 バージョンのオーバーレイ、エラー分類、可観測性、安全性ポリシーについては、機能の補足資料を参照してください。
3. ドキュメントに記載された呼び出し方法と、取得 → デコード → レンダリングのワークフロー （install、configure、build、modify、run、test、debug、 use）については、タスクの補足資料を参照してください。

関連スキル

• doca-dpa — ホスト側の DPA 制御ライブラリです。トレーサーは、このライブラリによって 読み込まれたアプリケーションイメージをキャプチャします。 すべての DPA デバッグセッションで両者を組み合わせてください。 doca-dpa はワークロードを起動し、トレーサーは DPA プログラミングイベント層でワークロードの動作をキャプチャします。 ライブラリとトレーサーを混同することは、DPA デバッグで 初めて使う際によくある誤りです。
• doca-debug — 分野横断的な デバッグ手順です。DPA 側のパフォーマンスや正確性について 結論を出す前に、トレーサーを DPA 側の確かな事実を確認する ランタイム層で使用します。
• doca-public-knowledge-map — docs.nvidia.com にある公開 DOCA DPA Tools ページと、 その他の公開 DOCA ドキュメント一式への案内です。
• doca-version — DOCA の バージョンを扱う際の標準ルールです。機能の補足資料にある ## Version compatibility セクションは、本文についてはこちらを参照するよう 案内する簡潔な補足であり、tracer ↔ doca-dpa library ↔ DPACC compiler の互換性ルールも追加しています。
• doca-setup — 環境の準備、 インストールの確認、DPACC コンパイラーのインストール／確認、 BlueField モード（トレースを有意義なものにするには、事前に DPA プロセッサーが公開されている必要があります）、および 公開 NGC DOCA コンテナーを使う まだ何もインストールしていない場合 の手順です。
• doca-structured-tools-contract — このバンドルに含まれる構造化ヘルパーツールの 検出 → 優先 → フォールバック → 報告という契約です。 タスクの補足資料にあるコマンド付録は、この契約に準拠しています。
• doca-programming-guide — すべてのライブラリ／ツールのインターフェイスに共通する DOCA の一般的なプログラミングパターンです。ホスト側の doca-dpa 呼び出しが同時に失敗した場合に、このツールの ホスト側エラー層が重ねて適用する、ライブラリ横断の DOCA_ERROR_* 分類も含まれます。

DPA 側の補助ライブラリである doca-dpa-comms（DPA カーネル自体が 呼び出す通信プリミティブ）と doca-dpa-verbs（DPA カーネル自体が 呼び出す RDMA verbs）は、トレーサーの DPA programming events インターフェイスに名前が表示される、別個の成果物です。 DPA 側のプログラミングモデル自体については、 doca-public-knowledge-map を通じて、公開 DOCA DPA-Comms および DPA-Verbs ガイドと、 同梱されている /opt/mellanox/doca/samples/doca_dpa/ サンプルを 参照してください。このツールはそれらの使用状況をトレースしますが、 それらの定義を変更するものではありません。