Traceur DPA DOCA haut niveau

Par où commencer : C'est une compétence d'outil pour invoquer doca_dpa_hl_tracer — l'interface de ligne de commande côté hôte documentée qui capture les traces d'exécution côté DPA en termes haut niveau (événements de programmation DPA : entrée/sortie du kernel, points de synchronisation, appels de primitives de communication, soumission d'écritures RDMA, complétions) plutôt que des décomptes de cycles bruts. Ouvrez TASKS.md et commencez à ## configure pour la décision mode-vs-surcharge et la disposition de la config JSON, puis ## run pour le pipeline capture → décode → rendu. Ouvrez CAPABILITIES.md quand la question porte sur ce que cet outil trace réellement, quels événements de programmation DPA il expose, quel est le compromis surcharge-de-trace vs fidélité, ou comment s'intègre-t-il dans une boucle de debug DPA aux côtés de doca-dpa et doca-debug. Si DPA n'est pas la bonne surface pour la question de l'utilisateur (par ex. le bug est côté hôte, le bug est dans l'image produite par DPACC, l'utilisateur veut des décomptes de cycles bruts), la règle de sélection de chemin dans CAPABILITIES.md ## Capabilities and modes oriente l'agent avant toute tentative de capture.

Exemples de questions auxquelles cette compétence répond bien

Les CLASSES de questions sur doca_dpa_hl_tracer auxquelles cette compétence est construite pour répondre, chacune avec un exemple travaillé. La classe est l'élément porteur ; l'exemple travaillé en est une instance.

« Mon kernel DPA fait le mauvais truc — où dois-je regarder ? » — exemple travaillé : « mon `doca_dpa_kernel_launchupdatecôté hôte se termine, mais le résultat rapporté par le kernel est faux ; aucuneDOCAERROR` côté hôte ». Répondu par la porte quand le tracing haut niveau côté DPA est la bonne surface dans CAPABILITIES.md ## Capabilities and modes

le flux capture → décode → rendu dans TASKS.md ## run + la règle sur quels événements de programmation DPA se concentrer dans TASKS.md ## debug.

« Mon kernel DPA est lent à une granularité qui n'apparaît pas dans les profils de cycles — comment puis-je voir la latence entrée-du-kernel à premier-appel-de-comm ? » — exemple travaillé : « mon kernel DPA s'exécute mais le temps entre le lancement et la première soumission d'écriture RDMA est plus grand que prévu ». Répondu par le tableau de taxonomie d'événements dans CAPABILITIES.md ## Capabilities and modes

la boucle itérative dans TASKS.md ## test qui traite la surcharge de trace, le mode (TRACE vs CRIT), et la fenêtre de capture comme des axes à affiner.

« Comment puis-je capturer une trace sans submerger la DPA de surcharge d'observation ? » — exemple travaillé : « le mode TRACE produit trop de données et ma latence DPA mesurée a augmenté de 2x par rapport à sans le traceur ». Répondu par le compromis mode-vs-surcharge dans CAPABILITIES.md ## Capabilities and modes

les conseils CRIT-en-premier dans TASKS.md ## configure (commencez avec les événements critiques uniquement ; élargissez à TRACE seulement quand le bug exige du détail par événement).

« Mon fichier de trace a été tronqué en cours d'exécution — comment dois-je configurer les limites de taille de fichier ? » — exemple travaillé : « le fichier de trace binaire a atteint 5 Go et la capture s'est arrêtée ». Répondu par le triple log_file_max_size_in_bytes / bin_file_max_size_in_bytes / file_size_limit_policy dans CAPABILITIES.md ## Capabilities and modes

la disposition de la config JSON dans TASKS.md ## configure.

« Le traceur est-il sur mon installation, et est-il associé à la version correspondante de la bibliothèque doca-dpa et du compilateur DPACC ? » — exemple travaillé : « l'ABI du traceur sur mon installation est-il compatible avec l'image DPA produite par mon DPACC ? ». Répondu par la surimpression de version dans CAPABILITIES.md ## Version compatibility, qui redirige vers la chaîne canonique doca-version et ajoute la règle de correspondance traceur ↔ bibliothèque doca-dpa ↔ compilateur DPACC.
« Le fichier de capture semble vide / le décode a échoué — l'installation est-elle cassée, aucun événement ne s'est produit, ou est-ce que je trace le mauvais truc ? » — exemple travaillé : « doca_dpa_hl_tracer s'est exécuté, a écrit un fichier, mais l'analyseur affiche zéro événements ». Répondu par la taxonomie d'erreur en couches dans CAPABILITIES.md ## Error taxonomy (installation / liaison-de-périphérique / image-DPA-instrumentée / fenêtre-de-capture / décode-vs-elf / surcharge-saturée / version / transversale) + la marche en couches dans TASKS.md ## debug.

Audience

Cette compétence sert les développeurs externes, opérateurs de plateforme, et agents IA qui ont déjà lancé une charge de travail côté DPA via doca-dpa et ont maintenant besoin d'une visibilité haut niveau sur ce que le kernel DPA fait réellement sur le fil — ordonnancement des événements de programmation DPA, lacunes de synchronisation, latences d'appels de communication, timing soumission/complétude d'écritures RDMA — sans descendre jusqu'aux décomptes de cycles bruts. Concrètement :

Un développeur DPA qui peut lancer son kernel proprement depuis le côté hôte mais dont le résultat du kernel est faux ou dont la performance côté DPA est inférieure à l'attente, et qui a besoin d'une vérité de terrain côté DPA avant diagnostic.
Un opérateur de plateforme exécutant une charge de travail utilisant DPA (déchargement RDMA depuis l'accélérateur, algorithme CC personnalisé via doca-pcc) et doit localiser une régression côté DPA sans instrumenter l'application.
Un agent IA produisant un rapport de trace côté DPA comme preuve pour l'échelle doca-dpa TASKS.md ## debug côté hôte quand le côté hôte signale des complétions propres mais le comportement côté DPA est faux.

Ce n'est pas pour les utilisateurs debuggant le binaire du traceur lui-même, pas un substitut au guide DOCA DPA Tools public en direct, pas le bon endroit pour les utilisateurs apprenant à écrire un kernel DPA (cette audience appartient à doca-dpa plus les guides publics DOCA DPA / DPACC / DPA-Comms / DPA-Verbs), et pas le bon endroit pour le profilage de cycles brut par instruction (surface différente, outil différent — router via doca-public-knowledge-map ## DOCA tools).

Le traceur est livré en tant que binaire CLI sous /opt/mellanox/doca/tools/, pas une bibliothèque que vous liez. La compétence utilise la même forme trois-fichiers kind: tool que le reste du bundle de façon que le contrat tâche-verbe de l'agent soit uniforme entre bibliothèques, services et outils.

Portée du langage

doca_dpa_hl_tracer est un CLI côté hôte C++. Ses entrées sont son fichier config JSON, l'ELF côté DPA (l' image de classe doca_dpa_app produite par DPACC), et une charge de travail côté DPA en cours d'exécution que le cycle de vie côté hôte doca-dpa a déjà lancé. Ses sorties sont un fichier de trace binaire (bin_file) et un fichier de log lisible par l'humain (log_file). La compétence conserve le langage de guidance du workflow indépendant du langage — la charge de travail côté DPA qu'elle trace peut être compilée en C par DPACC ou tout autre unité de traduction DPA que DPACC accepte — et route les questions par langage vers les guides DPA / DPACC publics via doca-public-knowledge-map.

Quand charger cette compétence

Chargez cette compétence quand l'utilisateur est — ou l'agent doit — invoquer doca_dpa_hl_tracer sur un vrai hôte avec DOCA installé contre un BlueField avec un processeur DPA visible depuis l'hôte, et le cycle de vie côté hôte doca-dpa a déjà lancé une charge de travail DPA au moins une fois. Concrètement :

Capturer une trace côté DPA pour localiser un comportement mauvais-résultat ou mauvais-ordonnancement du kernel DPA quand le cycle de vie côté hôte doca-dpa rapporte des complétions propres.
Capturer une trace côté DPA pour localiser une lacune de performance côté DPA (latence entrée-du-kernel à première-comm, écart soumission-RDMA-à-complétude, temps de dwell du point de synchronisation) à une granularité au-dessus des décomptes de cycles bruts.
Choisir entre les modes de capture TRACE et CRIT basé sur le compromis bug-vs-surcharge et la fenêtre de capture disponible.
Affiner la config JSON (priorités de thread, affinités de cœur, limites de taille de fichier, politique limite-de-taille-de-fichier) pour que la capture elle-même ne perturbe pas la charge de travail plus que le bug qu'elle enquête.
Décoder un bin_file capturé contre l'ELF côté DPA correspondant pour rendu le flux d'événements lisible par l'humain.
Capturer une trace bornée en effets secondaires comme preuve prérequise pour une étape d'échelle doca-dpa TASKS.md ## debug côté hôte.

Ne chargez pas cette compétence pour l'orientation générale de DOCA, les questions du modèle de programmation côté DPA, le profilage de cycles bruts, ou l'installation de DOCA / DPACC. Pour celles-ci, router vers doca-public-knowledge-map, doca-dpa, ou doca-setup.

Ce que cette compétence fournit

Ceci est un chargeur mince. Le matériel substantiel vit dans deux fichiers compagnons :

CAPABILITIES.md — ce que doca_dpa_hl_tracer capture : la taxonomie d'événements de programmation DPA (entrée/sortie du kernel, points de synchronisation, appels de primitives de communication, soumission et dépôt d'écriture RDMA), les deux modes de capture documentés (TRACE pour la pleine par-événement, CRIT pour événements-critiques-seulement), le compromis surcharge-de-trace-vs-fidélité, la forme du fichier config (threads récepteur / writer-binaire / writer-fichier / printer avec priorité + affinité de cœur, limites de taille de fichier, file_size_limit_policy), l'invariant fenêtre-de-capture + charge-de-travail-doit-être-en-cours, la règle ELF-doit-correspondre-à-l'image pour le décode, la surimpression disponibilité-de-version (traceur ↔ bibliothèque doca-dpa ↔ compilateur DPACC), la taxonomie d'erreur en couches (installation / liaison-de-périphérique / image-instrumentée / fenêtre-de-capture / décode / surcharge-saturée / version / transversale), la surface d'observabilité (fichier de trace binaire + fichier de log + stderr de l'outil), et la politique de sécurité (la capture est bornée ; le tracing n'est pas une surface d'observabilité de production).
TASKS.md — workflows pas-à-pas pour les verbes de tâche in-scope : install (router vers installation DOCA côté hôte + prérequis DPA), configure (mode + disposition config JSON + fenêtre de capture), build (router vers install — le binaire est livré, l'application côté DPA est construite par l'utilisateur avec DPACC), modify (refuser — ne patchez pas le binaire ; modifiez la config JSON et l'invocation à la place), run (le flux de capture avec --mode, --config-file, --output-file), test (boucle itérative affinage mode, fenêtre, et surcharge), debug (parcourir la taxonomie d'erreur), use (consommer la trace décodée dans une session de debug doca-dpa), plus un bloc Deferred task verbs.

La compétence suppose un hôte où DOCA est déjà installé à l'emplacement standard, un BlueField avec un processeur DPA est présent et visible depuis l'hôte, le compilateur DPACC est installé à une version correspondant au DOCA côté hôte, l'image d'application côté DPA (l'ELF contre lequel le traceur décode) est sur disque et correspond à ce que le cycle de vie doca-dpa a chargé, et l'opérateur a les privilèges que le guide DOCA DPA Tools public exige.

Ce que cette compétence ne livre délibérément pas

Cette compétence est une guidance d'agent, pas un bundle d'exemples ou de scripts. Pour garder la frontière propre, elle ne contient délibérément pas — et les pull requests ne devraient pas ajouter :

Chaînes de flag spécifiques, noms d'événements, ou tokens de mode au-delà de ce que la page DOCA DPA Tools publique et --help documentent. La surface des événements de programmation DPA évolue version après version ; --help sur le binaire installé est l'inventaire faisant autorité.
Traces d'exemple pré-cuites ou timings d'événements attendus. La sortie de trace est spécifique à la charge de travail, à l'image DPA, au BlueField, et au firmware ; un exemple capturé épinglé à une setup en trompe les opérateurs ailleurs.
Wrappers, parseurs, ou scripts de rendu dans n'importe quel langage qui consomment le format de trace binaire. Le format est documenté ; les utilisateurs qui veulent scripter contre lui devraient lire le guide en direct et écrire le parseur contre leur version installée.
Une recommandation d'affinage spécifique dérivée d'une seule trace. Une décision perf côté DPA (déplacer une synchronisation, regrouper un appel comm, changer un argument de lancement) est une question de charge de travail et la compétence prescrit comment capturer et lire les traces — elle refuse de traduire une lacune capturée en une recommandation de réécriture de kernel sans l'analyse propre de l'utilisateur.
Un sous-arbre samples/ ou reference/. Ceci est un chargeur mince pour un CLI livré ; le matériel substantiel vit sur la page publique, dans --help, et dans doca-dpa.

Ordre de chargement

Lisez d'abord ce SKILL.md pour confirmer que la question de l'utilisateur est in-scope (tracing haut niveau côté DPA, pas programmation côté DPA et pas profilage de cycles bruts).
Pour la taxonomie d'événements, modes de capture, compromis surcharge, disposition config JSON, surimpression de version, taxonomie d'erreur, observabilité, et politique de sécurité, voir CAPABILITIES.md.
Pour les invocations documentées et le workflow capture → décode → rendu — install, configure, build, modify, run, test, debug, use — voir TASKS.md.

Compétences connexes

doca-dpa — la bibliothèque de contrôle DPA côté hôte dont l'image d'application chargée est tracée par le traceur. Associez-les dans chaque session de debug DPA : doca-dpa lance la charge de travail ; le traceur capture ce que la charge de travail fait au niveau de la couche événement de programmation DPA. Confondre la bibliothèque avec le traceur est l' erreur de premier contact debug-DPA la plus courante.
doca-debug — l'échelle de debug transversale. Le traceur s'insère à la couche runtime comme la vérité de terrain côté DPA avant toute conclusion perf ou correction côté DPA.
doca-public-knowledge-map — routing vers la page DOCA DPA Tools publique sur docs.nvidia.com et le reste de l'ensemble de documentation DOCA publique.
doca-version — règles canoniques de gestion de version DOCA. La section ## Version compatibility dans CAPABILITIES.md est une surimpression concise qui redirige ici pour le corps et ajoute la règle de correspondance traceur ↔ bibliothèque doca-dpa ↔ compilateur DPACC.
doca-setup — préparation env, vérification install, install/vérification compilateur DPACC, mode BlueField (le processeur DPA doit être exposé avant que tout tracing soit significatif), et le chemin je n'ai pas encore d'install avec le conteneur DOCA NGC public.
doca-structured-tools-contract — le contrat du bundle detect → prefer → fall back → report pour les outils helper structurés. L'appendice de commande dans TASKS.md honore ce contrat.
doca-programming-guide — motifs généraux de programmation DOCA partagés par chaque surface bibliothèque / outil, incluant la taxonomie DOCA_ERROR_* inter-bibliothèques que la couche d'erreur côté hôte de cet outil surimpose quand les appels doca-dpa côté hôte échouent en tandem.

Les bibliothèques compagnon côté DPA doca-dpa-comms (primitives comm qu'appelle le kernel DPA lui-même) et doca-dpa-verbs (verbes RDMA qu'appelle le kernel DPA lui-même) sont des artefacts différents que la surface événements de programmation DPA du traceur nomme visiblement ; pour le modèle de programmation côté DPA lui-même, router via doca-public-knowledge-map vers les guides publics DOCA DPA-Comms et DPA-Verbs et vers les exemples livrés /opt/mellanox/doca/samples/doca_dpa/. Cet outil trace leur usage ; il ne les redéfinit pas.

doca-dpa-hl-tracer