Utilitaires de Telemetry DOCA

Par où commencer : Ceci est une tool skill pour invoquer doca_telemetry_utils — la CLI côté hôte documentée qui supporte un pipeline exportateur/collecteur DOCA Telemetry en découvrant le schéma des compteurs, en traduisant les noms de compteurs ↔ Data IDs, et en sondant le support des compteurs par appareil. Ouvrez TASKS.md et commencez à ## install pour les prérequis côté hôte et ## run pour les trois classes d'invocation documentées (enumerate / name→ID / ID→name). Ouvrez CAPABILITIES.md quand la question est ce que cet outil découvre réellement sur le schéma de telemetry, comment s'associe-t-il avec le doca-telemetry côté développeur et les bibliothèques d'exportateur, comment confirmer qu'un appareil supporte un compteur avant de valider une config d'exportateur sur celui-ci, ou pourquoi mon pipeline d'exportateur supprime silencieusement une métrique.

Cette skill est l'outil de support côté opérateur pour un déploiement DOCA Telemetry. Ce n'est PAS la bibliothèque collecteur côté développeur (c'est doca-telemetry), PAS la bibliothèque éditeur côté développeur (c'est doca-telemetry-exporter — voir doca-telemetry ## Related skills), et PAS un guide de déploiement DOCA Telemetry Service (DTS) (routez via doca-public-knowledge-map). Trois surfaces distinctes ; les confondre est l'erreur de première approche telemetry la plus courante.

Exemples de questions que cette skill répond bien

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

« Mon exportateur dit qu'il émet port_rx_bytes mais rien ne remonte en aval — qu'ai-je mal fait ? » — exemple travaillé : « ma config d'exportateur a une chaîne de nom de compteur et mon collecteur ne voit aucun événement avec ce nom ». Répondu par l'étape de traduction name ↔ Data ID dans CAPABILITIES.md ## Capabilities and modes
- le sondage de support par appareil dans TASKS.md ## test : l'exportateur expédie un Data ID, pas un nom ; un nom dans la config qui se résout à un Data ID que l'appareil ne supporte pas est silencieusement supprimé.
« Quels compteurs de diagnostic DOCA expose réellement ce BlueField ? » — exemple travaillé : « énumérez le schéma complet des compteurs pour mon BlueField-3 avant d'écrire la config d'exportateur ». Répondu par la classe d'invocation de découverte de schéma dans CAPABILITIES.md ## Capabilities and modes (doca_telemetry_utils get-counters énumère chaque nom de compteur que la surface de données de diagnostic connaît ; associez avec un sondage par appareil pour confirmer le support).
« J'ai un Data ID dans un log capturé — quel compteur était-ce ? » — exemple travaillé : « un consommateur en aval a émis Data ID: 0x1160000600030201 — traduisez-le en retour pour que je puisse le corréler contre le guide public ». Répondu par la classe d'invocation reverse-resolve dans CAPABILITIES.md ## Capabilities and modes
- la règle ID-encodes-properties dans TASKS.md ## use (un Data ID porte les dimensions de propriétés du compteur ; le reverse-resolve les signale).
« Quelles dimensions de propriétés ce compteur prend et quelles valeurs sont valides ? » — exemple travaillé : « je sais que le compteur est `pcie_link_write_stalledtime — que signifientnode/pcie_index/depthet quelles valeurs l'appareil accepte-t-il ? »*. Répondu par la table de dimensions de propriétés dans [CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
- l'invocation <name> sans arguments qui affiche les options de propriétés documentées + unités + axes spécifiques à l'unité.
« Ce compteur est-il supporté sur cet appareil avant que je le valide dans la config d'exportateur ? » — exemple travaillé : « validez que port_rx_bytes avec node=1 est exposé sur le BlueField à l'adresse PCIe X avant que j'écrive la config d'exportateur ». Répondu par le sondage de support par appareil (<device PCI> <name> [properties]) dans CAPABILITIES.md ## Capabilities and modes
- la règle gate-before-commit dans TASKS.md ## use.
« doca_telemetry_utils est-il sur mon installation, et est-il associé à la version de bibliothèque doca-telemetry correspondante ? » — exemple travaillé : « l'ensemble de compteurs de données de diagnostic que mon exportateur cible est-il sur cette version DOCA ? ». Répondu par le version-overlay dans CAPABILITIES.md ## Version compatibility, qui redirige vers la chaîne doca-version canonique et ajoute la règle de correspondance tool ↔ schéma-version de bibliothèque doca-telemetry.

Audience

Cette skill sert les opérateurs externes, développeurs et agents IA mettant en place ou déboguant un pipeline exportateur/ collecteur DOCA Telemetry qui ont besoin de confirmer le schéma des compteurs, valider le support par appareil, ou traduire entre les noms de compteurs lisibles par l'homme et les Data IDs binaires que l'exportateur envoie réellement. Concrètement :

Un opérateur de plateforme mettant en place un nouvel exportateur DOCA Telemetry sur une flotte BlueField qui a besoin de confirmer quels compteurs les appareils cibles exposent réellement avant de valider la config d'exportateur.
Un développeur d'un consommateur en aval (une app collecteur liant doca-telemetry, ou un agrégateur tiers consommant via DTS) qui a un flux Data ID capturé et a besoin de traduire les IDs en retour en noms de compteurs + propriétés.
Un opérateur déboguant un rapport « rien n'est envoyé en aval » / « cette métrique manque silencieusement » contre un exportateur déployé — les sondages de découverte de schéma
- support par appareil sont l'étape de premier recours canonique « le compteur est-il même supposé fonctionner sur cet appareil » avant de suspecter le collecteur ou le chemin réseau.
Un agent IA produisant une réponse « config d'exportateur validée pour ce BlueField + cette version DOCA » honnêtement — avec chaque compteur résolu à son Data ID et chaque Data ID confirmé contre le sondage de capacité par appareil.

Ce n'est pas pour les utilisateurs déboguant le binaire doca_telemetry_utils lui-même, pas un substitut pour les guides DOCA Telemetry publics en direct, et pas le bon endroit pour apprendre à écrire une application d'exportateur (ce public appartient à la skill doca-telemetry-exporter quand présente, ou via doca-public-knowledge-map).

L'outil est fourni en tant que binaire CLI sous /opt/mellanox/doca/tools/, pas une bibliothèque contre laquelle vous liez. La skill utilise la même forme kind: tool à trois fichiers que le reste du bundle pour que le contrat task-verb de l'agent soit uniforme sur les bibliothèques, services et outils.

Portée du langage

doca_telemetry_utils est une CLI C côté hôte qui utilise la surface doca_telemetry_diag documentée pour énumérer les types de compteurs et sonder le support par appareil. Ses entrées sont des arguments de ligne de commande (nom de compteur, valeurs de propriétés, Data ID, adresse PCI optionnelle d'appareil) ; ses sorties sont des mappages Data ID + propriétés lisibles par l'homme. La skill garde le langage de guidance de flux de travail indépendant du langage ; les consommateurs en aval dans n'importe quel langage peuvent utiliser les Data IDs résolus contre leur propre code collecteur.

Quand charger cette skill

Chargez cette skill quand l'utilisateur est — ou l'agent a besoin — d'invoquer doca_telemetry_utils sur un vrai hôte avec DOCA installé, aux côtés d'un pipeline exportateur/ collecteur qui a besoin de découverte de schéma, validation de support par appareil, ou traduction de Data ID. Concrètement :

Énumérer le schéma complet des compteurs avant d'écrire une config d'exportateur DOCA Telemetry nouvelle (get-counters).
Valider qu'un compteur choisi + ensemble de propriétés se résout à un Data ID que l'appareil cible supporte réellement, avant de valider la config.
Reverse-resolver un Data ID capturé d'un consommateur en aval en retour à un nom de compteur + propriétés pour corrélation contre le guide public.
Déboguer un rapport « exportateur envoie, collecteur ne reçoit rien » (le mode de défaillance schéma-mismatch / compteur-non-supporté canonique).
Produire un artefact « ensemble de compteurs validés pour ce BlueField + cette version DOCA » en tant que partie d'une baseline de config d'exportateur structurée.
Migrer un pipeline d'exportateur sur les versions DOCA et confirmer que chaque compteur précédemment supporté se résout toujours proprement sur la nouvelle version.

Ne chargez pas cette skill pour l'orientation DOCA générale, programmation de bibliothèque collecteur/exportateur, déploiement DTS, ou installation DOCA. Pour ceux-ci, routez vers doca-public-knowledge-map, doca-telemetry, ou doca-setup.

Ce que cette skill fournit

Ceci est un thin loader. Le matériel substantiel vit dans deux fichiers compagnons :

CAPABILITIES.md — ce que doca_telemetry_utils découvre + comment il s'associe avec les surfaces côté développeur : les trois classes d'invocation documentées (enumerate / name→ID / ID→name), le modèle de dimensions de propriétés (les compteurs portent des axes de propriétés comme node, pcie_index, depth, plus des axes par-unité), le sondage de capacité par appareil optionnel (<device PCI> <name> lance le compteur résolu contre l'appareil), le rôle de support côté opérateur (ce n'est PAS la bibliothèque côté développeur ; il existe pour que les setups exportateur/collecteur soient honnêtes), l'overlay de version (appairage version schéma tool ↔ bibliothèque doca-telemetry), la taxonomie d'erreur en couches (install / parse / unknown-counter / unknown-data-id / property-out- of-range / device-not-supported / version / cross-cutting), la surface d'observabilité (stdout-only), et la politique de sécurité (l'outil est en lecture seule ; les erreurs apparaissent en aval comme suppressions de métrique silencieuses, pas crashes).
TASKS.md — flux de travail pas à pas pour les verbes de tâche dans scope : install (DOCA côté hôte + prérequis de composant telemetry), configure (décisions d'axes : quelle classe d'invocation, quel appareil, quel compteur), build (route vers install — le binaire est fourni), modify (refuser — ne patchez pas le binaire ; modifiez l'invocation et la config d'exportateur/collecteur qui consomme les Data IDs résolus), run (les trois invocations documentées), test (round-trip un compteur choisi à travers name → Data ID → sondage par appareil → config d'exportateur → réception du collecteur), debug (parcourez la taxonomie d'erreur), use (le hand-off dans le pipeline collecteur/exportateur doca-telemetry côté développeur), plus un bloc Deferred task verbs.

La skill suppose un hôte où DOCA est déjà installé avec le composant telemetry, un BlueField que l'opérateur cible est visible pour DOCA, et le pipeline exportateur/collecteur qui consomme les Data IDs résolus est soit en cours de création, soit déjà créé contre la version de bibliothèque doca-telemetry correspondante.

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

Cette skill 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 doivent pas ajouter :

Un inventaire de compteurs verbatim ou une table Data ID. L'ensemble de compteurs évolue sur les versions DOCA et les générations BlueField ; un inventaire épinglé dans cette skill pourrirait silencieusement. doca_telemetry_utils get-counters sur le binaire installé est la source faisant autorité.
Des configs d'exportateur/collecteur pré-cuites. Les configs sont install-, appareil-, et use-case-spécifiques ; une config emballée dans cette skill induirait les opérateurs en erreur sur un setup différent.
Une recette de déploiement DTS. DTS est un service DOCA distinct avec son propre guide public ; routez via doca-public-knowledge-map. Cette skill résout les noms de compteurs + IDs qu'un pipeline DTS consomme ; elle ne configure pas DTS.
Des wrappers, parseurs, ou scripts dans n'importe quel langage qui consomment la sortie de l'outil. La sortie est un mapping texte simple ; les utilisateurs qui veulent scripter contre celle-ci devraient lire le guide en direct et écrire le parseur contre leur version installée.
Un sous-arbre samples/ ou reference/. Ceci est un thin loader pour une CLI fournie ; le matériel substantiel vit sur la page publique, dans --help, et dans doca-telemetry.

Ordre de chargement

Lisez d'abord ce SKILL.md pour confirmer que la question de l'utilisateur est dans scope (tooling de support côté opérateur pour un pipeline telemetry, pas la programmation de bibliothèque côté développeur).
Pour les trois classes d'invocation, le modèle de dimensions de propriétés, le sondage de support par appareil, l'overlay de version, la taxonomie d'erreur, la surface d'observabilité, et la politique de sécurité, voir CAPABILITIES.md.
Pour les invocations documentées et le flux de travail discover → resolve → validate → consume — install, configure, build, modify, run, test, debug, use — voir TASKS.md.

Skills liées

doca-telemetry — la bibliothèque collecteur côté développeur dont le schéma cet outil aide l'opérateur à découvrir. Associez-les dans chaque session de triage de pipeline d'exportateur. La skill de bibliothèque collecteur enseigne la règle collector-vs-exporter, le contrat schema-must-match avec l'éditeur, et la règle de back-pressure consumer-queue-full ; le rôle de cet outil est de rendre la moitié schéma de ce contrat inspectable du côté opérateur. Confondre la bibliothèque et l'outil est l'erreur de première approche telemetry la plus courante.
doca-public-knowledge-map — routage vers le guide public DOCA Telemetry et la page DOCA Telemetry Service (DTS) sur docs.nvidia.com, plus la mise en page d'installation sur disque pour l'outil.
doca-version — règles de gestion de version DOCA canoniques. La section ## Version compatibility dans CAPABILITIES.md est un overlay concis qui redirige ici pour le corps et ajoute la règle d'appairage tool ↔ schéma-version de bibliothèque doca-telemetry.
doca-setup — préparation d'environnement, vérification d'installation, et le chemin je n'ai encore aucune installation avec le conteneur NGC DOCA public. Cette skill suppose que ses préconditions sont satisfaites (DOCA installé avec le composant telemetry, BlueField visible pour DOCA).
doca-debug — l'échelle de débogage cross-cutting. Telemetry-utils alimente l'échelle cross-cutting en exposant la vérité de schéma de compteurs + support par appareil au niveau de la couche runtime ; les régressions de pipeline d'exportateur se résolvent souvent à la couche schéma avant de toucher le chemin collecteur/réseau.
doca-structured-tools-contract — le contrat detect → prefer → fall back → report du bundle pour les outils helper structurés. L'appendice de commandes dans TASKS.md honore ce contrat.
doca-programming-guide — patterns de programmation DOCA généraux partagés par chaque surface de bibliothèque/outil, y compris la taxonomie DOCA_ERROR_* cross-library que la couche d'erreur côté hôte de cet outil met en overlay en haut quand le code collecteur/ exportateur en aval expose une erreur liée.

doca-telemetry-utils