Exporteur de Télémétrie DOCA

Par où commencer : Cette compétence suppose que DOCA est déjà installé et que l'utilisateur travaille directement sur l'exporteur de télémétrie — émettant une télémétrie d'application structurée (compteurs / événements) depuis un programme utilisant DOCA vers un consommateur externe. Ouvrez TASKS.md si l'utilisateur veut faire quelque chose (configurer / construire / modifier / exécuter / tester / déboguer) ; ouvrez CAPABILITIES.md quand la question porte sur ce que l'exporteur peut exprimer sur cette installation. Si l'utilisateur n'a pas encore installé DOCA, orientez-le d'abord vers doca-setup. Si l'utilisateur hésite entre cette bibliothèque et le Service de Télémétrie DOCA (le récepteur) — lisez la règle exporteur-vs-service dans CAPABILITIES.md ## Capabilities and modes avant de configurer quoi que ce soit.

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

Les CLASSES de questions sur l'exporteur de télémétrie que cette compétence est construite pour répondre, chacune avec un exemple travaillé. L'agent devrait traiter la classe comme l'élément porteur — l'exemple travaillé est une instance unique.

« Quelle bibliothèque veux-je — l'exporteur ou le service de télémétrie ? » — exemple travaillé : « Je veux que mon programme DOCA Flow publie un compteur de paquets traités par seconde vers un collecteur en aval — quel artefact DOCA dois-je lier ? ». Répondu par la règle exporteur-vs-service dans CAPABILITIES.md ## Capabilities and modes tableau de répartition des rôles + la puce de sélection du chemin, qui nomment tous deux doca-telemetry-exporter comme l'éditeur auquel l'application se lie et acheminent le côté réception / consommation loin de cette compétence.
« Comment émets-je mon premier événement structuré depuis un programme DOCA ? » — exemple travaillé : « émettre un seul compteur d'événement packets_processed par seconde depuis mon application DOCA Flow ». Répondu par le cycle de vie schema-register-before-emit dans CAPABILITIES.md ## Capabilities and modes tableau d'objets + le flux de travail dans TASKS.md ## configure + TASKS.md ## run étape 3 (smoke d'un seul événement avant en masse).
« Mon appel d'émission d'événement retourne DOCA_ERROR_AGAIN sous charge — dois-je relancer ? » — exemple travaillé : « ma boucle d'émission à débit élevé commence à retourner AGAIN une fois que le consommateur en aval prend du retard — dois-je attendre et relancer ? ». Répondu par l'invariant de suppression-pas-blocage du chemin chaud dans CAPABILITIES.md ## Safety policy + la ligne AGAIN dans CAPABILITIES.md ## Error taxonomy : la réponse correcte de l'application est de supprimer l'événement (ou de mettre en buffer borné) — ne jamais bloquer le chemin de données sur la télémétrie.
« Mon émission retourne DOCA_ERROR_NOT_FOUND — qu'ai-je oublié ? » — exemple travaillé : « doca_telemetry_exporter_source_report retourne NOT_FOUND au tout premier appel ». Répondu par la ligne NOT_FOUND dans CAPABILITIES.md ## Error taxonomy (le schéma pour ce type d'événement n'a jamais été enregistré contre cette source) + l'ordre du cycle de vie dans TASKS.md ## configure (enregistrez les schémas AVANT le premier émission).
« Mon programme émet, mais le consommateur ne voit rien — par où commencer ? » — exemple travaillé : « l'émission retourne un succès, mais le journal du collecteur sur le même hôte est vide ». Répondu par la règle consumer-must-be-up-first dans CAPABILITIES.md ## Safety policy matrice de permissions + la boucle smoke-before-bulk dans TASKS.md ## test (un événement de bout en bout avec réception confirmée par le consommateur AVANT tout émission en masse).
*« `doca_telemetryexporterest-il sur mon DOCA installé, et le type d'événement que je veux est-il supporté ici ? »** — exemple travaillé : *« le type gauge est-il sur DOCA 3.3 par rapport à mon installation ? »*. Répondu par la surcouche de compatibilité des versions dans [CAPABILITIES.md ## Version compatibility](CAPABILITIES.md#version-compatibility), qui fait des renvois croisés vers la chaîne de détection canonique dans [doca-version](../../doca-version/SKILL.md), plus la règle capability-query dans [CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes).

Audience

Cette compétence sert les développeurs externes construisant des applications qui émettent une télémétrie structurée via l'Exporteur de Télémétrie DOCA — c'est-à-dire les utilisateurs dont le code d'application appelle doca_telemetry_exporter_* (directement en C/C++, ou via FFI/bindings depuis un autre langage) pour publier des compteurs, des jauges et des événements depuis leur programme utilisant DOCA vers un consommateur de télémétrie externe. Ce n'est pas pour les développeurs NVIDIA contribuant à l'Exporteur de Télémétrie DOCA lui-même, et ce n'est pas pour les utilisateurs construisant le service de télémétrie récepteur / agrégateur (le Service de Télémétrie DOCA est un service DOCA séparé avec son propre guide public, accessible via doca-public-knowledge-map).

Portée linguistique. L'Exporteur de Télémétrie DOCA est fourni en tant que bibliothèque C avec le nom du module pkg-config doca-telemetry-exporter. Les exemples fournis sont écrits en C. Les consommateurs C et C++ sont le cas canonique ; les exemples travaillés dans TASKS.md supposent ce chemin. Les consommateurs dans d'autres langages (Rust, Go, Python, …) consomment le même *.so via FFI ou les bindings spécifiques au langage ; la contribution de cette compétence dans ce cas est de garder la distinction exporteur-vs-service, le cycle de vie schema-register-before-emit, la règle capability-discovery, la règle de permission same-user-as-the-app, l'invariant de suppression-pas-blocage du chemin chaud, et la guidance de la taxonomie des erreurs indépendantes du langage, et d'orienter l'agent vers l'ABI C public comme la surface faisant autorité que tout wrapper finira par appeler.

Quand charger cette compétence

Chargez cette compétence quand l'utilisateur travaille directement sur l'Exporteur de Télémétrie DOCA, dans n'importe quel langage. Concrètement :

Définir un doca_telemetry_exporter_schema pour les événements que l'application émettra (noms de champs + types de champs), et l'enregistrer auprès de l'exporteur AVANT tout événement publié.
Créer une ou plusieurs instances doca_telemetry_exporter_source pour représenter des sources logiques distinctes de télémétrie à l'intérieur de l'application (p. ex. une source par thread worker / par étape de pipeline).
Choisir le bon doca_telemetry_exporter_type (compteur, jauge, événement) pour chaque champ que l'application rapporte.
Lire la surface de capacité du device + de la bibliothèque pour l'exporteur via la famille de requête doca_telemetry_exporter_*_get_* avant de supposer qu'une limite particulière (max champs de schéma, taille d'événement max, …) est disponible sur cette installation.
Déboguer un DOCA_ERROR_* retourné par un appel d'exporteur (cycle de vie vs. valeur invalide vs. file d'attente de transport pleine vs. permission vs. transport / driver) et le statut par-événement rapporté à l'application.
Choisir entre Telemetry Exporter et une option adjacente (doca_log quand stdout / structured-log shipping suffit ; une bibliothèque client Prometheus quand l'utilisateur a besoin d'un sink non-DOCA-aware ; doca-comch quand l'utilisateur a besoin d'une subscription événement real-time DE RETOUR VERS l'application — l'exporteur est publish-only / one-way).
Concevoir ou étendre des bindings non-C (Rust, Go, Python, …) qui enveloppent l'ABI C de l'exporteur — pour la distinction exporteur-vs-service, le cycle de vie schema-register-before-emit, la politique de permission, l'invariant de suppression-pas-blocage du chemin chaud, et les règles de capacité + erreur que le wrapper doit honorer.

Ne chargez pas cette compétence pour l'orientation générale DOCA, l'installation de DOCA lui-même, le service de télémétrie récepteur (le Service de Télémétrie DOCA a son propre guide public accessible via doca-public-knowledge-map), ou les questions sur les bibliothèques non-exporteur. Pour ceux-ci, utilisez doca-public-knowledge-map.

Ce que cette compétence fournit

Ceci est un thin loader. Le corps garde seulement l'orientation nécessaire pour choisir le prochain bon fichier. Le matériel substantiel spécifique à l'exporteur vit dans deux fichiers compagnons :

CAPABILITIES.md — ce que l'exporteur peut exprimer sur cette installation : la règle de répartition des rôles exporteur-vs-service, la famille d'objets (doca_telemetry_exporter_schema → _source → _type avec le cycle de vie schema-register-before-emit), la surface de capability-query (doca_telemetry_exporter_*_get_*), la taxonomie des erreurs d'exporteur (mappée sur l'ensemble DOCA_ERROR_* cross-library, avec la règle AGAIN-means-drop-not-block explicitement appelée), la surface d'observabilité (statut par-émission + snapshot de capacité au moment de la configuration + le côté consommateur comme signal de bout en bout), la politique de sécurité qui contrôle la permission same-user-as-the-app et la staging consumer-must-be-up-first, et la règle de sélection de chemin contre doca_log, Prometheus, et doca-comch.
TASKS.md — des workflows étape par étape pour les six verbes d'exporteur en scope : configure, build, modify, run, test, debug. Plus un bloc Deferred task verbs qui pointe les questions out-of-scope vers la bonne prochaine compétence.

La compétence suppose un hôte où DOCA est déjà installé à l'emplacement standard, l'application s'exécute en tant qu'utilisateur pouvant écrire sur le transport de télémétrie pour lequel l'exporteur est configuré, et un consommateur de télémétrie récepteur est accessible et démarré avant l'exporteur. Elle ne couvre pas l'installation de DOCA — ce chemin passe par doca-setup — et elle ne couvre pas la configuration / l'exploitation du service de télémétrie récepteur, qui est un service DOCA séparé avec son propre guide public.

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

Cette compétence est une guidance d'agent, pas un bundle de samples ou de templates. Pour garder la limite claire, elle ne contient délibérément pas — et les pull requests ne devraient pas ajouter :

Du code source d'application Exporteur de Télémétrie DOCA pré-écrit, dans n'importe quel langage. Le code source d'exporteur vérifié est les samples C fournis à /opt/mellanox/doca/samples/doca_telemetry_exporter/. Le travail de l'agent est d'orienter l'utilisateur vers ces fichiers et de prescrire une modification minimum-diff sur eux via le workflow universel modify-a-sample dans doca-programming-guide, mis en couche avec les overrides spécifiques à l'exporteur dans TASKS.md ## modify.
Un consommateur / collecteur / service de télémétrie récepteur. Le Service de Télémétrie DOCA est un service DOCA séparé avec son propre guide public ; l'orientation vers celui-ci passe par doca-public-knowledge-map. Cette compétence porte seulement sur le côté éditeur.
Des manifestes de construction autonomes (meson.build, CMakeLists.txt, Cargo.toml, …) stationnés à l'intérieur de la compétence. L'agent construit le manifeste de construction dans le répertoire du projet de l'utilisateur contre le DOCA installé de l'utilisateur, où pkg-config --modversion doca-telemetry-exporter est la source de vérité.
Un sous-arbre samples/, bindings/, ou reference/ de n'importe quel type. Un artefact simulé ou incomplet dans l'arbre de cette compétence, même s'il est étiqueté « reference », est trompeur : les utilisateurs le liront comme construit.

Ordre de chargement

Lisez d'abord ce SKILL.md pour confirmer que la question de l'utilisateur est dans le scope.
Pour la règle exporteur-vs-service, la famille d'objets, le cycle de vie schema-register-before-emit, la surface de capability-query, la taxonomie des erreurs (incluant la règle AGAIN-means-drop), l'observabilité, la politique de sécurité, et la règle de sélection de chemin contre doca_log / Prometheus / comch, voir CAPABILITIES.md.
Pour les workflows étape par étape — configure, build, modify, run, test, debug — voir TASKS.md.

Les deux fichiers compagnons font des renvois croisés l'un vers l'autre, doca-version pour les règles de gestion des versions canoniques, et doca-public-knowledge-map chaque fois que la bonne réponse est « consulte-le dans la documentation publique ou la disposition du package installé » plutôt que « guidance spécifique à l'exporteur ».

Compétences connexes

doca-public-knowledge-map — la table de routage pour chaque source de documentation DOCA publique et la disposition sur disque d'un package DOCA installé. L'URL du guide public de l'exporteur est https://docs.nvidia.com/doca/sdk/DOCA-Telemetry-Exporter/index.html ; les samples sur disque vivent sous /opt/mellanox/doca/samples/doca_telemetry_exporter/. Le Service de Télémétrie DOCA (récepteur, out of scope ici) est un guide séparé accessible via cette même table de routage.
doca-setup — préparation d'env, vérification d'installation, vérifications de réachabilité côté transport, et le chemin I have no install yet avec le container DOCA NGC public. Cette compétence suppose que ses préconditions sont satisfaites (en particulier, l'utilisateur de l'application peut écrire sur le transport de télémétrie).
doca-version — règles canoniques de gestion des versions DOCA. Le ## Version compatibility de cette compétence fait des renvois croisés vers la règle de correspondance quatre voies + la chaîne de détection et ajoute les règles de surcouche spécifiques à l'exporteur.
doca-structured-tools-contract — la règle de précédence structured-tools du bundle (detect / prefer / fall back / report). L'appendice Command dans TASKS.md honore ce contrat.
doca-programming-guide — les motifs généraux de programmation DOCA partagés par chaque bibliothèque : le motif de construction meson + pkg-config canonique, le workflow first-app universel modify-a-shipped-sample, le cycle de vie universel, la taxonomie DOCA_ERROR_* cross-library, et l'ordre de débogage côté programme. Cette compétence superpose les spécificités de l'exporteur.
doca-comch — la primitive correcte quand l'utilisateur a besoin d'une subscription événement real-time DE RETOUR VERS l'application (messagerie control-plane host ↔ DPU). L'exporteur est publish-only / one-way ; la règle de sélection de chemin de cette compétence vous oriente là-bas quand la subscription est le vrai besoin.
doca-debug — l'échelle de débogage cross-cutting (install / version / build / link / runtime / program / driver). Le débogage spécifique à l'exporteur (consumer not up, schema-not-registered, transport queue full, hot-path block) se superpose à cette échelle.