Los logs diseñados para ser leídos tanto por humanos como por agentes IA funcionan como un canal de comunicación, no como un basurero de mensajes técnicos. La clave es el logging estructurado para agentes IA: campos estables, nombres claros, contexto operativo y una narrativa mínima que explique qué pasó, dónde, a quién afectó y qué conviene revisar.
Un schema bien definido permite que una persona investigue rápido y que un agente de monitoreo correlacione eventos, detecte patrones y escale incidentes sin tener que interpretar frases ambiguas.
Los logs representan entre el 60 y el 80 por ciento del costo total de observabilidad según Grafana Labs 2025. El logging estructurado con JSON comprime entre 2 y 5 veces mejor que los logs no estructurados. En mis sistemas de agentes, los logs estructurados redujeron el tiempo de debugging de un incidente de 30 minutos a menos de 10 minutos — simplemente porque el error era findable con un query directo en lugar de un grep en archivos.
Los logs ya son una interfaz de producción, no una salida secundaria
Durante años los logs funcionaron como rastro de debug. En sistemas modernos, los logs los leen equipos de soporte, SREs, plataformas de observabilidad, reglas de alerta y, cada vez más, agentes IA que investigan incidentes.
El reporte State of Agent Engineering de LangChain muestra que el 57.3% de los encuestados declara tener agentes IA corriendo en producción y el 89% ya implementó alguna forma de observabilidad para agentes.
Eso cambia la responsabilidad del log. Un mensaje como Error processing user puede ser comprensible para quien acaba de tocar el código, pero es pobre como señal operativa: no dice qué operación falló, qué entidad estuvo involucrada, si el error fue esperado o si el sistema quedó en estado recuperable.
Por qué JSON solo no alcanza: el rol de la semántica compartida
OpenTelemetry propone nombres y atributos comunes para trazas, métricas, logs y eventos. La idea central: si distintas herramientas describen el mismo fenómeno con el mismo vocabulario, la telemetría se vuelve interoperable.
En la práctica, esto significa no inventar nombres distintos para service, environment, trace_id, span_id, event, latency_ms o status en cada módulo.
Para agentes IA, la semántica importa todavía más. El ciclo de razonamiento de un agente se parece a observar, orientar, decidir y actuar. Si observa eventos ambiguos, se orienta mal. Si se orienta mal, sus hipótesis son débiles.
El texto libre rompe la máquina de correlación
El texto libre es rápido de escribir. Su desventaja es que cada persona escribe distinto:
Payment failed
Payment error
Unable to charge customer
Stripe request failed
checkout payment exception
Para una máquina son señales distintas. El logging estructurado para agentes IA elimina esa ambigüedad:
{
"level": "error",
"event": "payment.charge_failed",
"service": "checkout",
"operation": "create_payment",
"provider": "stripe",
"result": "failed",
"retryable": true
}
Campos mínimos para un log accionable
| Campo | Qué comunica |
|---|---|
timestamp | Cuándo ocurrió, con zona horaria normalizada |
level | Severidad técnica |
service | Componente que emitió el log |
event | Qué ocurrió en el dominio |
trace_id | Conecta logs con requests y trazas |
entity_type + entity_id | Qué objeto estuvo involucrado |
result | Desenlace: succeeded, failed, skipped |
reason | Causa categorizada |
retryable | Si el sistema puede recuperarse solo |
requires_action | Si necesita intervención humana |
Para logs de agentes IA, se suman: agent_name, run_id, step_type, model, tool_name, tool_call_id, latencia, tokens y resultado de políticas.
Separar severidad técnica de impacto operativo
Un error puede no afectar a ningún usuario si ocurre en una tarea secundaria con reintento automático. Un warn puede anticipar un incidente serio si indica degradación sostenida.
La diferencia práctica: sin campos como user_visible y requires_action, un agente de monitoreo no puede distinguirlos y termina escalando todo o nada.
Diseñar nombres de eventos que razonan solos
| Evitar | Preferir |
|---|---|
error | payment.charge_failed |
process_failed | subscription.renewal_payment_failed |
user_123_failed_payment | payment.charge_failed + user_id: 123 en campo separado |
subscription.renewal_payment_failed permite filtrar, agrupar y entender el dominio sin leer el código. Para un agente IA facilita construir hipótesis: si aumentan los eventos de renovación fallida, el problema puede estar en el proveedor de pagos, en validaciones o en credenciales.
Causalidad explícita para sistemas distribuidos
{
"event": "inventory.reservation_failed",
"service": "orders",
"trigger": "checkout.submit",
"dependency": "inventory-api",
"result": "failed",
"reason": "dependency_timeout",
"attempt": 2,
"retryable": true
}
Este log dice qué dependencia falló, en qué flujo, durante qué operación y si el sistema puede recuperarse. Un agente de monitoreo puede correlacionar timeouts en inventory-api con fallos en checkout y recomendar revisar esa dependencia específica.
Sin esa causalidad explícita, la línea de tiempo de un incidente se reconstruye a mano — y mal. El tema se conecta directamente con la detección de prompt drift en agentes IA, que también depende de tener trazas legibles.
Cinco errores frecuentes al estructurar logs
- Loguear demasiado: si todo es importante, nada lo es.
- Campos inconsistentes:
userId,user_id,uidycustomerpara la misma cosa rompe la búsqueda. - Esconder la causa en el message en vez de en un campo filtrable.
- Usar logs como sustituto de métricas.
- Registrar información sensible por comodidad.
El impacto es medible
New Relic reportó que el 59% de los encuestados vio mejora en MTTR tras adoptar observabilidad. Los logs no producen esa mejora solos, pero son una de las señales que hacen posible detectar, comprender y resolver con menos fricción.
El logging estructurado para agentes IA no es una práctica separada de la buena observabilidad — es una extensión natural de una idea simple: producción necesita hablar con claridad.
Si estás construyendo sistemas con agentes en producción y necesitás un modelo de observabilidad que funcione, en solu30 lo puedo revisar con vos.
Preguntas frecuentes
¿Qué significa diseñar logs legibles para humanos y agentes IA? Significa escribir logs como una interfaz de producción. Cada evento debe explicar qué pasó, dónde ocurrió, a quién afectó y qué conviene revisar.
¿Por qué no alcanza con guardar logs en formato JSON? JSON ayuda a estructurar datos, pero no garantiza que el significado sea claro. Con nombres inconsistentes o campos ambiguos, una persona o agente IA igual tendrá que adivinar el contexto.
¿Qué campos debería incluir un buen log estructurado? Timestamp, nivel, servicio, entorno, evento, entidad afectada, identificador de correlación, resultado, causa conocida, impacto operativo y mensaje humano breve.
¿Cómo ayudan los logs estructurados a los agentes IA en producción? Los agentes pueden correlacionar eventos y detectar patrones con más precisión cuando los logs tienen semántica clara. Con eventos ambiguos, sus hipótesis son más débiles.
¿Qué errores comunes conviene evitar al escribir logs? Mensajes genéricos sin causa, nombres distintos para el mismo concepto en cada módulo, y registrar información sensible por comodidad.