Sei mesi di log di OpenClaw. Questo è ciò che avevo quando finalmente mi sono seduto per capire perché alcune sessioni di debug duravano 5 minuti e altre 2 ore. La risposta era ovvia a posteriori: il logging.
Non se avessi log — li avevo sempre. Il problema era che metà dei miei log erano rumore inutile (“Processo avviato… processo in esecuzione… processo ancora in esecuzione…”) e l’altra metà mancava delle informazioni di cui avevo realmente bisogno quando qualcosa andava storto.
Ecco cosa ho cambiato e come il mio tempo di debug è sceso da una media di 45 minuti a circa 12 minuti per incidente.
Il Problema Con il Logging Predefinito
Il logging predefinito è progettato da sviluppatori che sanno cosa significa tutto. Quando lo sviluppatore vede “Compattazione del contesto attivata a 142K caratteri,” sa esattamente cosa significa e cosa controllare dopo. Quando lo vedo alle 3 di notte, penso “è normale? 142K è alto? Doveva compattarsi a 142K o a 100K? Questo è correlato all’errore che sto investigando?”
I log predefiniti presumono che tu abbia una conoscenza perfetta del sistema. Il debug in produzione avviene quando hai una conoscenza imperfetta e probabilmente sei stressato.
Cosa Loggo Ora
Ho ristrutturato il mio logging attorno a un principio: ogni voce di log dovrebbe aiutarmi a rispondere a “cosa è successo e perché?” senza dover guardare in nessun altro sistema.
Chiamate API: Modello utilizzato, conteggio token di input, conteggio token di output, tempo di risposta, stato (successo/errore), messaggio di errore se presente. Una riga per chiamata. Questo mi dice subito se l’API è lenta, fallita o costosa.
Esecuzione degli strumenti: Nome dello strumento, riepilogo input, riepilogo output, durata, successo/fallimento. Quando uno strumento fallisce, posso vedere esattamente cosa è stato tentato e cosa è andato storto senza dover approfondire l’output grezzo.
Attività della sessione: Inizio della sessione, eventi significativi (nuovo messaggio utente, chiamata strumento, compattazione del contesto), fine della sessione. Questo mi fornisce una cronologia di ciò che è successo in ogni sessione.
Errori: Messaggio di errore completo, traccia dello stack, contesto rilevante (ID sessione, richiesta utente, attività recenti). Il contesto è cruciale: un errore senza contesto ti dice solo che qualcosa è andato storto, ma non perché.
Cosa ho smesso di loggare: Battiti cardiaci di routine (“messaggi ancora attivi” ogni 30 secondi), controlli di salute riusciti, transizioni di stato interne che sono normali e previste. Questi aggiungevano volume senza aggiungere informazioni.
Livelli di Log Che Hanno Senso
La maggior parte dei framework di logging offre livelli DEBUG, INFO, WARN, ERROR. Li uso in questo modo:
ERROR: Qualcosa è fallito e necessita dell’attenzione umana. Leggo ogni log di ERROR. Se ricevo più di 5 voci di ERROR al giorno in operazioni normali, le mie soglie sono sbagliate.
WARN: È successo qualcosa di insolito ma il sistema ha gestito la situazione. Limite di velocità raggiunto e ritirato, compattazione del contesto attivata, tentativo di ripetere riuscito dopo un fallo. Rivedo le voci di WARN quotidianamente per individuare schemi.
INFO: Operazioni normali che potrei voler tracciare. Chiamate API, esecuzioni di strumenti, eventi di sessione. Leggo questi solo quando debugo un problema specifico.
DEBUG: Stato interno dettagliato per un debug approfondito. Input/output di ogni funzione, allocazione di memoria, stato del pool di connessione. Disabilitato in produzione a meno che non stia investigando un bug specifico.
La chiave: in produzione, lavoro 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 indago problemi specifici, poi ritorno.
Logging Strutturato
I log in testo semplice sono difficili da cercare e impossibili da aggregare. Sono passato al logging strutturato in JSON:
Invece di: 2024-03-15 14:23:45 ERROR La chiamata API è fallita: timeout dopo 30s
Loggo: un oggetto JSON con timestamp, livello, tipo di evento, modello, errore, durata, ID sessione e ID richiesta.
Il formato JSON mi permette:
– Cercare per ogni campo (tutti gli errori per la sessione X, tutti i timeout per il modello Y)
– Aggregare metriche (tempo medio di risposta per modello per ora)
– Costruire dashboard (Grafana può leggere i log JSON direttamente)
– Correlare eventi (seguire una richiesta dall’arrivo attraverso l’elaborazione alla risposta)
Il compromesso: i log JSON sono meno leggibili per l’umano quando stai seguendo il file di log. Utilizzo uno strumento di visualizzazione dei log che formatta il JSON in modo carino per il monitoraggio in tempo reale.
Rotazione e Ritenzione dei Log
I log degli agenti AI crescono rapidamente. Un’istanza di OpenClaw moderatamente attiva genera 50-200MB di log al giorno a livello INFO. Senza rotazione, il disco si riempie in poche settimane.
La mia politica di ritenzione:
– Ultimi 7 giorni: log completi (livello INFO), non compressi per un accesso rapido
– Giorni 8-30: log compressi (gzipped, circa 10 volte la riduzione della dimensione)
– Giorni 31-90: solo voci di ERROR e WARN (estratte dai log completi prima della cancellazione)
– Oltre 90 giorni: solo metriche aggregate mensili (senza log grezzi)
Questo mantiene la mia memorizzazione totale dei log sotto 5GB mentre mantiene abbastanza storia per l’analisi delle tendenze e l’indagine sugli incidenti.
Il Flusso di Lavoro di Debugging
Quando qualcosa si rompe, seguo questa sequenza:
1. Controlla le ultime 10 voci di ERROR — di solito rivela la causa immediata
2. Cerca lo stesso tipo di errore nella settimana passata — è un problema ricorrente o un caso isolato?
3. Guarda la cronologia intorno all’errore — cosa è successo nei 60 secondi precedenti all’errore?
4. Controlla gli eventi correlati — l’errore è coinciso con un deployment, un cambio di configurazione o un’interruzione del servizio esterno?
Questo approccio sistematico, combinato con un buon logging, risolve la maggior parte dei problemi in 10-15 minuti. Prima del logging strutturato, gli stessi problemi richiedevano 30-60 minuti perché i passaggi 3 e 4 richiedevano un’archeologia manuale del file di log.
🕒 Published: