La prima volta che uno dei miei agenti ha smesso di funzionare silenziosamente, non me ne sono accorto per tre giorni. Tre giorni di report previsti mancati. Tre giorni di messaggi automatizzati senza risposta. Tre giorni di un lavoro di monitoraggio che non monitorava nulla.
Il mio cliente se ne è accorto prima di me. È stato imbarazzante.
Così, ho configurato Grafana per monitorare i miei agenti come i miei agenti monitorano tutto il resto. Ora, so nei minuti seguenti quando qualcosa non va, e di solito so già perché prima ancora di aprire un terminale.
Cosa monitorare (e cosa non monitorare)
Quando ho inizialmente impostato il monitoraggio, monitoravo tutto. I tempi di risposta per richiesta, il numero di token per messaggio, i punteggi di fiducia dei modelli, l’uso della memoria per sessione, i tassi di errore per tipo, gli istogrammi di latenza… 47 metriche su 12 pannelli.
Ho guardato questo cruscotto per una settimana. Poi mi sono reso conto che osservavo solo quattro cose:
Funziona? Verifica semplice on/off. Punto verde = il processo è attivo e risponde. Questo aiuta a rilevare crash, blocchi e guasti d’infrastruttura.
È lento? Tempo medio di risposta negli ultimi 5 minuti. Normalmente 2-3 secondi. Quando supera 8 secondi, qualcosa non va — di solito un sovraccarico di contesto o problemi con il fornitore API.
Sta fallendo? Tasso di errore in percentuale sul totale delle richieste. Sotto il 2%, è normale (timeout API occasionali). Sopra il 5%, significa problemi sistemici.
È costoso? Costo operativo per il giorno corrente rispetto alla media giornaliera. Un picco di 2x significa che qualcosa genera richieste anormalmente lunghe o frequenti.
Ho ridotto il mio cruscotto a queste quattro metriche. Una riga, quattro grandi numeri con un codice colore. Questa è la mia visualizzazione 10 volte al giorno. Tutto il resto si trova in una pagina “dettagli” che consulto solo durante il debug.
La configurazione
Raccolta dati: Ho scritto un piccolo script che analizza i log di OpenClaw e espone le metriche nel formato Prometheus. Viene eseguito come un processo secondario e estrae il file di log ogni 30 secondi. Circa 50 righe di codice. Niente di complesso.
Le metriche che espone:
– openclaw_requests_total (contatore, etichettato per tipo)
– openclaw_response_seconds (istogramma)
– openclaw_errors_total (contatore, etichettato per tipo di errore)
– openclaw_tokens_used (contatore, etichettato per direzione: entrata/uscita)
– openclaw_process_up (gauge, 1 o 0)
Prometheus estrae queste metriche ogni 15 secondi. La retention predefinita è di 15 giorni, il che è sufficiente per le mie esigenze. Prometheus gira sullo stesso server di OpenClaw — utilizza circa 100 MB di RAM per questo carico di lavoro ridotto.
Grafana visualizza le metriche. Utilizzo il piano gratuito di Grafana Cloud (10.000 metriche, il che è più che sufficiente). Puoi anche auto-ospitare Grafana sullo stesso server — è leggero.
Tempo totale di configurazione: circa 2 ore la prima volta. La maggior parte del tempo è stata dedicata alla scrittura del parser di log.
Gli avvisi che funzionano
Ho quattro avvisi. Ho regolato le loro soglie per tre mesi per minimizzare i falsi positivi:
Processo inattivo per > 2 minuti. Si attiva se la verifica on/off fallisce per due minuti consecutivi. Due minuti offrono un margine sufficiente per i riavvii e le piccole interruzioni di rete. Invia una notifica push al mio telefono.
Tempo di risposta p95 > 15 secondi per 5 minuti. Una sola risposta lenta non conta. Cinque minuti di risposte costantemente lente significa che qualcosa non va sistematicamente. Questo si pubblica sul mio canale di avvisi Slack.
Tasso di errore > 10% per 3 minuti. Ho impostato questo valore più alto di quanto ci si aspetterebbe (10% invece di 5%) perché brevi esplosioni di timeout API sono normali durante la manutenzione del fornitore. Tre minuti di errori sostenuti alti significano che non si tratta di un semplice incidente. Notifica sul telefono.
Costo giornaliero > 3x la media mobile. Verificato ogni ora. Cattura i loop indesiderati e i modelli di utilizzo inattesi prima che diventino costosi. Avviso solo su Slack — questo è informativo, non urgente.
Ho eliminato due avvisi che erano troppo rumorosi: “qualunque richiesta unica > 30 secondi” (questo accadeva troppo spesso durante compiti complessi dell’agente) e “utilizzo della memoria > 80%” (senza interesse — Node.js gestisce la propria raccolta dei rifiuti e brevi picchi sono normali).
Il cruscotto che ha rilevato problemi reali
Febbraio: Gonfiore graduale del contesto. I tempi di risposta sono saliti da 2,5 s a 7 s nel giro di due settimane. La curva di tendenza era evidente sul cruscotto — le singole richieste sembravano corrette, ma la media giornaliera aumentava. Causa principale: i contesti di conversazione crescevano perché la compattazione non veniva attivata correttamente. Una correzione di configurazione ha riportato i tempi di risposta alla normalità in un’ora.
Marzo: Picco di costo dovuto a un loop. Un job cron aveva un meccanismo di retry che, a causa di un bug, continuava a riprovare indefinitamente quando l’API restituiva un codice di errore specifico. L’avviso di costo giornaliero si è attivato a 2x la media. L’ho catturato in meno di 2 ore. Senza l’avviso, questo sarebbe continuato fino a quando la chiave API non avesse raggiunto il suo limite di spesa.
Marzo: Fallimento silenzioso del cron. Il mio job di report giornaliero ha smesso di essere eseguito. Non c’era errore — semplicemente non è stato eseguito. Il cruscotto mostrava che il picco di attività giornaliero atteso alle 8 era assente. Il pianificatore cron era andato in crash dopo un aggiornamento. Riavviarlo ha risolto il problema, e ho aggiunto l’avviso di processo inattivo specificamente per il pianificatore.
Cosa direi al mio io del passato
Inizia con le quattro metriche di base. Aggiungi complessità solo quando hai un bisogno specifico di debug. La maggior parte dei cruscotti di monitoraggio falliscono perché sono troppo complessi — costruisci 20 pannelli, sei sopraffatto dai dati e smetti completamente di guardare il cruscotto.
Il cruscotto che usi realmente è migliore di quello che tiene traccia di tutto. Rendilo veloce da leggere, fai in modo che gli avvisi siano utilizzabili e rivedi le soglie ogni mese. Questa è tutta la strategia.
🕒 Published: