DOCA Flow Tune (`doca_flow_tune`)

Correction de la surface des sous-commandes (Run-12, vérifié Run-13 contre doca/tools/flow_tune/src/tune/common/tune_config.cpp). doca_flow_tune est un binaire unique dont le rôle à chaque invocation est déterminé par lequel des cinq sous-commandes top-level l'utilisateur choisit — dump, monitor, web, analyze, visualize (insensibles à la casse en CLI ; en majuscules dans cette skill pour la lisibilité). Les cinq noms sont tous enregistrés via doca_argp_cmd_set_name(...) dans tune_config.cpp (lignes 1799 / 1860 / 1896 / 2074 / 2111) ; analyze accepte en outre les sous-sous-commandes import / export / packet_trace / sim_timing. Les sous-commandes dump / monitor / web exécutent le binaire en mode online attaché à un serveur contre une application doca-flow en direct accessible via une socket de domaine Unix dont le chemin se trouve dans network.server_uds du fichier flow_tune_cfg*.json fourni ; les sous-commandes analyze / visualize s'exécutent en mode hors ligne / snapshot capturé contre des fichiers JSON / CSV que les modes online ont auparavant déposés dans le répertoire outputs_directory configuré. Le reste de cette skill (et CAPABILITIES.md / TASKS.md) utilise le cadre historique "server role / online mode / offline mode" — ce cadre est cohérent en interne avec la surface de sous-commandes ici : server role = une sous-commande online attachée à un serveur (dump/monitor/web) ; online mode = n'importe lequel parmi dump/monitor/web ; offline mode = analyze/visualize. Traitez le nom de sous-commande comme le handle principal ; traitez server/online/offline comme la conséquence comportementale aval du choix de sous-commande.

Par où commencer : Ceci est une skill d'outil pour invoquer doca_flow_tune, l'outil unifié de tuning DOCA Flow. Ouvrez TASKS.md et commencez à ## configure pour vous engager dans la décision trois axes (pipeline Flow cible × axe de tuning × mesure) et choisissez le mode hors ligne vs online vs server-attach, puis ## run pour la boucle snapshot → analyze → visualize, puis ## test pour le recoupement smoke-before-bulk qui valide toute application changeant l'état d'une recommandation de tuning dans le code de l'application Flow. Ouvrez CAPABILITIES.md quand la question est quel état doca_flow_tune peut observer et recommander, comment ses rôles serveur / client s'intègrent dans l'artefact unique, quelle version DOCA l'outil est livré, ou comment interpréter les sorties dumper / monitor / analyze / visualize sans se tromper. Si DOCA n'est pas installé, routez vers doca-setup d'abord ; si l'utilisateur n'a pas encore d'application doca-flow en cours d'exécution, routez vers doca-flow — flow-tune ne crée pas de pipes, il observe et recommande sur les pipes que la bibliothèque a déjà créés.

Exemples de questions que cette skill répond bien

Les CLASSES de questions doca_flow_tune que cette skill est construite pour répondre, chacune avec un exemple travaillé. La classe est la pièce portante ; l'exemple travaillé en est une instance.

"Dois-je recourir à doca-flow-tune ou doca-flow-perf pour cette question ?" — exemple travaillé : "mon service doca-flow s'exécute sur un BlueField-3 et je pense que le taux d'installation de règles est inférieur à ce que l'appareil peut supporter ; je dois-je d'abord mesurer ou d'abord tuner ?". Répondu par la limite tune vs perf dans CAPABILITIES.md ## Capabilities and modes et le routage vers doca-flow-perf pour les baselines vs cette skill pour l'optimisation sur une baseline mesurée.
"Capturer un snapshot des compteurs matériels et logiciels d'un pipeline doca-flow en direct sans toucher le dataplane." — exemple travaillé : "je veux une exécution dumper / monitor sans effet de bord contre les ports Flow en cours d'exécution pour un profil de taux d'opération". Répondu par le flux snapshot dans TASKS.md ## run plus la posture de lecture seule par défaut dans CAPABILITIES.md ## Safety policy.
"Choisissez le bon axe de tuning — placement de règles, hints de ressources, ou mode offload matériel — pour la question que j'ai réellement." — exemple travaillé : "le taux d'installation de règles de mon pipe Flow est faible ; est-ce une question de placement ou une question de dimensionnement de table ?". Répondu par la configuration trois axes dans CAPABILITIES.md ## Capabilities and modes
- la promenade configure dans TASKS.md ## configure.
"Comment le rôle serveur de doca_flow_tune et le rôle client / consommateur s'intègrent-ils ensemble dans l'artefact unique ?" — exemple travaillé : "je n'arrête pas de lire sur un serveur Flow Tune et un client Flow Tune ; quel binaire j'exécute ?". Répondu par la décomposition un binaire, deux rôles dans CAPABILITIES.md ## Capabilities and modes et le routage correspondant dans TASKS.md ## configure.
"Comment appliquer un changement de paramètre recommandé de flow-tune dans mon application doca-flow sans casser le dataplane ?" — exemple travaillé : "l'étape analyze suggère un dimensionnement de table différent pour mon pipe ; comment l'appliquer ?". Répondu par la boucle recommendation → modification minimum-diff du programme Flow dans TASKS.md ## modify et la règle smoke-before-bulk dans TASKS.md ## test.
"doca_flow_tune ne rapporte rien / désaccord avec l'app Flow / ne peut pas attacher — qu'est-ce que ça signifie ?" — exemple travaillé : "l'outil s'exécute mais l'étape visualize produit un diagramme mermaid vide". Répondu par la taxonomie d'erreur par couches dans CAPABILITIES.md ## Error taxonomy
- TASKS.md ## debug.

Audience

Cette skill sert les opérateurs externes, ingénieurs de performance, développeurs d'applications DOCA Flow, et agents IA qui doivent comprendre, caractériser ou améliorer le comportement d'un pipeline doca-flow en cours d'exécution sur l'installation et l'appareil réels de l'utilisateur. Concrètement :

Un opérateur de plateforme exécutant un service doca-flow sur BlueField qui veut un snapshot en lecture seule des pipes qui existent et comment leurs compteurs matériels / logiciels progressent avant de recommander un changement.
Un ingénieur de performance qui a déjà un numéro de baseline doca-flow-perf et veut transformer la mesure en optimisation — choisissez un axe de tuning et identifiez quel bouton dans le programme doca-flow est le levier pour cela.
Un développeur d'application DOCA Flow qui veut la boucle offline analyze
- visualize pour comprendre un layout de pipe sans ré-instrumenter le programme Flow.
Un agent IA pilotant l'étape de triage "ce pipeline Flow se comporte-t-il comme prévu, et un hint de tuning non-mutant aiderait-il" avant de recommander tout changement de code au programme Flow.

Ce n'est pas pour les utilisateurs débogant le code source de doca_flow_tune, pas un substitut du guide public en direct DOCA Flow Tune sur docs.nvidia.com, pas le bon endroit pour apprendre l'API doca-flow (cette audience appartient à doca-flow), et pas le bon endroit pour la méthodologie de mesure de baseline — cela appartient à doca-flow-perf.

doca_flow_tune est livré comme un outil unique (un binaire plus ses scripts analyseur / visualiseur compagnons et modèles de config JSON) — les rôles historiques serveur et client vivent dans cet artefact unique, pas dans deux exécutables séparés. La skill utilise la même forme trois fichiers kind: tool que le reste du bundle pour que le contrat verbe-tâche de l'agent (configure / build / modify / run / test / debug) soit uniforme dans les bibliothèques, services et outils.

Périmètre du langage

Cette skill gouverne l'invocation, l'interprétation des sorties, et le routage recommendation-to-code-change pour l'application C / C++ DOCA Flow que doca_flow_tune observe. L'outil lui-même n'est pas une cible de programmation — il n'y a pas d'API publique que l'agent est censé lier ; ce que l'agent et l'utilisateur font avec l'outil est configurer JSON, exécuter, lire les sorties, proposer des changements minimum-diff au programme doca-flow environnant dans le langage propre du programme. Pour l'API doca-flow vers laquelle les recommandations routent, voir doca-flow CAPABILITIES.md ; pour les motifs d'application multi-langages, voir doca-programming-guide.

Quand charger cette skill

Chargez cette skill quand l'utilisateur est — ou l'agent doit — invoquer doca_flow_tune contre une application doca-flow en cours d'exécution ou prévue (sur hôte ou BlueField Arm, ou à l'intérieur du conteneur DOCA NGC public avec la saveur de trace-build Flow correspondante) pour caractériser, dumper, visualiser, analyser ou tuner ce pipeline. Concrètement :

Choisir quel rôle de doca_flow_tune engager (analyze / visualize offline sur une config + état capturés, dumper / monitor online contre l'app Flow en direct, ou utilisation du rôle serveur attach-to-app quand l'application Flow lie les points d'entrée du serveur tune documentés).
Choisir quel axe de tuning à poser (placement de règles, hints de ressources / dimensionnement de table, ou mode offload matériel) pour une charge de travail candidate.
Choisir quel axe de mesure comparer (taux d'installation de règles, latence lookup, delta de compteur matériel) — les trois ne sont pas interchangeables et l'axe choisi doit être le même qu'une baseline doca-flow-perf antérieure a nommé.
Capturer une paire documentée avant / après autour d'un changement proposé du programme Flow (le chemin du fichier config JSON documenté, la ligne de commande, la version DOCA, l'appareil, l'environnement déployé, la sortie complète non-redacté du dumper / analyzer / visualizer).
Diagnostiquer pourquoi une session tune a produit une sortie vide, une étape visualize a rendu un diagramme dégénéré, ou une recommandation analyze ne correspond pas à ce que les compteurs en direct disent.

Ne pas charger cette skill pour l'orientation générale DOCA, le travail d'API du programme Flow, l'installation ou la méthodologie de mesure pure. Pour ceux-ci, routez vers doca-public-knowledge-map, doca-flow, doca-setup, ou doca-flow-perf.

Ce que cette skill fournit

Ceci est un thin loader. La matière substantive vit dans deux fichiers compagnons :

CAPABILITIES.md — ce que doca_flow_tune observe et recommande : la décomposition d'artefact unifié (rôle serveur
- rôle client / consommateur dans un binaire), le modèle de configuration trois axes (axe de tuning × mesure × périmètre : quel pipe / port / app), les modes offline / online / attach documentés, la forme fichier de configuration JSON (le modèle public livré flow_tune_cfg_public.json plus ses variantes hardware-only et software-only), les surfaces de sortie dumper / monitor / analyze / visualize, l'overlay de version (cet outil monte la version de la bibliothèque doca-flow qu'il observe ; les règles canoniques vivent dans doca-version), la taxonomie d'erreur par couches (config-syntax / attach-failed / pipe-not-found / measurement-unsound / recommendation-unactionable / version / cross-cutting), la posture d'observabilité (l'outil est une primitive d'observabilité pour le pipeline Flow), et la politique de sécurité qui rend toute application mutante d'une recommandation à enjeu élevé car la recommandation atterrit dans l'état Flow en direct.
TASKS.md — workflows étape par étape pour les verbes de tâches en périmètre : install (routez vers setup ; le binaire est livré), configure (la décision trois axes + config JSON + choix mode), build (routez vers install ; le binaire est livré), modify (appliquez une recommandation au programme Flow via minimum-diff), run (le flux snapshot → analyze → visualize), test (la boucle eval — warm-up, steady-state, paire avant / après, correspondance client / serveur / version Flow), debug (parcourez la taxonomie d'erreur couche par couche), use (le workflow côté agent pour consommer la sortie flow-tune), plus un bloc Deferred task verbs et un Command appendix.

La skill suppose un hôte où DOCA est déjà installé (ou le conteneur DOCA NGC public est en cours d'exécution) et une application doca-flow est déjà créée et validée selon la skill doca-flow. Sans ces préconditions, la session de tune n'a rien à observer.

Ce que cette skill ne livre délibérément pas

Cette skill est un agent guidance, pas un bundle de samples ou scripts. Pour garder la limite claire, elle ne contient délibérément pas — et les pull requests ne doivent pas ajouter :

Inventaires de flags verbatim, noms de sous-commandes, noms de champs config JSON, ou chemins de points d'extrémité par défaut cités comme le contrat. Le guide public DOCA Flow Tune sur docs.nvidia.com (accessible via doca-public-knowledge-map ## DOCA tools) et le --help installé sur la version de l'utilisateur sont la source de vérité commune ; les modèles flow_tune_cfg*.json livrés sur l'installation de l'utilisateur sont la deuxième source pour le schéma JSON. Les copier ici épingle la skill à une release et pourrit silencieusement quand l'outil évolue.
Sortie d'exemple précuite (colonnes CSV dumper, noms de champs JSON analyzer, sortie mermaid visualizer). La sortie est install-, appareil-, firmware-, NUMA-, pipe Flow-, et version DOCA-spécifique ; un exemple capturé épinglé à une plateforme induit les opérateurs en erreur sur une plateforme / version différente.
Wrappers, parseurs, ou scripts dans aucun langage qui consomment la sortie flow-tune. Les formats de sortie sont documentés et le répertoire scripts/ livré sur l'installation de l'utilisateur contient des aides fournisseur (par ex. flow_json_diff.py, flow_mermaid_diff.py, hw_counters_csv_analyzer.py) ; si un utilisateur veut scripter contre les sorties, la bonne réponse est "lisez les scripts livrés sur votre version installée".
Recommandations de tuning précuites. Les recommandations de cet outil sont install-, appareil-, firmware-, et workload-spécifiques ; en livrer une pour "pipes hairpin" ou "pipes NAT" induit les opérateurs en erreur en l'appliquant à un pipe différent. L'agent réhérite toujours la recommandation depuis la session réelle de l'utilisateur.
Un sous-arbre samples/, templates/, ou reference/. Les recettes de tuning mockées ou incomplètes dans l'arbre de cette skill sont trompeuses ; les opérateurs les lisent comme production-grade.

Ordre de chargement

Lisez d'abord ce SKILL.md pour confirmer que la question de l'utilisateur est en périmètre (l'utilisateur veut réellement invoquer doca_flow_tune contre un pipeline doca-flow, pas mesurer la perf baseline ou apprendre l'API Flow).
Pour ce que doca_flow_tune observe, la décomposition binaire unique / deux rôles, le modèle trois axes, l'overlay de version, la taxonomie d'erreur, la surface d'observabilité et la posture de sécurité, voir CAPABILITIES.md.
Pour les invocations documentées et le workflow snapshot → analyze → visualize → propose → smoke — install, configure, build, modify, run, test, debug, use — voir TASKS.md.

Skills connexes

doca-flow — la bibliothèque de base dont ce pipeline de cet outil observe et tune. La surface pipe / entry / rule que flow-tune rapporte est créée par le code du programme doca-flow ; les recommandations routent au programme via le workflow universel modify-a-sample.
doca-flow-perf — l'outil mesure frère. La règle est : doca-flow-perf mesure les baselines ; doca-flow-tune recommande les optimisations au-dessus. Un agent qui recourt au tune sans un numéro de baseline depuis perf optimise dans l'obscurité ; un agent qui recourt à perf sans une question benchmarque pour le plaisir.
doca-flow-dpa-perf — la variante DPA-offloadée de Flow perf. Pertinent quand le pipeline Flow que l'utilisateur tune s'exécute via un chemin d'offload DPA ; la baseline vient de là, pas du doca-flow-perf côté hôte.
doca-flow-grpc-server — la surface gRPC de contrôle à distance pour doca-flow. La gestion programmée de règles Flow vit là ; les recommandations de flow-tune peuvent être appliquées via cette surface quand le plan de contrôle de l'opérateur est distant.
doca-public-knowledge-map — routage vers la page publique DOCA Flow Tune sur docs.nvidia.com et le reste du corpus de documentation DOCA public.
doca-version — la chaîne de détection de version canonique, correspondance quatre voies, sémantique NGC, et règle headers-win-over-docs. L'overlay ## Version compatibility dans cette skill est une fine extension au-dessus.
doca-debug — l'échelle debug cross-cutting. Flow-tune expose sa propre taxonomie d'erreur ; quand la cause s'avère être en dessous de DOCA (driver, firmware, NUMA), la taxonomie tune remet à doca-debug.
doca-structured-tools-contract — le contrat du bundle detect → prefer → fall back → report. L'appendix Command dans TASKS.md l'honore.
doca-setup — préparation env, vérification d'installation, hugepages, NUMA, et le chemin je n'ai pas encore d'installation avec le conteneur DOCA NGC public.
doca-hardware-safety — la méta-politique hardware-safety cross-cutting que le ## Safety policy de cette skill overlaye.

DOCA Flow Tune (doca_flow_tune)