Dépannage et signalement de bugs NVSHMEM

Objectif

Diagnostiquer les défaillances d'exécution NVSHMEM à partir d'éléments probants de haute qualité. Faire correspondre les problèmes documentés de manière prudente, vérifier les affirmations sensibles à la version avec la documentation officielle en vigueur, distinguer les défauts NVSHMEM des défaillances d'application ou d'environnement, et préparer un rapport portable quand l'escalade est utile.

Conditions préalables

• Ne requérir aucune identifiant, clé API ou accès privilégié.
• Travailler à partir de la commande de lancement exacte de l'utilisateur, de la sortie complète et des logs générés. Utiliser l'inspection directe en lecture seule uniquement quand l'utilisateur fournit l'accès et le demande.
• Utiliser $nvshmem-docs quand il est enregistré pour vérifier le comportement spécifique à la version, et $nvshmem-install quand il est enregistré pour les remises d'installation ou de construction. Sinon, utiliser la documentation officielle en vigueur liée depuis la base de connaissances intégrée.
• Garder troubleshooting-knowledge-base.md disponible pour le diagnostic et bug-report-template.md disponible pour l'escalade.

Entrées

• Obligatoire: Obtenir la commande exacte ou le stanza de lancement complet du script batch et la sortie complète stdout et stderr de chaque PE, incluant les lignes avant la première erreur et tous les logs par PE.
• Conditionnel: Obtenir une sortie confirmant la journalisation NVSHMEM au niveau INFO avant de diagnostiquer une défaillance NVSHMEM en cours de processus. Appliquer l'exception prédéfinie documentée uniquement quand NVSHMEM ne peut démontrablement pas émettre de logs.
• Optionnel: Obtenir la version NVSHMEM complète, les versions CUDA et driver, le lanceur et bootstrap, les paramètres de transport, les comptes PE/nœud/GPU, le mappage rang-vers-GPU, la topologie, l'échelle minimale défaillante, et la dernière configuration connue comme bonne uniquement quand ils distinguent les causes plausibles.
• Préséance des sources: Préférer les artefacts bruts de l'exécution en cours, puis les valeurs explicites dans l'invite utilisateur en cours ou l'invocation, puis le contexte d'agent sans conflit, puis les réponses de suivi ciblées. Signaler les conflits et préférer l'artefact brut en cours sauf si l'utilisateur confirme une correction.

Limitations

• Ne pas confirmer une cause racine à partir d'erreurs paraphrasées, de sortie PE incomplète, d'une correspondance de signature partielle, ou de changements de synchronisation seuls.
• Traiter la base de connaissances intégrée comme un cliché de routage, pas une autorité en cours. Exiger la documentation officielle en vigueur pour les affirmations spécifiques à la version.
• Ne pas prétendre qu'un correctif en version corrigée prouve que chaque version antérieure est affectée. Traiter la compatibilité des mises à niveau comme non vérifiée jusqu'à vérification par rapport à l'environnement collecté.
• Ne pas effectuer de changements de plateforme privilégiés ou soumettre directement des rapports. Fournir des vérifications en lecture seule, des questions administrateur, et du Markdown prêt à coller à la place.
• Respecter la limite d'exécution en boucle humaine ci-dessous pour chaque action de commande ou d'outil.

Instructions

Limite d'exécution en boucle humaine

Garder le diagnostic, l'inspection d'artefacts, la construction de commandes, et la rédaction de rapports en lecture seule. La liste d'outils autorisés par défaut est limitée à :

• inspection et recherche en lecture seule d'artefacts fournis par l'utilisateur dans les chemins autorisés, en utilisant rg, sed -n, head, tail, wc, stat, ou file;
• récupération en lecture seule de la documentation officielle NVSHMEM via $nvshmem-docs ou opérations de recherche/ouverture web; et
• rédaction de commandes diagnostiques et de texte de rapport dans la réponse.

Toutes les autres actions d'outils sont interdites par défaut. En particulier, ne pas invoquer d'opérations d'écriture ou suppression de fichiers, lancement/contrôle de processus ou job, gestion de paquets, changements de configuration, opérations privilégiées, téléchargements, connecteurs, ou actions de création/mise à jour/soumission externes au nom de l'utilisateur.

Si l'utilisateur demande une action diagnostique changeant l'état non destructive qui reste dans le périmètre de cette compétence, mettre en pause immédiatement avant et :

1. Afficher la commande ou l'action exacte et ses cibles résolues.
2. Expliquer ses effets attendus, si elle est réversible, et toute donnée et destination impliquées.
3. Obtenir la confirmation explicite de l'utilisateur pour cette action exacte immédiatement avant l'exécution.

Une demande de diagnostic, reproduction, correction, préparation, ou signalement d'un bug n'est pas en soi une confirmation pour effectuer une action changeant l'état. Ne pas inférer la confirmation à partir des identifiants, de la disponibilité d'outil, de l'accès shell, ou de l'approbation antérieure d'une action différente. Si la commande, la cible, les données, la destination, ou le périmètre change, divulguer le changement et confirmer de nouveau.

Les opérations destructives ou irréversibles, la soumission directe de rapport, le téléchargement d'artefact, et les changements de plateforme privilégiés restent en dehors du périmètre de cette compétence même après confirmation. Retourner un texte de rapport prêt à coller et des instructions de remise administrateur à la place.

Commencer par la commande et la sortie

Demander d'abord tous les deux éléments suivants quand l'un manque, puis arrêter :

1. La commande exacte ou le stanza de lancement complet du script batch, incluant les paramètres d'environnement, les options du lanceur, l'invocation de conteneur, et les chargements de module.
2. La sortie complète stdout et stderr de chaque PE, incluant les lignes avant la première erreur et tous les fichiers log par PE.

Ne pas commencer par un large questionnaire d'environnement. Ne pas diagnostiquer à partir d'une erreur paraphrasée quand la sortie brute peut être obtenue.

Exiger la journalisation INFO

Déterminer si la sortie capturée contient NVSHMEM_DEBUG=INFO ou des enregistrements NVSHMEM clairs au niveau INFO. La ligne de commande seule est insuffisante car un lanceur peut échouer à propager son environnement. Si la sortie ne confirme pas la journalisation INFO, demander à l'utilisateur de répéter le même lancement avec :

NVSHMEM_DEBUG=INFO
NVSHMEM_DEBUG_SUBSYS=ALL
NVSHMEM_DEBUG_FILE=nvshmem-%h-%p.log

Préserver l'exécutable, le lanceur, les comptes PE et nœud, la liaison, le transport, le conteneur, et les arguments de charge de travail. Mettre les variables là où le lanceur sélectionné les propage à chaque PE. Pour un lancement direct simple, les préfixer à la commande. Pour srun, mpirun, nvshmrun, ou un autre lanceur, invoquer $nvshmem-docs pour la version NVSHMEM détectée avant de donner la syntaxe spécifique au lanceur quand la propagation est incertaine.

Demander la commande répétée, stdout et stderr, et chaque nvshmem-<host>-<pid>.log généré. Attendre cette preuve avant d'analyser le comportement NVSHMEM.

Appliquer une exception : diagnostiquer immédiatement quand la défaillance se produit démontrablement avant le démarrage de NVSHMEM et ne peut pas émettre de logs NVSHMEM, comme l'analyse shell, la recherche d'exécutable, le démarrage du chargeur, ou l'échec d'admission du lanceur. Indiquer pourquoi la réexécution du debug ne peut pas ajouter de preuve NVSHMEM. Ne pas utiliser l'exception simplement parce qu'une erreur existante semble familière.

Construire l'enregistrement de preuve

Après la porte de journalisation, extraire avant de demander plus d'informations :

• la première erreur causale ou divergence sur chaque PE affecté, séparé des avortements en cascade;
• la version NVSHMEM et tout décalage de bibliothèque hôte/appareil signalé par les logs INFO;
• le lanceur et bootstrap, les transports sélectionnés, les paramètres NVSHMEM_* pertinents, les comptes PE/nœud/GPU, et le mappage rang-vers-GPU;
• si la défaillance change avec un PE, un nœud, différentes paires de GPU, ou plusieurs nœuds;
• l'opération et la phase : lancement, initialisation, allocation, communication, synchronisation, collectif, finalisation, ou démontage de processus.

Demander uniquement les faits manquants qui distinguent les causes plausibles. Ne jamais fabriquer une version, topologie, paramètre d'environnement, ou résultat de reproduction.

Diagnostiquer prudemment

Lire troubleshooting-knowledge-base.md pour chaque diagnostic après la porte de journalisation ou l'exception prédéfinie. Utiliser son index de sujet pour sélectionner la section pertinente, puis chercher les signatures exactes du log dans cette section avant de revenir à des correspondances sémantiques.

Classifier le résultat comme exactement l'un des suivants :

1. Correspondance confirmée de base de connaissances intégrée: la signature et les conditions requises correspondent à une entrée.
2. Problème connu spécifique à la version ou correctif en version ultérieure: les notes de version officielles établissent l'applicabilité à la version détectée.
3. Diagnostic NVSHMEM probablement pas dans la base de connaissances: la preuve pointe vers NVSHMEM, mais aucune entrée intégrée ou documentée ne correspond.
4. Problème externe probablement: la preuve pointe vers l'application, CUDA, le lanceur, le chargeur, le réseau, le driver, l'ordonnanceur, le conteneur, ou la configuration de plateforme.

Utiliser la classe 1 chaque fois qu'une entrée intégrée est confirmée, même quand cette entrée assigne la responsabilité à un composant externe; indiquer la responsabilité séparément dans Diagnosis. Utiliser la classe 4 uniquement quand aucune entrée intégrée ou documentée versionnée ne correspond. Pour les correspondances de signature partielle, utiliser la classe 3 ou 4 plutôt que d'appeler la correspondance confirmée. Traiter un symptôme de note de version similaire comme une piste, pas une preuve que l'utilisateur a le même défaut. Une note de version qui dit seulement qu'un bug a été corrigé établit la version corrective, pas chaque version antérieure affectée. Décrire une version installée antérieure comme prédatant un correctif candidat sauf si la preuve officielle établit explicitement qu'elle est affectée ou qu'un test de mise à niveau contrôlé confirme la correspondance.

Utiliser $nvshmem-docs avec la version détectée complète avant de faire des affirmations sensibles à la version. Demander la version si elle manque; si la vérification en direct est indisponible, étiqueter ces affirmations non vérifiées et non exploitables.

Avant de recommander une mise à niveau cible, vérifier la compatibilité de cette version et les problèmes connus par rapport au contexte CUDA, driver, GPU, CPU, NCCL, bootstrap, et transport collecté. Si ce contexte est incomplet, présenter la version comme un test candidat et nommer les vérifications de compatibilité manquantes au lieu de l'appeler convenable.

Séparer :

• Observation: ce que la commande et les logs affichent directement.
• Preuve de documentation: l'entrée FAQ, variable d'environnement, limitation, problème connu, ou problème corrigé correspondant.
• Inférence: l'explication la plus probable et sa confiance.
• Vérification: le plus petit test sûr qui peut confirmer ou rejeter l'inférence.

Si aucune entrée ne correspond, dire exactement : No matching entry was found in the bundled NVSHMEM troubleshooting knowledge base. Puis fournir un diagnostic probable, la confiance, les explications concurrentes, et les vérifications ciblées suivantes.

Pour un problème externe probable, identifier le propriétaire probable et donner des vérifications concrètes suivantes. Ne pas s'arrêter à « pas NVSHMEM ». Router les défaillances d'installation et de construction vers $nvshmem-install quand enregistré; sinon identifier la remise d'installation/construction appropriée sans tenter un fallback de compétence non enregistrée. Router les régressions de performance seule vers une compétence de performance NVSHMEM disponible, ou vers $nvshmem-docs quand aucune n'est disponible.

Ne pas effectuer de changements de plateforme privilégiés. Pour IMEX, driver, fabric-manager, nœud-appareil, module-kernel, NIC, ou configuration d'ordonnanceur, fournir des vérifications en lecture seule et dire à l'utilisateur ce qu'il faut demander à l'administrateur de vérifier.

Présenter le diagnostic

Retourner ces en-têtes :

• Evidence Collected
• Diagnosis
• Knowledge-Base Match
• Version Applicability
• Next Actions

Inclure les liens source officiels directs pour les affirmations soutenues par la documentation. Garder les commandes copiables et marquer les espaces réservés. Préférer un test discriminant à la fois à une longue checklist générique.

Préparer un rapport de bug ou une question

Offrir un rapport quand le problème reste non résolu, est probablement un défaut NVSHMEM, ou l'utilisateur explicitement en demande un. Ne pas routièrement offrir l'escalade pour un problème de configuration locale résolu ou une défaillance clairement externe.

Quand les logs NVSHMEM au niveau INFO sont absents, demander explicitement à l'utilisateur de reproduire la défaillance avant soumission à support avec :

NVSHMEM_DEBUG=INFO
NVSHMEM_DEBUG_SUBSYS=ALL
NVSHMEM_DEBUG_FILE=nvshmem-%h-%p.log

Préserver l'exécutable, le lanceur, les comptes PE et nœud, la liaison, le transport, le conteneur, et les arguments de charge de travail. Demander la commande exacte répétée, sortie complète stdout/stderr de chaque PE, et tous les fichiers log générés. Un brouillon peut toujours être généré quand l'utilisateur demande de préserver l'investigation, mais l'étiqueter incomplet et inclure cette réexécution comme une étape prérequise de soumission; ne pas le présenter comme prêt pour le support.

Quand préparant un, lire bug-report-template.md et le remplir à partir de la preuve collectée. Refléter le formulaire GitHub NVSHMEM issue or bug : commencer le titre par [Issue]:, utiliser ses en-têtes de champ exacts, et sélectionner exactement une valeur d'impact supportée. Préserver les commandes exactes et l'erreur causale première. Utiliser Not provided pour les faits manquants et lister ces lacunes; ne jamais les inventer. Rappeler à l'utilisateur de caviardifier les identifiants, jetons, noms d'hôte et IPs internes, et données identifiant l'utilisateur avant de partager les logs.

Retourner le Markdown dans un bloc clôturé pour qu'il puisse être collé dans GitHub, NVONLINE, ou email. Ne pas exiger ou soumettre directement via un connecteur.

Dépannage

Utiliser ces motifs quand l'investigation s'enlise :

Exemples

• Preuve manquante: Donné seulement « NVSHMEM se bloque pendant init », demander le stanza de lancement exact et la sortie complète de chaque PE, puis arrêter.
• Logs INFO manquants: Donné une commande complète et une sortie non-INFO d'une défaillance en cours de processus, demander le même lancement avec les trois paramètres de debug et tous les logs générés; préserver l'échelle et les arguments.
• Défaillance prédéfinie: Donné error while loading shared libraries avant que tout PE ne rentre dans NVSHMEM, indiquer pourquoi la journalisation INFO ne peut pas aider, identifier le chargeur comme le composant émetteur, et router un problème d'installation de bibliothèque NVSHMEM vers $nvshmem-install.
• Correspondance confirmée intégrée: Donné No more teams available plus les conditions d'utilisation d'équipe correspondantes, classifier comme correspondance confirmée intégrée, vérifier NVSHMEM_MAX_TEAMS pour la version complète, et proposer une réexécution minimale.
• Pas de correspondance: Indiquer la phrase requise pas-de-correspondance, séparer observation d'inférence, donner un test discriminant, et offrir un rapport rempli uniquement si le problème reste non résolu ou semble être un défaut NVSHMEM.