Seis meses de registros de OpenClaw. Eso es lo que tenía cuando finalmente me senté a averiguar por qué algunas sesiones de depuración tardaban 5 minutos y otras 2 horas. La respuesta era obvia en retrospectiva: los registros.
No si tenía registros — siempre tuve registros. El problema era que la mitad de mis registros eran ruido inútil (“Proceso iniciado… proceso en ejecución… proceso sigue en ejecución…”) y la otra mitad carecía de la información que realmente necesitaba cuando las cosas fallaban.
Aquí está lo que cambié y cómo mi tiempo de depuración se redujo de un promedio de 45 minutos a aproximadamente 12 minutos por incidente.
El Problema Con los Registros Predeterminados
El registro predeterminado es diseñado por desarrolladores que saben lo que significa cada cosa. Cuando el desarrollador ve “Compresión de contexto activada en 142K caracteres,” sabe exactamente lo que eso significa y qué comprobar a continuación. Cuando yo lo veo a las 3 AM, pienso: “¿es eso normal? ¿Es 142K alto? ¿Se suponía que debía comprimirse a 142K o a 100K? ¿Está esto relacionado con el error que estoy investigando?”
Los registros predeterminados asumen que tienes un conocimiento perfecto del sistema. La depuración en producción ocurre cuando tienes un conocimiento imperfecto y probablemente estás estresado.
Lo Que Registro Ahora
Reestructuré mi registro en torno a un principio: cada entrada de registro debe ayudarme a responder “¿qué pasó y por qué?” sin necesidad de mirar ningún otro sistema.
Llamadas a la API: Modelo utilizado, conteo de tokens de entrada, conteo de tokens de salida, tiempo de respuesta, estado (éxito/error), mensaje de error si lo hay. Una línea por llamada. Esto me dice de inmediato si la API es lenta, falla o es costosa.
Ejecuciones de herramientas: Nombre de la herramienta, resumen de entrada, resumen de salida, duración, éxito/fracaso. Cuando una herramienta falla, puedo ver exactamente qué se intentó y qué salió mal sin tener que revisar la salida en bruto.
Actividad de sesión: Inicio de sesión, eventos significativos (mensaje de nuevo usuario, llamada a herramienta, compresión de contexto), fin de sesión. Esto me proporciona una línea de tiempo de lo que sucedió en cada sesión.
Errores: Mensaje de error completo, traza de pila, contexto relevante (ID de sesión, solicitud del usuario, actividad reciente). El contexto es crucial — un error sin contexto te dice que algo falló, pero no por qué.
Lo Que Dejé de Registrar: Latidos de corazón rutinarios (mensajes de “sigue vivo” cada 30 segundos), chequeos de salud exitosos, transiciones de estado interno que son normales y esperadas. Estos aumentaron el volumen sin añadir información.
Niveles de Registro Que Tienen Sentido
La mayoría de los frameworks de registro ofrecen niveles DEBUG, INFO, WARN, ERROR. Los uso así:
ERROR: Algo falló y necesita atención humana. Leo cada registro de ERROR. Si estoy recibiendo más de 5 entradas de ERROR por día en operación normal, mis umbrales son incorrectos.
WARN: Algo inusual ocurrió pero el sistema lo manejó. Se alcanzó el límite de tasa y se detuvo, se activó la compresión de contexto, el reintento tuvo éxito después de un fallo. Revisar entradas WARN a diario me ayuda a detectar patrones.
INFO: Operaciones normales que podría querer rastrear. Llamadas a la API, ejecuciones de herramientas, eventos de sesión. Solo leo esto cuando depuro un problema específico.
DEBUG: Estado interno detallado para una depuración profunda. Entrada/salida de cada función, asignación de memoria, estado del grupo de conexiones. Desactivado en producción a menos que esté investigando un error específico.
La clave: en producción, opero a nivel INFO. Esto me da suficiente detalle para diagnosticar la mayoría de los problemas sin el ruido de DEBUG. Cambio a DEBUG temporalmente al investigar problemas específicos y luego regreso.
Registro Estructurado
Los registros de texto plano son difíciles de buscar e imposibles de agregar. Cambié a registro estructurado en JSON:
En lugar de: 2024-03-15 14:23:45 ERROR La llamada a la API falló: timeout después de 30s
Registro: un objeto JSON con marca de tiempo, nivel, tipo de evento, modelo, error, duración, ID de sesión y ID de solicitud.
El formato JSON me permite:
– Buscar por cualquier campo (todos los errores para la sesión X, todos los timeouts para el modelo Y)
– Agregar métricas (tiempo de respuesta promedio por modelo por hora)
– Construir paneles (Grafana puede leer registros JSON directamente)
– Correlacionar eventos (seguir una solicitud desde su llegada hasta el procesamiento y respuesta)
La compensación: los registros JSON son menos legibles para los humanos cuando estás siguiendo el archivo de registro. Uso una herramienta de visor de registros que formatea JSON de manera atractiva para la monitorización en tiempo real.
Rotación y Retención de Registros
Los registros de agentes de AI crecen rápidamente. Una instancia de OpenClaw moderadamente activa genera de 50 a 200 MB de registros por día a nivel INFO. Sin rotación, tu disco se llena en semanas.
Mi política de retención:
– Últimos 7 días: registros completos (nivel INFO), sin comprimir para un acceso rápido
– Días 8-30: registros comprimidos (gzipped, alrededor de reducción de tamaño 10x)
– Días 31-90: solo entradas ERROR y WARN (extraídas de registros completos antes de la eliminación)
– Más allá de 90 días: solo métricas agregadas mensuales (sin registros en bruto)
Esto mantiene mi almacenamiento total de registros por debajo de 5 GB mientras mantiene suficiente historial para el análisis de tendencias y la investigación de incidentes.
El Flujo de Trabajo de Depuración
Cuando algo falla, sigo esta secuencia:
1. Ver las últimas 10 entradas de ERROR — generalmente revela la causa inmediata
2. Buscar el mismo tipo de error en la semana pasada — ¿es un problema recurrente o un caso aislado?
3. Mirar la línea de tiempo alrededor del error — ¿qué sucedió en los 60 segundos antes del error?
4. Comprobar eventos correlacionados — ¿coincidió el error con una implementación, un cambio de configuración o una caída de servicio externo?
Este enfoque sistemático, combinado con un buen registro, resuelve la mayoría de los problemas en 10-15 minutos. Antes del registro estructurado, los mismos problemas tomaban entre 30 y 60 minutos porque los pasos 3 y 4 requerían arqueología manual del archivo de registro.
🕒 Published: