Six mois de journaux OpenClaw. C’est ce que j’avais quand je me suis enfin assis pour comprendre pourquoi certaines sessions de débogage prenaient 5 minutes et d’autres 2 heures. La réponse était évidente avec le recul : la journalisation.
Pas savoir si j’avais des journaux — j’avais toujours des journaux. Le problème était que la moitié de mes journaux étaient des bruits inutiles (« Process started… process running… process still running… ») et l’autre moitié manquait des informations dont j’avais réellement besoin lorsque les choses cassaient.
Voici ce que j’ai changé, et comment mon temps de débogage est passé d’une moyenne de 45 minutes à environ 12 minutes par incident.
Le Problème Avec la Journalisation par Défaut
La journalisation par défaut est conçue par des développeurs qui savent ce que tout signifie. Lorsque le développeur voit « Context compaction triggered at 142K chars, » il sait exactement ce que cela signifie et ce qu’il faut vérifier ensuite. Quand je le vois à 3 heures du matin, je me demande « est-ce normal ? 142K est-il élevé ? Était-ce censé se compacter à 142K ou à 100K ? Est-ce lié à l’erreur que j’examine ? »
Les journaux par défaut supposent que vous avez une connaissance parfaite du système. Le débogage en production se produit lorsque vous avez des connaissances imparfaites et que vous êtes probablement stressé.
Ce Que Je Journalise Maintenant
J’ai restructuré ma journalisation autour d’un principe : chaque entrée de journal devrait m’aider à répondre à « que s’est-il passé et pourquoi ? » sans avoir besoin de regarder un autre système.
Appels API : Modèle utilisé, nombre de tokens d’entrée, nombre de tokens de sortie, temps de réponse, statut (succès/erreur), message d’erreur le cas échéant. Une ligne par appel. Cela me dit immédiatement si l’API est lente, échoue ou est coûteuse.
Exécutions d’outils : Nom de l’outil, résumé des entrées, résumé des sorties, durée, succès/échec. Lorsqu’un outil échoue, je peux voir exactement ce qui a été tenté et ce qui s’est mal passé sans avoir à fouiller la sortie brute.
Activité de session : Début de session, événements significatifs (message de nouvel utilisateur, appel d’outil, compactage de contexte), fin de session. Cela me donne une chronologie de ce qui s’est passé dans chaque session.
Erreurs : Message d’erreur complet, trace de pile, contexte pertinent (ID de session, demande utilisateur, activité récente). Le contexte est crucial — une erreur sans contexte vous dit que quelque chose s’est cassé, mais pas pourquoi.
Ce que j’ai arrêté de journaliser : Battements de coeur de routine (« still alive » messages toutes les 30 secondes), vérifications de santé réussies, transitions d’état internes qui sont normales et attendues. Ceux-ci ajoutaient du volume sans ajouter d’informations.
Niveaux de Journalisation Qui Ont Du Sens
La plupart des frameworks de journalisation offrent des niveaux DEBUG, INFO, WARN, ERROR. Je les utilise comme ceci :
ERROR : Quelque chose a échoué et nécessite une attention humaine. Je lis chaque journal ERROR. Si je reçois plus de 5 entrées ERROR par jour lors d’une opération normale, mes seuils sont mauvais.
WARN : Quelque chose d’inhabituel s’est produit mais le système l’a géré. Limite de débit atteinte et recul, compactage de contexte déclenché, nouvelle tentative réussie après échec. Je passe en revue les entrées WARN quotidiennement pour repérer des modèles.
INFO : Opérations normales que je pourrais vouloir tracer. Appels d’API, exécutions d’outils, événements de session. Je ne les lis que lors du débogage d’un problème spécifique.
DEBUG : État interne détaillé pour un débogage approfondi. Entrée/sortie de chaque fonction, allocation de mémoire, statut du pool de connexions. Désactivé en production sauf si j’examine un bug spécifique.
La clé : en production, je fonctionne au niveau INFO. Cela me donne suffisamment de détails pour diagnostiquer la plupart des problèmes sans le bruit de DEBUG. Je passe temporairement à DEBUG lorsque j’examine des problèmes spécifiques, puis je reviens à INFO.
Journalisation Structurée
Les journaux en texte brut sont difficiles à rechercher et impossibles à agréger. J’ai changé pour une journalisation structurée en JSON :
Au lieu de : 2024-03-15 14:23:45 ERROR API call failed: timeout after 30s
Je journalise : un objet JSON avec horodatage, niveau, type d’événement, modèle, erreur, durée, ID de session et ID de demande.
Le format JSON me permet :
– De rechercher par n’importe quel champ (toutes les erreurs pour la session X, tous les délais pour le modèle Y)
– D’agréger des métriques (temps de réponse moyen par modèle par heure)
– De créer des tableaux de bord (Grafana peut lire les journaux JSON directement)
– De corréler des événements (suivre une demande depuis son arrivée jusqu’à sa réponse)
Le compromis : les journaux JSON sont moins lisibles pour les humains lorsque vous taillez le fichier journal. J’utilise un outil de visualisation de journaux qui formate JSON joliment pour la surveillance en temps réel.
Rotation et Conservation des Journaux
Les journaux des agents IA se développent rapidement. Une instance OpenClaw modérément active génère 50 à 200 Mo de journaux par jour au niveau INFO. Sans rotation, votre disque se remplit en quelques semaines.
Ma politique de conservation :
– Derniers 7 jours : journaux complets (niveau INFO), non compressés pour un accès rapide
– Jours 8-30 : journaux compressés (gzippés, réduction de taille d’environ 10x)
– Jours 31-90 : entrées ERROR et WARN seulement (extraites des journaux complets avant suppression)
– Au-delà de 90 jours : métriques agrégées mensuelles seulement (pas de journaux bruts)
Cela garde mon stockage total de journaux en dessous de 5 Go tout en maintenant suffisamment d’historique pour l’analyse des tendances et l’investigation des incidents.
Le Flux de Travail de Débogage
Lorsque quelque chose casse, je suis cette séquence :
1. Vérifier les 10 dernières entrées ERROR — révèle généralement la cause immédiate
2. Rechercher le même type d’erreur dans la semaine précédente — s’agit-il d’un problème récurrent ou d’un cas isolé ?
3. Regarder la chronologie autour de l’erreur — que s’est-il passé dans les 60 secondes précédant l’erreur ?
4. Vérifier les événements corrélés — l’erreur a-t-elle coïncidé avec un déploiement, un changement de configuration ou une panne de service externe ?
Cette approche systématique, combinée à une bonne journalisation, résout la plupart des problèmes en 10 à 15 minutes. Avant la journalisation structurée, les mêmes problèmes prenaient 30 à 60 minutes car les étapes 3 et 4 nécessitaient une archéologie manuelle des fichiers journaux.
🕒 Published: