doca-flow-tune

DOCA Flow Tune (doca_flow_tune)

例

• 「BlueField でフロールールのインストールレートが低いです。」 — これは対象範囲内です。まずスナップショットを取得し、その後チューニングの軸を選択してください。これを flow-perf のベースライン実行に置き換えないでください。
• 「Tune の可視化ステップが空です。」 — Flow プログラムを変更する前に、ダンパーの JSON／CSV／analyze の JSON を確認してください。

手順

以下の読み込み順に従ってください。設定／チューニング／デバッグについてはタスクの補足ファイルを開いてください。オンラインモードとオフラインモードについては機能の補足ファイルを開いてください。補足ファイルをすべて開かないでください。

コマンドの仕様（DOCA 3.5 公開 Flow Tune ガイド）。 doca_flow_tune は単一のバイナリであり、特定の実行における役割は、ユーザーが選択する 3 つのトップレベルコマンド（monitor、analyze、visualize）のいずれかによって決まります（インストール済みバージョンで --help を確認してください）。dump、web、import、sim_timing は 3.5 のガイドには記載されていません。実行しないでください。 カウンターのダンプは monitor の機能（--enable-dump、または画面出力なしでダンプする background サブコマンド）であり、独立したコマンドではありません。analyze は export と packet-trace（ハイフン区切り）のサブコマンドを受け付けます。monitor と analyze は、同梱されている flow_tune_cfg*.json の network.server_uds にパスが設定された Unix ドメインソケット経由で接続する、稼働中の doca-flow アプリケーションに対して、サーバー接続型のオンラインモードでバイナリを実行します。visualize（および、以前エクスポートしたパイプラインファイルのオフライン分析）は、オンラインコマンドが以前に設定済みの outputs_directory に出力した JSON／CSV ファイルを対象に、オフライン／キャプチャ済みスナップショットモードで実行します。このスキルの残りの部分（および機能の補足ファイル／タスクの補足ファイル）では、従来の「サーバーの役割／オンラインモード／オフラインモード」という枠組みを使用しています。この枠組みは、ここで説明するコマンドの仕様と内部的に整合しています。「サーバーの役割」＝サーバー接続型のオンラインコマンド（monitor、analyze export／analyze packet-trace）、「オンラインモード」＝これらのいずれか、「オフラインモード」＝キャプチャ済みファイルに対する visualize です。コマンド名を第一の手掛かりとし、「サーバー／オンライン／オフライン」はサブコマンドの選択に伴う動作上の結果として扱ってください。

開始位置： これは、統合 DOCA Flow チューニングツールである doca_flow_tune を呼び出すためのツールスキルです。タスクの補足ファイルを開き、まず ## configure から始めて、3 つの軸（対象の Flow パイプライン × チューニング軸 × 測定）の選択を確定し、オフライン／オンライン／サーバー接続モードのいずれかを選んでください。次に ## run でスナップショット → 分析 → 可視化のループを実行し、続いて ## test で、チューニングの推奨事項を Flow アプリケーションのコードに反映する際の状態変更を伴う適用を制御する、バルク処理前のスモークテスト用オーバーレイを確認してください。doca_flow_tune が観察および推奨できる状態、単一の成果物内でサーバー／クライアントの各役割がどのように構成されているか、ツールに同梱されている DOCA のバージョン、または自分を欺かずにダンパー／monitor／analyze／visualize の出力を解釈する方法についての質問であれば、機能の補足ファイルを開いてください。DOCA がインストールされていない場合は、まず doca-setup/SKILL.md に案内してください。ユーザーがまだ稼働中の doca-flow アプリケーションを用意していない場合は、doca-flow/SKILL.md に案内してください。flow-tune はパイプを作成しません。ライブラリがすでに作成したパイプ上で観察し、推奨を行います。

このスキルが得意とする質問の例

このスキルが回答できるよう設計されている、doca_flow_tune に関する質問のクラスと、それぞれの具体例です。重要なのは質問のクラスであり、具体例はその一例です。

• 「この質問には doca-flow-tune と doca-flow-perf のどちらを使うべきですか？」 — 具体例：「私の doca-flow サービスは BlueField-3 で動作しており、ルールのインストール速度がデバイスの処理能力を下回っていると思います。まず測定すべきですか、それとも先にチューニングすべきですか？」。機能の補足資料にあるチューニングと性能測定の境界と、ベースラインの測定には doca-flow-perf/SKILL.md、測定済みベースラインに基づく最適化にはこのスキルを使うという振り分けで回答します。
• 「データプレーンに触れずに、稼働中の doca-flow パイプラインのハードウェアカウンターとソフトウェアカウンターのスナップショットを取得したい。」 — 具体例：「運用レートプロファイル向けに、稼働中の Flow ポートを対象とした副作用のないダンプ／モニターを実行したい」。タスクの補足資料にあるスナップショットの手順と、機能の補足資料にある読み取り専用をデフォルトとする方針で回答します。
• 「実際の質問に応じて、ルール配置、リソースのヒント、ハードウェアオフロードモードのうち、適切なチューニング軸を選びたい。」 — 具体例：「私の Flow パイプのルールインストール速度が低いのですが、配置の問題ですか、それともテーブルサイズの問題ですか？」。機能の補足資料にある3つの設定軸と、タスクの補足資料にある設定手順で回答します。
• 「単一の成果物の中で、doca_flow_tune のサーバーの役割とクライアント／利用側の役割はどのように連携しますか？」 — 具体例：「Flow Tune サーバーと Flow Tune クライアントについて何度も目にしますが、どのバイナリを実行すればよいですか？」。機能の補足資料にある1つのバイナリ、2つの役割の説明と、タスクの補足資料にある対応する振り分けで回答します。
• 「データプレーンを壊さずに、flow-tune が推奨したパラメーターの変更を doca-flow アプリケーションに反映するにはどうすればよいですか？」 — 具体例：「analyze の手順で、私のパイプに別のテーブルサイズが提案されました。どのように適用すればよいですか？」。タスクの補足資料にある推奨事項から Flow プログラムの最小限の差分変更へという反復手順と、同資料にある一括適用前にスモークテストを行うルールで回答します。
• 「doca_flow_tune が何も報告しない／Flow アプリと食い違う／接続できない場合、どういう意味ですか？」 — 具体例：「ツールは動作しますが、visualize の手順で空の mermaid 図が生成されます」。機能の補足資料とタスクの補足資料にある、階層化されたエラー分類で回答します。

対象読者

このスキルは、外部オペレーター、パフォーマンスエンジニア、DOCA Flow アプリケーション開発者、およびユーザーの実際のインストール環境とデバイス上で、稼働中の doca-flow パイプラインの動作を理解、特性評価、または改善する必要がある AI エージェントを対象としています。 具体的には、次のような方が対象です。

• 変更を勧める前に、どのパイプが存在し、ハードウェア／ソフトウェアのカウンターがどのように推移しているかを読み取り専用で確認したいオペレーター。
• doca-flow-perf のベースラインがあり、測定を最適化につなげたいパフォーマンスエンジニア。調整軸を選び、doca-flow プログラムのどの設定値が調整の手段になるかを特定します。
• プログラムに再度計測機能を組み込まずに、オフラインの分析＋可視化のワークフローでパイプレイアウトを把握したい Flow 開発者。
• *「このパイプラインは期待どおりに動作しているか。変更を加えない調整のヒントが役立つか」*というトリアージを進める AI エージェント。

このスキルは、doca_flow_tune のソースコードをデバッグするユーザー向けではありません。公開されている DOCA Flow Tune ガイドの代わりでもありません。doca-flow API を学ぶための場所でもありません（doca-flow/SKILL.md を参照してください）。また、ベースラインの測定方法を学ぶ場所でもありません。それについては doca-flow-perf/SKILL.md を参照してください。

doca_flow_tune は、単一のツール（1 つのバイナリと、付属のアナライザー／ビジュアライザーのスクリプトおよび JSON 設定テンプレート）として提供されます。従来のサーバーとクライアントの役割は 2 つの実行ファイルに分かれているのではなく、この 1 つの成果物の中にあります。バンドル内の他のものと同じ kind: tool の 3 ファイル構成を使用します。

言語の範囲

このスキルでは、doca_flow_tune が監視する DOCA Flow アプリケーションについて、呼び出し、出力の解釈、および推奨事項からコード変更への振り分けを扱います。このツールはプログラミングの対象ではありません。リンク可能な公開 API はありません。ワークフローはJSON を設定し、実行し、出力を読み、周辺の doca-flow プログラムに対する最小差分の変更を提案することです。推奨事項の適用先となる doca-flow API については、doca-flow/SKILL.md を参照してください。 言語をまたぐアプリケーションパターンについては、doca-programming-guide/SKILL.md を参照してください。

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

ユーザーが稼働中または計画中の doca-flow アプリケーションに対して doca_flow_tune を呼び出し、パイプラインの特性評価、ダンプ、可視化、分析、または調整を行う場合（またはエージェントがその必要がある場合）に、このスキルを読み込んでください。 具体的には、次のような場合です。

• どの役割を使うか選ぶ場合（キャプチャ済みの設定と状態に対するオフラインの分析／可視化、稼働中のアプリケーションに対するオンラインのダンパー／モニター、またはアプリケーションに接続するサーバー役の使い方）。
• どの調整軸について確認するか選ぶ場合（ルールの配置、リソースのヒント／テーブルサイズ、ハードウェアオフロードモード）。
• どの測定軸を比較するか選ぶ場合（ルールのインストール率、検索レイテンシ、ハードウェアカウンターの差分）。これらは相互に置き換えられません。以前の doca-flow-perf のベースラインで指定された軸を使用してください。
• 提案した Flow プログラムの変更の前後で、記録に残る比較用データを取得する場合（JSON 設定パス、コマンドライン、DOCA のバージョン、デバイス、環境、未加工のツール出力）。
• 空のセッション、退化した可視化図、または稼働中のカウンターと矛盾する分析の推奨事項を診断する場合。

一般的な DOCA の概要、Flow プログラムの API 作業、インストール、または測定方法のみを扱う場合は、このスキルを読み込まないでください。doca-public-knowledge-map/SKILL.md、doca-flow/SKILL.md、doca-setup/SKILL.md、または doca-flow-perf/SKILL.md を参照してください。

このスキルが提供するもの

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

• capabilities companion — doca_flow_tune が何を観測し、 何を推奨するかについて説明します。統合アーティファクトの 分解（1つのバイナリ内のサーバーの役割 ＋クライアント／コンシューマーの役割）、3軸の 設定モデル（チューニング軸 × 測定 × スコープ：対象の パイプ／ポート／アプリ）、文書化されたオフライン／オンライン／アタッチ モード、JSON 設定ファイルの形式（公開されている flow_tune_cfg_public.json テンプレートと、 ハードウェア専用およびソフトウェア専用のバリアント）、 ダンパー／モニター／分析／可視化の各出力面、バージョン オーバーレイ（このツールは観測対象の doca-flow ライブラリのバージョンに追従します。正式な ルールは doca-version/SKILL.md にあります）、 階層化されたエラー分類 （config-syntax / attach-failed / pipe-not-found / measurement-unsound / recommendation-unactionable / version / cross-cutting）、可観測性の方針（このツールは Flow パイプラインの可観測性プリミティブそのものです）、および 推奨事項を適用して状態を変更する操作が、稼働中の Flow 状態に 反映されるため重大な影響を伴うものとなる安全ポリシー。
• tasks companion — 対象範囲内のタスク動詞について、手順を ステップごとに説明します。 install（セットアップへ誘導。バイナリは同梱済み）、 configure（3軸の判断＋JSON 設定＋モードの選択）、 build（install へ誘導。バイナリは同梱済み）、modify （最小差分で Flow プログラムに推奨事項を反映）、 run（スナップショット → 分析 → 可視化のフロー）、 test（評価ループ — ウォームアップ、定常状態、変更前／変更後の ペア、クライアント／サーバー／Flow のバージョン一致）、debug （エラー分類を階層ごとに確認）、use（flow-tune の出力を 利用するエージェント側のワークフロー）、さらに Deferred task verbs ブロックと Command appendix が含まれます。

このスキルは、DOCA がすでにインストールされている（または 公開 NGC DOCA コンテナが実行中の）ホストと、 doca-flow/SKILL.md スキルに従って doca-flow アプリケーションがすでに作成・検証済みであることを 前提としています。これらの前提条件を満たさない場合、 チューニングセッションで観測できるものはありません。

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

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

• 契約として引用する、フラグ一覧、サブコマンド名、JSON 設定フィールド名、 デフォルトのエンドポイントパスの逐語的な記載。 公開 DOCA Flow Tune ガイド（ doca-public-knowledge-map ## DOCA tools 経由で参照 （doca-public-knowledge-map/SKILL.md#doca-tools）） と、インストール済みの --help が共同で信頼できる情報源です。 JSON スキーマの第2の情報源は、同梱されている flow_tune_cfg*.json テンプレートです。これらをここにコピーすると、 ツールの進化に伴って内容が古くなります。
• 事前に用意された出力例（ダンパーの CSV 列、アナライザーの JSON フィールド名、ビジュアライザーの mermaid 出力）。 出力はインストール環境、 デバイス、ファームウェア、バージョンによって異なります。特定のプラットフォームに 固定されたキャプチャ例は、他の環境で運用する担当者に誤解を与えます。
• flow-tune の出力を利用するラッパー、パーサー、スクリプト。 ユーザーのインストール環境に同梱されている scripts/ ディレクトリには、 ベンダー提供のヘルパー（例：flow_json_diff.py、 flow_mermaid_diff.py、hw_counters_csv_analyzer.py）が含まれています。 適切な回答は「インストール済みバージョンに同梱されているスクリプトを 読んでください」です。
• 事前に用意されたチューニング推奨事項。 推奨事項はインストール環境、 デバイス、ファームウェア、ワークロードによって異なります。エージェントは 常に、ユーザーの実際のセッションに基づいて推奨事項を導き出します。
• samples/、templates/、reference/ サブツリー。 模擬的な チューニング手順は本番環境向けのものに見え、誤解を招きます。

読み込み順

1. まずこのスキルを読み、ユーザーの質問が対象範囲内であることを確認します（ユーザーがベースライン性能の測定や Flow API の学習ではなく、doca-flow パイプラインに対して doca_flow_tune を実行したいと考えていることを確認します）。
2. doca_flow_tune が観測する内容、1つのバイナリと2つのロールへの分解、3軸モデル、バージョンのオーバーレイ、エラー分類、可観測性の対象、安全性に関する方針については、機能コンパニオンを参照してください。
3. ドキュメントに記載された実行方法と、スナップショット → 分析 → 可視化 → 提案 → スモークテストのワークフロー（install、configure、build、modify、run、test、debug、use）については、タスクコンパニオンを参照してください。

関連スキル

• doca-flow/SKILL.md — このツールが観測・調整するパイプラインを提供する基盤ライブラリです。flow-tune が報告するパイプ／エントリー／ルールの構成要素は、doca-flow のプログラムコードによって作成されます。推奨事項は、汎用的なサンプル変更ワークフローを通じて、そのプログラムに反映されます。
• doca-flow-perf/SKILL.md — 関連する測定ツールです。ルールは次のとおりです。doca-flow-perf はベースラインを測定し、doca-flow-tune はそれを踏まえて最適化を提案します。perf によるベースライン値を得ずに tune を使うエージェントは、暗闇の中で最適化することになります。一方、明確な問いもなく perf を使うエージェントは、目的もなくベンチマークを実行することになります。
• doca-public-knowledge-map/SKILL.md — docs.nvidia.com の公開 DOCA Flow Tune ページと、その他の公開 DOCA ドキュメントへの案内です。
• doca-version/SKILL.md — 正式なバージョン検出手順、4者の照合、NGC の仕様、ヘッダー優先のルールについて説明します。このスキルの ## Version compatibility オーバーレイは、その上に重ねる薄い拡張です。
• doca-debug/SKILL.md — 分野横断的なデバッグ手順です。Flow-tune は独自のエラー分類を示します。原因が DOCA より下位（ドライバー、ファームウェア、NUMA）にあると判明した場合、tune の分類から doca-debug に引き継ぎます。
• doca-structured-tools-contract/SKILL.md — このバンドルの「検出 → 優先 → フォールバック → 報告」契約です。タスクコンパニオンのコマンド付録は、この契約に従います。
• doca-setup/SKILL.md — 環境の準備、インストールの確認、HugePages、NUMA、および公開 NGC DOCA コンテナーを使ったまだインストールしていない場合の手順です。
• doca-hardware-safety/SKILL.md — このスキルの ## Safety policy がオーバーレイする、分野横断的なハードウェア安全性メタポリシーです。