La primera vez que uno de mis agentes dejó de funcionar silenciosamente, no me di cuenta durante tres días. Tres días de informes programados perdidos. Tres días de mensajes automatizados sin respuesta. Tres días de un trabajo de monitoreo que no estaba monitoreando nada.
Mi cliente se dio cuenta antes que yo. Eso fue embarazoso.
Así que configuré Grafana para vigilar a mis agentes como mis agentes vigilan todo lo demás. Ahora sé en minutos cuando algo sale mal, y generalmente sé por qué antes de abrir una terminal.
Qué Monitorear (Y Qué No)
Cuando configuré el monitoreo por primera vez, rastreé todo. Tiempos de respuesta por solicitud, conteos de tokens por mensaje, puntajes de confianza del modelo, uso de memoria por sesión, tasas de error por tipo, histogramas de latencia… 47 métricas en 12 paneles.
Miré ese panel durante una semana. Luego me di cuenta de que solo estaba observando 4 cosas:
¿Está funcionando? Comprobación simple de encendido/apagado. Punto verde = proceso está vivo y respondiendo. Esto captura bloqueos, cuelgues y fallos de infraestructura.
¿Es lento? Tiempo de respuesta promedio durante los últimos 5 minutos. Normalmente 2-3 segundos. Cuando supera los 8 segundos, algo está mal — generalmente expansión del contexto o problemas con el proveedor de API.
¿Está fallando? Tasa de error como porcentaje de solicitudes totales. Por debajo del 2% es normal (tiempos de espera ocasionales de la API). Por encima del 5% significa problemas sistemáticos.
¿Es costoso? Costo de funcionamiento para el día actual en comparación con el promedio diario. Un aumento de 2x significa que algo está generando solicitudes de manera inesperadamente larga o frecuente.
Reduje mi panel a estas cuatro métricas. Una fila, cuatro grandes números con codificación de colores. Eso es lo que miro 10 veces al día. Todo lo demás está en una página de “detalles” que visito solo cuando estoy depurando.
La Configuración
Recolección de datos: Escribí un pequeño script que analiza los registros de OpenClaw y expone métricas en formato Prometheus. Se ejecuta como un proceso secundario y raspa el archivo de registro cada 30 segundos. Alrededor de 50 líneas de código. Nada complicado.
Las métricas que expone:
– openclaw_requests_total (contador, etiquetado por tipo)
– openclaw_response_seconds (histograma)
– openclaw_errors_total (contador, etiquetado por tipo de error)
– openclaw_tokens_used (contador, etiquetado por dirección: entrada/salida)
– openclaw_process_up (medidor, 1 o 0)
Prometheus raspa estas métricas cada 15 segundos. La retención predeterminada es de 15 días, lo cual es suficiente para mis necesidades. Prometheus se ejecuta en el mismo servidor que OpenClaw — utiliza alrededor de 100 MB de RAM para esta pequeña carga de trabajo.
Grafana visualiza las métricas. Utilizo el nivel gratuito de Grafana Cloud (10,000 métricas, que es más que suficiente). También puedes autoalojar Grafana en el mismo servidor — es ligero.
Tiempo total de configuración: aproximadamente 2 horas la primera vez. La mayor parte fue escribir el analizador de registros.
Las Alertas que Funcionan
Tengo cuatro alertas. He ajustado sus umbrales durante tres meses para minimizar los falsos positivos:
Proceso caído por > 2 minutos. Se activa si la comprobación de encendido/apagado falla durante dos minutos consecutivos. Dos minutos dan suficiente margen para reinicios y pequeños problemas de red. Esto envía una notificación push a mi teléfono.
Tiempo de respuesta p95 > 15 segundos durante 5 minutos. Una única respuesta lenta no importa. Cinco minutos de respuestas consistentemente lentas significa que algo está sistemáticamente mal. Esto se publica en mi canal de alertas de Slack.
Tasa de error > 10% durante 3 minutos. Establecí esto más alto de lo que podrías esperar (10% en lugar de 5%) porque ráfagas breves de tiempo de espera de API son normales durante el mantenimiento del proveedor. Tres minutos de altas tasas de error sostenidas significa que no es un bache. Notificación por teléfono.
Costo diario > 3x promedio móvil. Comprobado cada hora. Captura bucles descontrolados y patrones de uso inesperados antes de que se vuelvan costosos. Alerta de Slack solo — esto es informativo, no urgente.
Eliminé dos alertas que eran demasiado ruidosas: “cualquier solicitud individual > 30 segundos” (sucedía demasiado a menudo durante tareas complejas de agentes) y “uso de memoria > 80%” (irrelevante — Node.js gestiona su propia recolección de basura y breves aumentos son normales).
El Panel que Capturó Problemas Reales
Febrero: Crecimiento gradual del contexto. Los tiempos de respuesta aumentaron de 2.5s a 7s durante dos semanas. La línea de tendencia era obvia en el panel — las solicitudes individuales parecían bien, pero el promedio diario estaba aumentando. Causa raíz: los contextos de conversación estaban creciendo porque la compactación no se estaba activando correctamente. Una corrección en la configuración devolvió los tiempos de respuesta a la normalidad en una hora.
Marzo: Aumento de costos por un bucle. Un trabajo cron tenía un mecanismo de reintento que, debido a un error, seguía intentando indefinidamente cuando la API devolvía un código de error específico. La alerta de costo diario se activó a 2x el promedio. Lo atrapé en 2 horas. Sin la alerta, habría continuado hasta que la clave API alcanzara su límite de gasto.
Marzo: Fallo silencioso del cron. Mi trabajo de informe diario dejó de ejecutarse. Sin error — simplemente no se ejecutó. El panel mostraba que el aumento diario esperado en la actividad a las 8 AM estaba ausente. El programador cron se había caído tras una actualización. Reiniciarlo solucionó el problema, y añadí la alerta de proceso caído específicamente para el programador.
Lo que Le Diría a Mi Yo Pasado
Comienza con las cuatro métricas básicas. Añade complejidad solo cuando tengas una necesidad de depuración específica. La mayoría de los paneles de monitoreo fallan porque son demasiado complejos — construyes 20 paneles, te abruma la cantidad de datos, y dejas de mirar el panel por completo.
El panel que realmente usas es mejor que el panel que rastrea todo. Hazlo fácil de revisar, haz que las alertas sean accionables, y revisa los umbrales mensualmente. Esa es toda la estrategia.
🕒 Published: