name: logging-backend
description: Implementa Wide Events para logging backend estructurado con observabilidad real
triggers:
- agregar logging
- mejorar logs
- wide events
- observabilidad
- canonical log lines
- structured logging

Logging Backend - Wide Events

Implementa Wide Events (también conocidos como Canonical Log Lines): un evento estructurado por request que contiene TODO el contexto relevante en un solo registro.

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 ("user logged in", "fetched data", "returned response"), emitís UN evento al final con toda la información agregada.

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 (solo guardar eventos interesantes)

Estructura de un Wide Event

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

  "request": { "method": "POST", "path": "/api/orders", "duration_ms": 245 },
  "user": { "id": "user_789", "plan": "premium" },
  "business": { "order_id": "ord_456", "total": 150.00, "items_count": 3 },
  "infra": { "db_queries": 4, "db_time_ms": 120, "cache_hits": 2 },
  "error": null
}

Ver wide-event-schema.md para esquema completo con todos los campos recomendados.

Workflow de Implementación

Fase 1: Middleware Base

1. Crear middleware que inicializa el wide event al inicio del request
2. Adjuntar el evento al contexto (req.wideEvent, AsyncLocalStorage, etc.)
3. Emitir el log al finalizar el request

Ver implementation.md para código del middleware.

Fase 2: Enriquecimiento

1. En cada handler/service, agregar campos al wide event
2. Usar helpers tipados: enrichUser(), enrichBusiness(), enrichError()
3. Acumular métricas: queries, cache hits, llamadas externas

Fase 3: Tail Sampling

1. Implementar función de sampling que decide qué loggear
2. Siempre loggear: errores, latencia alta, usuarios específicos
3. Samplear porcentaje de requests exitosos normales

Ver implementation.md para función de tail sampling.

Fase 4: Colorización (Desarrollo)

1. Configurar colores por nivel (ERROR=rojo, WARN=amarillo)
2. Configurar colores por contexto (Request=azul, User=verde)
3. Formatear output legible en terminal

Ver colorization.md para configuración de colores.

Checklist Rápido

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

Anti-patrones

Ver anti-patterns.md para errores comunes:
- Confundir structured logging con wide events
- Depender solo de OpenTelemetry
- Loggear múltiples veces por request
- No incluir contexto de negocio

Referencias

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

Lecturas Recomendadas

• Stripe Engineering - Canonical Log Lines - El artículo original que popularizó el patrón
• Observability Wide Events 101 - Guía práctica de implementación
• Logging Sucks - Por qué el logging tradicional no escala