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 pianificati persi. Tre giorni di messaggi automatici senza risposta. Tre giorni di un lavoro di monitoraggio che non stava monitorando nulla.
Il mio cliente se ne è accorto prima di me. È stato imbarazzante.
Così ho configurato Grafana per osservare i miei agenti come i miei agenti osservano tutto il resto. Ora so entro pochi minuti quando qualcosa va storto, e di solito so perché prima ancora di aprire un terminale.
Cosa Monitorare (E Cosa Non Monitorare)
Quando ho impostato il monitoraggio per la prima volta, ho tracciato tutto. Tempi di risposta per richiesta, conteggi di token per messaggio, punteggi di confidenza del modello, utilizzo della memoria per sessione, tassi di errore per tipo, istogrammi di latenza… 47 metriche su 12 pannelli.
Ho guardato quel cruscotto per una settimana. Poi mi sono reso conto che stavo guardando solo 4 cose:
È in esecuzione? Controllo semplice su/giù. Punto verde = processo attivo e reattivo. Questo cattura crash, blocchi e guasti dell’infrastruttura.
È lento? Tempo medio di risposta negli ultimi 5 minuti. Normalmente 2-3 secondi. Quando supera gli 8 secondi, qualcosa non va — di solito un eccesso di contesto o problemi con il fornitore API.
Sta fallendo? Tasso di errore come percentuale delle richieste totali. Sotto il 2% è normale (timeout occasionali dell’API). Sopra il 5% indica problemi sistematici.
È costoso? Costo operativo per il giorno corrente rispetto alla media giornaliera. Un picco 2x significa che qualcosa sta generando richieste inaspettatamente lunghe o frequenti.
Ho semplificato il mio cruscotto a queste quattro metriche. Una riga, quattro grandi numeri con codifica colore. Questo è ciò che guardo 10 volte al giorno. Tutto il resto è su una pagina di “dettagli” che visito solo durante il debug.
La Configurazione
Raccolta dati: Ho scritto un piccolo script che analizza i log di OpenClaw e espone le metriche in formato Prometheus. Funziona come processo secondario e raccoglie il file di log ogni 30 secondi. Circa 50 righe di codice. Niente di speciale.
Le metriche che espone:
– openclaw_requests_total (conteggio, etichettato per tipo)
– openclaw_response_seconds (istogramma)
– openclaw_errors_total (conteggio, etichettato per tipo di errore)
– openclaw_tokens_used (conteggio, etichettato per direzione: input/output)
– openclaw_process_up (misuratore, 1 o 0)
Prometheus raccoglie 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 100MB di RAM per questo carico di lavoro ridotto.
Grafana visualizza le metriche. Uso il piano gratuito di Grafana Cloud (10.000 metriche, che sono più che sufficienti). Puoi anche autogestire Grafana sullo stesso server — è leggero.
Tempo totale di configurazione: circa 2 ore la prima volta. La maggior parte del tempo è stata impiegata per scrivere l’analizzatore di log.
Le Notifiche Che Funzionano
Ho quattro notifiche. Ho sintonizzato le loro soglie nel corso di tre mesi per minimizzare i falsi positivi:
Processo inattivo per > 2 minuti. Si attiva se il controllo su/giù fallisce per due minuti consecutivi. Due minuti offrono un buffer sufficiente per i riavvii e brevi interruzioni di rete. Questo invia una notifica push al mio telefono.
Tempo di risposta p95 > 15 secondi per 5 minuti. Una singola risposta lenta non importa. Cinque minuti di risposte costantemente lente significano che qualcosa non va sistematicamente. Questo viene postato nel mio canale di avvisi Slack.
Tasso di errore > 10% per 3 minuti. Ho impostato questa soglia più alta di quanto ci si potrebbe aspettare (10% invece di 5%) perché brevi picchi di timeout dell’API sono normali durante la manutenzione del fornitore. Tre minuti di errori elevati sostenuti significano che non è un picco occasionale. Notifica telefonica.
Costo giornaliero > 3x media mobile. Controllato ogni ora. Cattura loop incontrollati e schemi di utilizzo inaspettati prima che diventino costosi. Solo notifica Slack — questo è informativo, non urgente.
Ho rimosso due notifiche che erano troppo rumorose: “qualunque singola richiesta > 30 secondi” (accadeva troppo spesso durante compiti complessi degli agenti) e “utilizzo della memoria > 80%” (non rilevante — Node.js gestisce la propria raccolta di spazzatura e brevi picchi sono normali).
Il Cruscotto Che Ha Catturato Problemi Reali
Febbraio: Eccesso di contesto graduale. I tempi di risposta sono cresciuti da 2.5s a 7s nell’arco di due settimane. La linea di tendenza era ovvia nel cruscotto — le singole richieste apparivano a posto, ma la media giornaliera stava salendo. Causa principale: i contesti di conversazione stavano crescendo perché la compattazione non si stava attivando 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 lavoro cron aveva un meccanismo di ripetizione che, a causa di un bug, continuava a ritentare indefinitamente quando l’API restituiva un codice di errore specifico. L’avviso di costo giornaliero si è attivato a 2x la media. L’ho catturato entro 2 ore. Senza l’avviso, avrebbe continuato fino a quando la chiave API non avesse colpito il suo limite di spesa.
Marzo: Fallimento silenzioso del cron. Il mio lavoro di report giornaliero ha smesso di funzionare. Nessun errore — semplicemente non si è eseguito. Il cruscotto mostrava che il picco di attività atteso alle 8 del mattino era assente. Il programmatore cron si era bloccato dopo un aggiornamento. Riavviarlo ha risolto il problema, e ho aggiunto l’avviso di processo inattivo specificamente per il programmatore.
Cosa Direi al Mio Io Passato
Inizia con le quattro metriche di base. Aggiungi complessità solo quando hai un’esigenza di debug specifica. La maggior parte dei cruscotti di monitoraggio fallisce perché sono troppo complessi — costruisci 20 pannelli, diventi sopraffatto dai dati e smetti di guardare completamente il cruscotto.
Il cruscotto che usi effettivamente è migliore del cruscotto che traccia tutto. Rendilo facilmente leggibile, rendi le notifiche azionabili e rivedi le soglie mensilmente. Questa è la strategia completa.
🕒 Published: