Dépannage d'un agent durable

Expérimental. Le protocole réseau, le SDK et cette page peuvent changer, ou la fonctionnalité peut être retirée, dans une version mineure ultérieure. Agents durables indique ce qui détermine son maintien.

Un agent durable qui n'apparaît pas, affiche Unreachable ou ne répond pas à un appui : trois commandes identifient la cause, et un tableau des motifs ainsi qu'une liste de cas fournissent la solution. Dépannage couvre Collie dans son ensemble.

Premières vérifications

Exécutez ces trois commandes, dans cet ordre :

collie durable list
collie doctor
collie logs

Le téléphone affiche moins de détails. La ligne d'un agent durable indique Starting ou Unreachable sans fournir de motif. Un refus de version du protocole utilise son propre libellé, Version mismatch, ainsi qu'un encadré d'avertissement sur l'accueil de l'agent durable. Un jeton refusé utilise ses propres termes dans la barre de connexion. collie doctor et collie logs indiquent tous les autres motifs.

La table des motifs

Quand Collie ne peut pas joindre un agent durable, le reste de Collie démarre quand même, et l'agent durable apparaît comme inaccessible avec un motif.

Un motif indique la variable d'environnement même lorsque l'agent durable est une entrée de sources.json. Lisez COLLIE_DURABLE_SOCKET comme socket de l'entrée, COLLIE_DURABLE_URL comme son url et COLLIE_DURABLE_TOKEN comme son token. La correction pour une entrée se trouve dans sources.json. La correction pour la forme réservée aux agents durables se trouve dans .env, puis collie restart.

Le paramètre enfreint une règle

Collie les signale sans contacter l'agent durable. Les règles définies dans les entrées de sources.json sont également refusées au démarrage du bridge (Une faute de frappe dans sources.json).

L'agent durable ne répond pas, ou répond de manière incorrecte

Lignes du doctor pour les agents durables

collie doctor pose à chaque agent durable les mêmes questions que le pont, dans l'ordre où le pont les pose. Il n'envoie rien d'autre que hello.

Chaque entrée de sources.json reçoit un bloc de six lignes, noté durable-socket:desk pour un agent durable nommé desk. Une ligne sources avant les blocs vérifie le fichier, et une ligne durable-lead les suit. Un Collie fonctionnant uniquement en agent durable affiche les six mêmes lignes sans suffixe, et sa ligne mux indique durable, see the durable-* lines.

Une ligne en échec interrompt les lignes suivantes. Elles s'affichent comme ignorées avec la raison fix the row above first, car Collie n'interroge jamais un agent durable via un socket qui échoue au contrôle de confidentialité ou avec un jeton non conforme à sa règle. Une ligne ignorée n'est pas une anomalie.

Cas

Chaque cas indique ce que vous observez, la raison et le correctif.

Une faute de frappe dans sources.json

Vous voyez Collie à l'arrêt, et pas seulement un agent durable : le téléphone ne peut pas se connecter. collie logs se termine par [bridge] FATAL:, le chemin du fichier, l'entrée et le champ.

Le bridge lit sources.json au démarrage et s'arrête sur un champ inconnu, un kind qui n'est pas durable, un nom non conforme à la règle, un nom utilisé deux fois, socket et url ensemble, aucun des deux, un url sans token, ou un token avec un socket. Corrigez le fichier, puis exécutez collie restart. collie doctor affiche le même message dans sa ligne sources.

Lorsque le bridge ne peut pas nommer l'entrée (ce n'est pas un objet, elle contient un champ inconnu ou son nom enfreint la règle), il compte à partir de 0 et écrit entry 1 pour la seconde. collie durable attach compte à partir de 1 et écrit entry 2 pour la même entrée. Les deux indiquent le champ en cause. Dès que le nom est valide, le bridge l'écrit : entry "desk".

attach et detach refusent d'écrire un fichier qu'ils ne peuvent pas lire, afin qu'une faute de frappe n'écrase pas vos autres entrées. Ils s'arrêtent avec le code de sortie 1.

Un agent durable n'apparaît pas après attach

Vous ne voyez aucun agent durable sur le téléphone, et collie durable list indique not loaded (restart to apply).

attach et detach écrivent uniquement sources.json. Le bridge le lit au démarrage. Exécutez collie restart, ou ajoutez --restart au verbe la prochaine fois. Si not loaded persiste après un redémarrage, lisez collie logs : list formule un code HTTP 400 du bridge de la même manière qu'un 404.

Le contrôle de confidentialité échoue

Vous voyez socket-not-private: the socket's folder /tmp/hello has mode 0755, not 0700, et la ligne de diagnostic durable-socket est rouge.

Collie se connecte à un socket uniquement si l'intégralité du chemin est privée. Les causes habituelles sont un dossier avec le mode 0755, un socket placé directement dans /tmp ou un autre dossier partagé, et un lien symbolique dans le chemin. Un lien symbolique passe facilement inaperçu : /var/run pointe vers /run sur de nombreux hôtes Linux, de sorte qu'un chemin débutant par /var/run/ échoue avec /var/run is a symlink. Utilisez le chemin réel.

Exécutez chmod 700 sur le dossier propre au socket, ou déplacez le socket sous $XDG_RUNTIME_DIR. Les règles figurent dans Sécurité d'un agent durable. Un agent durable compilé avec le SDK refuse de démarrer dans un dossier existant dont le mode n'est pas 0700, et le signale explicitement.

Un fichier socket orphelin

Vous voyez connection refused sur un socket, alors que le fichier est présent.

Un agent durable qui a planté laisse son fichier de socket derrière lui, et rien n'écoute dessus. Redémarrez l'agent durable. Le SDK supprime un fichier de socket inactif avant de se mettre en écoute, et s'arrête avec another instance is already listening si le socket est actif. Ne supprimez le fichier manuellement que si votre agent durable ne le nettoie pas.

Un nom identique à celui d'une session de terminal

Vous voyez le bridge s'arrêter au démarrage avec the name is the terminal session's own; pick another, ou une session de terminal manque sur le téléphone.

Un agent durable ne peut pas prendre le nom du terminal depuis lequel Collie s'exécute. Ce nom est default sur la plupart des installations, et sur un Collie configuré uniquement pour les agents durables, default est celui de son agent durable. Le bridge s'arrête au démarrage et nomme l'entrée. Une session Herdr qui porte le nom d'un agent durable constitue un autre cas : l'agent durable conserve le nom, le téléphone n'affiche pas cette session, et le journal le signale une fois. Renommez l'un des deux.

Un avertissement durable-ready qui persiste

Vous voyez durable-ready sous forme d'avertissement à chaque exécution de collie doctor.

L'agent durable répond hello et indique ready: false. Le téléphone l'affiche comme En cours de démarrage. Un agent durable n'indique qu'il est prêt qu'après avoir structuré ses conversations et réémis ses questions en suspens. Consultez le journal propre à l'agent durable pour savoir ce qu'il attend.

L'agent durable s'arrête au démarrage lors du contrôle des descendants

Vous voyez l'agent durable s'arrêter au démarrage avec the descendant check needs Bun on Linux to read the peer of a socket; pass callerCheck: "off" to run without it.

Ce contrôle nécessite Bun sous Linux. Sous macOS, exécutez l'agent durable avec Node, ou passez callerCheck: "off" à openCollie et lisez d'abord ce que le contrôle protège. L'erreur provient de l'agent durable. Collie n'est pas en cause.

Une question revient après un redémarrage

Vous revoyez une question après le redémarrage de l'agent durable, ou une carte indiquant qu'elle a déjà reçu une réponse.

Une réponse à une question posée avant le redémarrage reçoit too-late, la carte l'indique puis disparaît. Un agent durable qui dérive l'id de la question de son appel d'outil repose la même question ; la réponse envoyée pendant le redémarrage aboutit donc et l'outil s'exécute une seule fois. Un agent durable qui génère un nouvel id à chaque fois pose une nouvelle question pour le même appel d'outil. La carte l'affiche, et Collie n'envoie pas de second push, car la protection anti-push s'appuie sur la clé de l'appel d'outil. Cette protection autorise également 3 pushs par minute et par conversation, 10 par minute et par hôte, et 30 par heure et par hôte. Le push qui serait le 31e en une heure devient un push récapitulatif pour cet hôte, et l'hôte n'en envoie plus aucun pendant l'heure qui suit. Une carte est toujours affichée.

403 appelant refusé

Vous voyez le téléphone indiquer que la réponse ou le message a été refusé, avec pour motif renvoyé par l'agent durable : 403 caller-refused.

La vérification des descendants de l'agent durable a rejeté l'appelant. Elle rejette l'agent durable lui-même, tout processus lancé par l'agent durable, ainsi que tout appelant qu'elle ne peut pas distinguer de ceux-ci. Collie se retrouve du côté de l'agent durable lorsque celui-ci, ou un outil qu'il a exécuté, a démarré le processus Collie et que ce processus reste son enfant. Démarrez Collie en dehors de l'agent durable, puis réessayez.

Réessayer, et réponse susceptible d'être appliquée

Vous voyez « Réception de la réponse incertaine » avec un bouton Réessayer, puis après appui « Peut-être déjà appliquée. Vérifiez le chat. »

Un délai d'attente dépassé, une coupure de connexion ou une erreur 5xx après le départ de la réponse signifie qu'elle a pu aboutir. Réessayer renvoie le même id de requête, de sorte que l'agent durable répond replayed et ne résout jamais la question deux fois. Si la question est déjà fermée, la première tentative a pu la clore ; le téléphone indique alors de vérifier le chat. Un envoi, un arrêt et un appui sur un bouton indiquent la même chose avec leurs propres termes.

L'agent durable a refusé le jeton

Vous voyez la barre de connexion afficher « L'agent durable a refusé le jeton. Vérifiez COLLIE_DURABLE_TOKEN sur ce pair. », et la raison est token-refused.

L'agent durable a renvoyé 401 ou 403 au jeton. La cause la plus fréquente est une rotation où un côté a changé avant l'autre. Le message sur le téléphone mentionne COLLIE_DURABLE_TOKEN même pour une entrée de type sources.json : lisez-le comme le token de l'entrée. Donnez le nouveau jeton à l'agent durable avant de redémarrer Collie. Jetons détaille les étapes de rotation. Un 403 peut aussi provenir d'un proxy d'accès placé devant l'agent durable.

Un basculement vers Inaccessible qui prend deux lectures

Vous voyez un agent durable rester Prêt lors d'une première lecture en échec, puis basculer vers Inaccessible.

Une lecture échouée après une lecture réussie conserve la dernière disposition pour cette scrutation. Le deuxième échec consécutif fait basculer l'agent durable. Un jeton refusé suit la même règle. Un chemin de socket échouant au contrôle de confidentialité est la seule exception : il apparaît immédiatement.

En https, un agent durable qui ne répond pas ou refuse le jeton n'est interrogé qu'au maximum une fois toutes les 10 s, chaque essai étant une requête facturée. Sur un socket, l'intervalle minimal entre deux lectures d'un agent durable arrêté est de 250 ms.

Dans une crew

Un agent durable situé sur un membre d'une crew s'affiche sur le téléphone du lead ; le lead doit donc savoir ce qu'est un agent durable.

Un lead antérieur à la version 1.21.0 liste les conversations de l'agent durable sans la carte de question, et son onglet Terminal scrute une conversation dépourvue de terminal. Aucune action sur le membre ne résout cela. Le membre l'indique lui-même : collie doctor émet un avertissement dans durable-lead, et le journal enregistre une ligne, [durable] the lead is 1.20.1; it shows durable panes without the question card and its Terminal tab polls; update the lead, pour chaque version détectée. Mettez le lead à jour.

Un membre plus ancien que le lead présente le défaut inverse. Le téléphone affiche « Cette machine exécute une version plus ancienne de Collie et ne peut pas recevoir de réponses ici. Mettez-la à jour, ou répondez dans l'agent durable. » Mettez ce membre à jour.