Sei mesi di registri OpenClaw. Questo è ciò che avevo quando finalmente mi sono seduto per capire perché alcune sessioni di debug richiedevano 5 minuti e altre 2 ore. La risposta era ovvia con il senno di poi: la registrazione.
Non sapere se avessi dei registri — ne avevo sempre. Il problema era che metà dei miei registri era composta da rumori inutili (« Processo avviato… processo in esecuzione… processo ancora in esecuzione… ») e l’altra metà mancava delle informazioni di cui avevo realmente bisogno quando le cose andavano male.
Ecco cosa ho cambiato e come il mio tempo di debug è passato da una media di 45 minuti a circa 12 minuti per incidente.
Il Problema Con la Registrazione di Default
La registrazione di default è progettata da sviluppatori che sanno cosa significhi tutto. Quando lo sviluppatore vede « Compattazione del contesto attivata a 142K caratteri, » sa esattamente cosa ciò significhi e cosa controllare poi. Quando lo vedo alle 3 di mattina, mi chiedo « è normale? 142K è alto? Doveva compattarsi a 142K o a 100K? È correlato all’errore che sto esaminando? »
Le registrazioni di default presuppongono che tu abbia una conoscenza perfetta del sistema. Il debug in produzione avviene quando hai conoscenze imperfette e probabilmente sei sotto stress.
Cosa Registuro Ora
Ho ristrutturato la mia registrazione attorno a un principio: ogni voce di registro dovrebbe aiutarmi a rispondere a « cosa è successo e perché? » senza bisogno di guardare un altro sistema.
Chiamate API: Modello utilizzato, numero di token in ingresso, numero di token di uscita, tempo di risposta, stato (successo/errore), messaggio di errore se presente. Una riga per chiamata. Questo mi dice immediatamente se l’API è lenta, fallisce o è costosa.
Esecuzioni di strumenti: Nome dello strumento, riepilogo degli ingressi, riepilogo delle uscite, durata, successo/fallimento. Quando uno strumento fallisce, posso vedere esattamente cosa è stato tentato e cosa è andato storto senza dover setacciare l’output grezzo.
Attività di sessione: Inizio sessione, eventi significativi (messaggio di nuovo utente, chiamata di strumento, compattazione del contesto), fine sessione. Questo mi dà una cronologia di ciò che è successo in ogni sessione.
Errori: Messaggio di errore completo, traccia dello stack, contesto pertinente (ID di sessione, richiesta utente, attività recente). Il contesto è cruciale — un errore senza contesto ti dice che qualcosa si è rotto, ma non perché.
Cosa ho smesso di registrare: Battiti cardiaci di routine (« messaggi ancora attivi » ogni 30 secondi), controlli di stato riusciti, transizioni di stato interne che sono normali e previste. Questi aggiungevano volume senza fornire informazioni.
Livelli di Registrazione Che Hanno Senso
La maggior parte dei framework di registrazione offre livelli DEBUG, INFO, WARN, ERROR. Li utilizzo in questo modo:
ERROR: Qualcosa è fallito e richiede attenzione umana. Leggo ogni registro ERROR. Se ricevo più di 5 voci ERROR al giorno durante un’operazione normale, le mie soglie sono sbagliate.
WARN: È successo qualcosa di insolito ma il sistema lo ha gestito. Limite di throughput raggiunto e ripristino, compattazione del contesto attivata, nuova tentativo riuscito dopo fallimento. Rivedo le voci WARN quotidianamente per individuare modelli.
INFO: Operazioni normali che potrei voler tracciare. Chiamate API, esecuzioni di strumenti, eventi di sessione. Le leggo solo quando debuggo un problema specifico.
DEBUG: Stato interno dettagliato per un debug approfondito. Ingressi/uscite di ogni funzione, allocazione di memoria, stato del pool di connessioni. Disabilitato in produzione a meno che non stia esaminando un bug specifico.
La chiave: in produzione, opero a livello INFO. Questo mi dà abbastanza dettagli per diagnosticare la maggior parte dei problemi senza il rumore di DEBUG. Passo temporaneamente a DEBUG quando esamino problemi specifici, poi torno a INFO.
Registrazione Strutturata
I registri in testo semplice sono difficili da cercare e impossibili da aggregare. Ho cambiato a una registrazione strutturata in JSON:
Invece di: 2024-03-15 14:23:45 ERROR Chiamata API fallita: timeout dopo 30s
Registuro: un oggetto JSON con timestamp, livello, tipo di evento, modello, errore, durata, ID di sessione e ID di richiesta.
Il formato JSON mi consente:
– Cercare per qualsiasi campo (tutti gli errori per la sessione X, tutti i timeout per il modello Y)
– Aggregare metriche (tempo di risposta medio per modello all’ora)
– Creare dashboard (Grafana può leggere i registri JSON direttamente)
– Correlare eventi (seguire una richiesta dalla sua arrivo fino alla sua risposta)
Il compromesso: i registri JSON sono meno leggibili per gli esseri umani quando si taglia il file di registro. Utilizzo uno strumento di visualizzazione di registri che formatta JSON in modo elegante per il monitoraggio in tempo reale.
Rotazione e Conservazione dei Registri
I registri degli agenti IA crescono rapidamente. Un’istanza OpenClaw moderatamente attiva genera 50 a 200 MB di registri al giorno a livello INFO. Senza rotazione, il tuo disco si riempie in poche settimane.
La mia politica di conservazione:
– Ultimi 7 giorni: registri completi (livello INFO), non compressi per un accesso rapido
– Giorni 8-30: registri compressi (gzippati, riduzione della dimensione di circa 10x)
– Giorni 31-90: solo voci ERROR e WARN (estratti dai registri completi prima della cancellazione)
– Oltre 90 giorni: solo metriche aggregate mensili (niente registri grezzi)
Questo mantiene il mio storage totale di registri sotto 5 GB pur mantenendo abbastanza storicità per l’analisi delle tendenze e l’investigazione degli incidenti.
Il Flusso di Lavoro di Debugging
Quando qualcosa si rompe, seguo questa sequenza:
1. Controlla le ultime 10 voci ERROR — generalmente rivela la causa immediata
2. Cerca lo stesso tipo di errore nella settimana precedente — si tratta di un problema ricorrente o di un caso isolato?
3. Guarda la cronologia attorno all’errore — cosa è successo nei 60 secondi precedenti all’errore?
4. Controlla gli eventi correlati — l’errore è coinciso con un deployment, un cambiamento di configurazione o un’interruzione di servizio esterna?
Questo approccio sistematico, combinato con una buona registrazione, risolve la maggior parte dei problemi in 10-15 minuti. Prima della registrazione strutturata, gli stessi problemi richiedevano 30-60 minuti poiché i passaggi 3 e 4 richiedevano un’archeologia manuale dei file di registro.
🕒 Published: