Déboguer l'intégration runtime

Utilisez cette skill quand NeMo Relay est présent dans l'application mais quelque chose ne fonctionne pas. Commencez par prouver quelle couche runtime échoue avant de changer la configuration.

Premiers contrôles

• La liaison ou l'artefact natif peut-il se charger ?
• Y a-t-il une scope active quand l'appel défaillant s'exécute ?
• Le travail se déroule-t-il sur la pile de scope attendue ?
• La configuration du subscriber/exporter/plugin est-elle vraiment active ?
• L'application a-t-elle choisi la bonne couche API publique : managed execute vs cycle de vie manuel vs wrappers typés vs adaptive/plugins ?

Classes de défaillance courantes

• Extension native Python manquante
• Bibliothèque dynamique Go absente du chemin du loader
• Native addon Node non construit ou ne se chargeant pas
• Execute appelé en dehors d'une scope
• Événements manquants parce que l'enregistrement n'a jamais eu lieu
• Concurrence causant une mauvaise pile de scope active
• Composant adaptive jamais initialisé ou validation de config ignorée

Matrice de dépannage embarquée

• Rust build failure : exécutez d'abord le build core le plus étroit, puis étendez à la liaison affectée ou la commande workspace.
• Python import failure : reconstruisez l'environnement virtuel et l'extension native avec uv sync, puis exécutez un petit test Python ou vérification d'import depuis le même environnement que l'application.
• Node.js addon failure : réinstallez et reconstruisez le native addon depuis le package Node binding avant de déboguer le code applicatif.
• Go loader failure : compilez la bibliothèque partagée FFI de release et pointez le linker et le loader runtime vers le répertoire de sortie de release ; utilisez la variable de chemin de bibliothèque dynamique macOS (DYLD_LIBRARY_PATH) sur macOS.
• Scope stack empty : le travail se trouve en dehors d'une scope active ou a franchi une limite de thread, task, goroutine ou worker sans la pile prévue.
• Work leaks across requests : des requêtes distinctes partagent une même pile de scope ; créez une pile fraîche par requête ou agent indépendant.
• Middleware missing or ordered incorrectly : vérifiez l'enregistrement global vs scope-local, l'ascendance de scope active, les noms et les valeurs de priorité.
• Subscriber missing events : enregistrez avant que les événements soient émis ; pour les subscribers scope-local, assurez-vous que la scope courante est le propriétaire ou un descendant.
• Event fields missing : les assistants managed remplissent les champs sémantiques ; les appels de cycle de vie manuel nécessitent des params explicites pour les noms d'input, output, model et les IDs d'appel d'outil.
• ATIF empty or mixed : enregistrez avant le démarrage du travail, utilisez un exporter par run ou videz entre les runs, et séparez les agents concurrents par root scope.
• Provider payload conversion failure : convertissez les objets provider non-JSON, poignées SDK, callbacks, streams ou instances de classe avec des codecs explicites.
• Plugin validation failure : validez la config indépendamment de l'enregistrement runtime et vérifiez les champs requis, types de valeur, defaults et source de config.
• Adaptive behavior unchanged : confirmez que l'instrumentation émet des événements, le composant adaptive est activé, la policy autorise le comportement, et le chemin d'appel atteint le composant configuré.
• OpenTelemetry or OpenInference export failure : confirmez http_binary vs grpc, endpoint, headers, support cible et si un exporter natif gRPC a un runtime Tokio actif.
• Callback succeeded but no lifecycle events appear : confirmez que l'intégration utilise les assistants managed execute ou des APIs start/end manuel équilibrées, pas seulement le callback business sous-jacent.

Skills connexes

• nemo-relay-get-started
• nemo-relay-instrument-context-isolation
• nemo-relay-plugin-adaptive-tuning
• nemo-relay-plugin-build