logging-backend

Wide Events y Canonical Log Lines para observabilidad real.

Triggers

Frases que activan el skill
“agregar logging”
“mejorar logs”
“wide events”
“observabilidad”
“canonical log lines”
“structured logging”

Concepto Core

Un Wide Event es un único log JSON que captura el ciclo completo de un request. En lugar de múltiples logs dispersos, emitís UN evento al final con toda la información agregada.

Comparación:

// ❌ Log tradicional - múltiples líneas dispersas
[10:30:00] INFO: User 789 logged in
[10:30:01] INFO: Fetching orders for user 789
[10:30:02] DEBUG: Query executed in 45ms
[10:30:03] ERROR: Failed to send email

// ✅ Wide Event - todo en un solo registro
{
  "user": { "id": "789" },
  "action": "fetch_orders",
  "infra": { "db_time_ms": 45 },
  "error": { "type": "email_failed" }
}

Beneficios:

  • Debuggear con UN query en vez de correlacionar múltiples logs
  • Análisis con SQL simple sobre campos estructurados
  • Sin pérdida de contexto entre logs
  • Tail sampling efectivo

Workflow del skill

Fase 1: Middleware Base

  • Crear middleware que inicializa wide event al inicio del request
  • Adjuntar evento al contexto (AsyncLocalStorage, req.wideEvent)
  • Emitir log al finalizar request

Fase 2: Enriquecimiento

  • En cada handler/service, agregar campos al wide event
  • Helpers tipados: enrichUser(), enrichBusiness(), enrichError()
  • Acumular métricas: queries, cache hits, llamadas externas

Fase 3: Tail Sampling

  • Implementar función que decide qué loggear
  • Siempre: errores, latencia alta, usuarios específicos
  • Samplear porcentaje de requests normales

Fase 4: Colorización (Dev)

  • Colores por nivel (ERROR=rojo, WARN=amarillo)
  • Colores por contexto (Request=azul, User=verde)
  • Formato legible en terminal

Ejemplo de Wide Event 

{
  "timestamp": "2024-01-15T10:30:00.000Z",
  "level": "info",
  "service": "order-api",
  "trace_id": "abc123",

  "request": {
    "method": "POST",
    "path": "/api/orders",
    "status": 201,
    "duration_ms": 567
  },

  "user": {
    "id": "user_789",
    "plan": "premium"
  },

  "business": {
    "action": "create_order",
    "entity_id": "ord_456",
    "order": {
      "total": 299.99,
      "items_count": 5
    }
  },

  "infra": {
    "db": { "queries_count": 6, "total_time_ms": 180 },
    "cache": { "hits": 3, "misses": 1 },
    "external_calls": [
      { "service": "payment-gateway", "status": 200, "duration_ms": 234 }
    ]
  },

  "error": null
}

Checklist rápido

  • Middleware que crea wide event por request
  • Contexto accesible en toda la cadena
  • Campos request: method, path, status, duration_ms
  • Campos user: id, plan, roles
  • Campos business: entidades del dominio
  • Campos infra: db_queries, cache_hits, external_calls
  • Campos error: code, message, stack
  • Tail sampling configurado
  • Formato JSON en prod, coloreado en dev

Anti-patrones

Anti-Pattern Por qué está mal
Múltiples logs por request Pierde contexto, difícil correlacionar
Solo structured logging No es lo mismo que wide events
Solo OTel Traces difíciles de queryar, sin contexto de negocio
Sin tail sampling Demasiado volumen, costos altos
Sin contexto de negocio Solo datos técnicos, no ayuda a debugging real

Troubleshooting

Problema Causa Solución
user: null en todos los logs Auth middleware corre después del wide event Mover auth middleware antes
db: { queries_count: 0 } No se usa trackDbQuery() Wrappear queries con helper
Logs muy grandes en prod Sin tail sampling Samplear solo 1-10% del tráfico normal
No correlacionan entre servicios No se propaga trace_id Agregar header x-trace-id

Referencias del skill

  • wide-event-schema.md - Esquema JSON completo
  • implementation.md - Código de middleware y helpers
  • anti-patterns.md - Qué NO hacer
  • colorization.md - Configuración de colores

Herramientas disponibles

  • Bash - Ejecutar comandos
  • Read - Leer código existente
  • Write - Crear archivos de logging
  • Edit - Modificar código existente
  • Glob - Buscar archivos
  • Grep - Buscar patrones