doca-flow-perf

DOCA Flow Perf（doca_flow_perf）

例

• 「BlueField は毎秒何件のルールを挿入できますか？」 — これは対象範囲内です。doca_flow_perf を使ってください。ここでは稼働中の Flow アプリを調整しないでください。
• 「DPDK と DOCA のベンチマーク比較。」 — JSON ポリシーと バックエンドを選び、Kops/sec の数値を根拠づける 4 タプルを記録してください。
• 「本番パイプラインでハードウェアオフロードが失われています。」 — 対象範囲外です。稼働中の Flow アプリの診断は doca-flow-tune の担当です。その名前を伝えて終了し、 そのために doca_flow_perf のベンチマークを実行しないでください。

手順

以下の読み込み順に従ってください。設定／実行／デバッグについてはタスク用コンパニオンを開いてください。バックエンドとポリシーファイルについては機能用コンパニオンを開いてください。コンパニオンファイルをすべて開かないでください。

最初に行うこと： これは、ホスト側／DPU の CPU 側で DOCA Flow の性能を測定するツール doca_flow_perf を実行するためのツールスキルです。タスク用コンパニオンを開き、まず ## configure に進んでください。3 軸の判断（対象となる Flow パイプラインの形状 × トラフィッククラス × 測定軸）を確定し、ワークロードを表す JSON ポリシーファイルを選びます。次に ## run に進み、1 回の反復によるスモークテストを実施します。その後、## test に進み、根拠のある Kops/sec クラスの数値を出す反復評価ループを実行します。質問が doca_flow_perf が何を測定し、意図的に何を測定しないか、同じ JSON 契約のもとで DPDK と DOCA のバックエンドがどう異なるか、反復ごとの CPU サイクル出力をどう解釈するか、または doca-flow-tune（測定と最適化）の違い に関する場合は、機能用コンパニオンを開いてください。DOCA がインストールされていない場合は、まず doca-setup/SKILL.md に案内してください。合成パイプラインを測定するのではなく、すでにデプロイ済みの Flow パイプラインを最適化することが目的の場合は、doca-flow-tune/SKILL.md に案内してください。flow-perf は合成ドライバーによるマイクロベンチマークであり、稼働中の Flow アプリを調整するツールではありません。

このスキルの使い方。 このファイルを読み、質問に必要な ## <name> 見出しをコンパニオンファイル内で検索し、そのセクション全体を読んでください。回答はその内容だけに基づいて完全に記述し、記号とコマンドは記載されているものだけを引用してください。ドキュメントは参照せず、doca-public-knowledge-map のエントリーポイントを使ってください。環境の確認方法は、ユーザーの DOCA ホストで実行するコマンドとして提示してください。対象範囲外の依頼では、担当するスキルの名前を伝えて終了してください。

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

• 「5 タプルのマッチとヘアピン処理を行うワークロードで、単一の BlueField-3 が 1 秒あたりに挿入できる doca-flow ルール数について、ホスト側の妥当なベースライン値を得たいです。どのポリシー JSON を出発点にすればよいですか？結果を再現可能にするにはどうすればよいですか？また、その値を妥当なものとして示すには、値とともに何を記録する必要がありますか？」 — クラスに沿ったフローパフォーマンスのベースラインに関する質問です。エージェントは configs/ ライブラリ、JSON の仕様、4 タプルを記録するルールを確認します。
• 「doca-flow-perf と doca-flow-tune の違いは何ですか？どちらの名前にも doca-flow とありますが、それぞれどんなときに使えばよいですか？」 — 測定と最適化の違いに関する質問です。エージェントは両者の境界を明確にします。
• 「ポリシー JSON は例と同じように見えるのに、報告された Kops/sec が NVIDIA のリリースノートで見た公開値より大幅に低いです。比較を信頼できるものにするには、どの変数を制御する必要がありますか？」 — 方法論に関する質問です。エージェントは制御可能な要素（ワーカー数、キュー深度、バーストサイズ、マッチフィールドを固定するか増加させるか、DPDK と DOCA のバックエンド、BlueField モード、ドライバー／ファームウェア）を確認します。
• 「configs/ にある提供済みのポリシー JSON のどれにも合わないワークロードがあります。新しいポリシー JSON を作成するにはどうすればよいですか？JSON スキーマの概要を教えてください。また、マッチフィールドの mode: fixed を mode: increase に切り替えると、何が変わりますか？」 — JSON の作成に関する質問です。エージェントは提供済みの設定を例として確認し、ソースツリーにないスキーマフィールドをでっち上げることはありません。
• 「このツールが実際に測定しないものは何ですか？フローパフォーマンスの値がエンドツーエンドのトラフィックレイテンシについて何かを示すのか、それともルールプログラミングのコントロールプレーンレートだけを示すのかを知りたいです。」 — 方法論の範囲に関する質問です。エージェントは明確に線引きします。このツールが測定するのはルールのインストール／削除（コントロールプレーン）レートと、オプションのクエリレートであり、データプレーンのレイテンシでもスループットでも、エンドツーエンドのアプリケーション性能でもありません。
• 「同じ JSON で 2 つのバックエンド（DPDK と DOCA）を使えるようですが、どちらを選べばよいですか？選択によって、報告する結果はどう変わりますか？」 — バックエンドの選択に関する質問です。エージェントは DPDK バックエンドと DOCA バックエンドのトレードオフを確認し、オペレーターがどちらを使ったかを必ず報告するよう求めます。

対象読者

doca-flow のプログラミングモデルと DPDK コントロールプレーンに慣れており、ホスト側／DPU の CPU 側での Flow ルールのインストール／削除レートについて、妥当な値を求めている、経験豊富な AI エージェントとプラットフォーム／ネットワークエンジニアを対象としています。読者は、NVIDIA のリリースノートに掲載された値が非常に限定された前提条件（特定の DOCA バージョン、特定の BlueField ファームウェア、特定のトラフィッククラス）で測定されており、ローカルで得た値にはそうした前提条件を明記する必要があることを理解しているものとします。

このスキルは、以下の方を対象としていません。

• デプロイ済みの doca-flow アプリケーションを最適化したいオペレーター — その場合は doca-flow-tune/SKILL.md を参照してください。
• エンドツーエンドのデータプレーンスループットやレイテンシを測定するオペレーター — それはアプリケーションの責任範囲であり、doca-flow/SKILL.md に加えて対応するものです。
• ツール自体を作成または変更するコントリビューター。

対象言語の範囲

doca_flow_perf とのユーザーのやり取りは、次の方法で行います。

1. 同梱バイナリのコマンドラインフラグ（doca_flow_perf --help および docs.nvidia.com の公開 DOCA Flow Perf ガイドに記載）。
2. パイプライン（ポート、パイプ、マッチャー、アクション、転送）を記述する JSON ポリシーファイル。同梱の configs/ ディレクトリには、最も一般的なトラフィッククラス向けの既成ポリシーが含まれており、新しいポリシーはそのいずれかをコピーして編集して作成します。
3. ツールの反復ごとの出力（反復あたりの CPU サイクル数、処理数、失敗数。ツールの stdout を通じて報告されます。正確な形式は公開ガイドとバイナリの実行時出力で定義されており、このスキルが定めるものではありません）。

スキル自体は Markdown です。doca_flow_perf のプログラム用 API はなく、利用者はその結果を stdout または取得したログから読み取ります。

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

次のいずれかに該当する場合は、doca-flow-perf を読み込んでください。

• ユーザーが doca_flow_perf、doca-flow-perf、configs/ JSON ライブラリに言及した場合、または「ホスト側のフロールール毎秒」の数値を求めている場合。
• ユーザーが、稼働中のアプリケーションを最適化するのではなく、基盤となる Flow 経路のベースラインを測定したい場合。
• ユーザーが、DOCA リリース、BlueField の世代、またはファームウェアのバージョン間で、ホスト側／DPU-CPU 側の Flow パフォーマンスを比較している場合。
• ユーザーが新しいトラフィッククラスの JSON を設計するにあたり、どの既成の configs/ JSON を元にすべきか、どのフィールドを変更できるかを知りたい場合。

次のスキルと併せて読み込んでください。

• doca-flow/SKILL.md（基盤ライブラリ。flow-perf は、ライブラリが公開するものと同じマッチャー／アクション／パイプをプログラムします）。
• doca-flow-tune/SKILL.md（測定と最適化の違いは、最もよくある混同です）。
• doca-version/SKILL.md（報告するすべての flow-perf の数値に付記する必要がある、4 要素のバージョン一致情報）。
• 環境側のデバッグ手順のために、doca-debug/SKILL.md と doca-setup/SKILL.md。

ユーザーが稼働中の Flow アプリケーションを最適化したい場合は、このスキルを読み込まないでください（doca-flow-tune/SKILL.md に誘導してください）。

このスキルの内容

このディレクトリにある 3 つの関連ファイルは、それぞれ異なる種類の質問を扱います。

• このスキル — このファイルです。対象読者、範囲、読み込み順序、関連スキルを説明します。それ以外の内容はすべて適切な場所に誘導します。
• 機能の関連ファイル — doca_flow_perf とは何か、何を測定し、意図的に何を測定しないのか、DPDK と DOCA のバックエンドの二重性、JSON の契約範囲、反復ごとの出力の解釈、バージョン互換性（doca-flow および doca-version と連携）、階層化されたエラー分類、可観測性、安全性ポリシーの適用について説明します。
• タスクの関連ファイル — 手順を表す動詞（configure、run、test、debug など）に加えて、doca_flow_perf 固有のコマンド付録と、取得した反復ごとの出力を利用するエージェント側の use ワークフローを扱います。

このスキル一式は、doca_flow_perf に関する測定クラスの質問に AI エージェントが対応する方法を説明します。提供済みまたは新規作成したポリシー JSON を選び、単一反復のスモークテストを実行し、反復評価ループを実行し、結果の数値を裏付ける 4 要素の情報を取得し、出力を解釈し、隣接する質問（稼働中のアプリケーションのチューニング、DPA 経路の測定、ファームウェアの最適化）をそれぞれ適切な関連スキルに誘導します。

このスキルが意図的に提供しないもの

• データプレーンのエンドツーエンドのスループットやレイテンシの測定。 doca_flow_perf が測定するのは、ルールを設定するコントロールプレーンの速度と、オプションのエントリーごとのクエリー時間です。データプレーンで、結果として生成されるルールをパケットがどれだけ速く通過するかは測定しません。それを担うのはアプリケーションであり、doca-flow/SKILL.md を基盤とします。オペレーターから「Flow のスループット」について尋ねられた場合、エージェントはこの点を明確に伝える必要があります。
• デプロイ済み Flow アプリケーションの最適化。 doca-flow-tune/SKILL.md を案内してください。flow-perf は JSON で記述されたパイプラインを駆動する合成ドライバーであり、稼働中のパイプラインをチューニングするものではありません。
• 唯一の「正解」となる Kops/sec の値。 エージェントは、公開済みの数値を記憶に基づいて権威あるものとして引用しません。公開済みの数値は、DOCA のバージョンと BlueField の世代ごとに NVIDIA のリリースノートに記載されています。比較する前に、オペレーター自身が正確に同じ前提条件で再現する必要があります。
• 作り出した JSON スキーマフィールド。 エージェントは、同梱の configs/ のサンプルに存在しないポリシー JSON キーを作り出しません。オペレーターが必要とするキーが同梱のサンプルにない場合は、その旨を伝え、公開されている DOCA Flow Perf ガイドを案内します。
• ライブラリ内部の doca-flow API の解説。 基盤となるマッチャーとアクションについては doca-flow/SKILL.md を参照してください。このスキルではそれらに触れますが、ライブラリの API ドキュメントを重複して記載することはありません。
• 前提条件が異なるツール間の、公平に比較できるベンチマークの主張。 DOCA のバージョン、BlueField の世代、ファームウェアのバージョンが異なる場合、2 つの flow-perf の数値を直接比較することはできません。利用者が比較の妥当性を判断できるよう、エージェントは 4 項目の情報を記録するよう求めます。

読み込み順序

doca_flow_perf に関する質問を受けた場合：

1. DOCA がインストールされており、バイナリと configs/ の JSON ライブラリにアクセスできることを確認します。そうでない場合は doca-setup/SKILL.md を案内します。
2. デバイス上で基盤となる doca-flow ライブラリが正常に動作していることを確認します。そうでない場合は doca-flow/SKILL.md を案内します。
3. ユーザーが最適化ではなく測定を希望していることを確認します。最適化を希望している場合は doca-flow-tune/SKILL.md を案内します。
4. 対象のパスが、このツールの測定対象であるホスト／DPU-CPU であることを確認します。
5. ケイパビリティの補足資料を読み、3 軸の判断（パイプラインの形状 × トラフィックのクラス × 測定軸）を確定します。
6. タスクの補足資料を読み、## configure → ## run → ## test → ## debug の順に進めます。## configure の前提条件を満たさずに ## run から始めてはいけません。

関連スキル

相互リンクの規約は、tools/<X>/ からのバンドル相対パス 契約に従います。

• doca-flow/SKILL.md — 基盤となるライブラリです。flow-perf は Flow のパイプ、エントリー、マッチャー、アクションをプログラムします。このライブラリが、flow-perf が演習する API の正式な情報源です。
• doca-flow-tune/SKILL.md — 統合 Flow チューニングツールです。測定と最適化の境界はこちらにあります。「数値を知りたいのか、それともデプロイ済みのパイプラインを変更したいのか」を確認してください。
• doca-version/SKILL.md — 報告する flow-perf の数値にはすべて、ホストパッケージ、カーネルモジュール、ファームウェア、対象アプリケーションにリンクされた doca-flow バージョンの 4 項目の一致と、BlueField / ConnectX の世代を必ず付記してください。flow-perf はこのルールに従うものであり、これに反するものではありません。
• doca-setup/SKILL.md — DOCA のインストール方針です。「バイナリがそもそも存在するか」という質問の振り分け先です。
• doca-debug/SKILL.md — 環境側の問題（ドライバー、ファームウェア、BlueField モード、カーネルモジュール）に対応する、分野横断的なデバッグ手順です。
• doca-bench/SKILL.md — より広い範囲を対象とする、同種のベンチマークツールです（Flow だけでなく、複数の DOCA プリミティブを対象とします）。flow-perf は Flow 専用のマイクロベンチマークで、doca-bench はより広範なワークロードベンチマークです。
• doca-public-knowledge-map/SKILL.md — リリース固有の公開済み数値や再現性に関する注記について、公開されている docs.nvidia.com の DOCA Flow Perf ページ、リリースノート、フォーラムへ案内します。
• doca-structured-tools-contract/SKILL.md — 構造化ヘルパー（doca-env --json、doca-capability-snapshot、version-matrix.json）に関する、エージェントの検出 → 優先 → フォールバック → 報告の契約です。flow-perf の前提条件はこれらに依存します。
• doca-hardware-safety/SKILL.md — 機能の補助スキルが重ねて適用する、ハードウェア安全性に関する標準メタポリシーです。

このスキルでは、周辺の doca-flow アプリケーションを オペレーターが既に所有するソース成果物と想定しています。flow-perf 自体は サンプルの doca-flow アプリケーションを同梱していません。