Logging

Definition

Son las 3 AM y tu sistema de producción está caído. Los clientes se quejan, tu equipo está corriendo, y necesitas averiguar qué pasó - rápido. Abres tus logs y ves… nada útil. Solo una pared de texto no estructurado sin correlación entre entradas, sin contexto sobre qué estaba pasando cuando las cosas se rompieron. Este escenario de pesadilla es por qué el logging importa: los logs son la memoria de tu sistema, y las buenas prácticas de logging pueden significar la diferencia entre un arreglo de 5 minutos y una investigación de 5 horas.

Logging es la práctica de registrar eventos discretos que ocurren en tu aplicación - peticiones recibidas, errores capturados, cambios de estado, datos de rendimiento. A diferencia de las métricas (que agregan datos a lo largo del tiempo) o las trazas (que siguen rutas de peticiones), los logs capturan momentos específicos con contexto rico. Una entrada de log podría decir “Usuario [email protected] falló intento de login desde IP 192.168.1.1 a 2024-01-15T10:30:00Z - razón: contraseña inválida.”

El logging moderno ha evolucionado de simples archivos de texto a datos estructurados (JSON), agregación centralizada de logs (ELK, Splunk, Datadog), y análisis inteligente. El logging estructurado significa que cada entrada de log es un objeto parseable con campos como timestamp, level, service, correlation_id, y message - haciendo los logs buscables, filtrables, y analizables a escala. Cuando se hace correctamente, los logs responden la pregunta “¿qué pasó?” con precisión.

Example

Debugging un Incidente en Producción: Netflix experimenta inicios de video lentos. Los logs muestran un pico en entradas de “connection timeout” de una región específica, todas con el mismo servicio upstream. Cruzar correlation IDs revela que el CDN en esa región está fallando. Tiempo total para diagnóstico: 5 minutos, porque los logs contaron la historia.

Pista de Auditoría de Seguridad: Un banco necesita probar qué pasó durante una transacción disputada. Los logs muestran: usuario autenticado a las 10:00 AM, vio cuenta a las 10:01, inició transferencia a las 10:02, confirmó con 2FA a las 10:02:30, transferencia completada a las 10:02:35. Cada entrada tiene timestamps, IDs de usuario, direcciones IP, y detalles de transacción - una pista de auditoría completa.

Investigación de Rate Limiting de API: Un cliente se queja de que está siendo limitado injustamente. Los logs muestran que su clave API hizo 10,000 peticiones en el último minuto, todas desde la misma IP, 90% devolviendo la misma respuesta cacheada - sugiriendo un loop de reintento mal configurado. Los logs probaron que el rate limiting era correcto.

Detección de Regresión de Rendimiento: Después de un deployment, los logs muestran advertencias aumentadas de “database query slow”. Filtrar por correlation ID revela que un nuevo endpoint está ejecutando consultas N+1. Las entradas de log incluyen timing de consulta, sentencias SQL, y la petición que las disparó - suficiente para identificar y arreglar la regresión.

Troubleshooting de Integración de Terceros: Tu webhook de Stripe no está funcionando. Los logs muestran el webhook llegando, validación de firma pasando, luego un timeout llamando a tu servicio de inventario. Sin logs, culparías a Stripe; con logs, encontraste tu propio bug.

Analogy

La Caja Negra del Avión: Las aeronaves tienen grabadoras de vuelo que capturan todo lo que pasa durante un vuelo. Después de un incidente, los investigadores analizan las grabaciones para entender qué pasó. Los logs de tu aplicación sirven el mismo propósito - son la caja negra de tu software.

El Sistema de Cámaras de Seguridad: Las cámaras de seguridad no previenen robos, pero te permiten ver exactamente qué pasó, cuándo, y por quién. Los logs son las cámaras de seguridad de tu aplicación - registrando eventos para investigación posterior.

El Diario del Barco: Históricamente, los barcos mantenían diarios detallados de sus viajes - clima, posición, incidentes, decisiones. Si algo salía mal, el diario contaba la historia. El capitán no registraba “navegamos a algún lugar” - registraba “partimos de Londres a las 0800, rumbo SO a 12 nudos, tripulación de 45, carga: 200 barriles de ron.”

El Historial Médico: Los doctores no solo recuerdan tu historia - la escriben. Cada visita, resultado de prueba, y prescripción se registra. Años después, un nuevo doctor puede entender tu historial de salud completo. Los logs de aplicación funcionan igual para la “salud” de tu software.

Code Example

// Logging estructurado con correlación y contexto
import winston from 'winston';

// Configurar logging JSON estructurado
const logger = winston.createLogger({
  level: process.env.LOG_LEVEL || 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.json()
  ),
  defaultMeta: {
    service: 'user-api',
    version: process.env.APP_VERSION,
    environment: process.env.NODE_ENV
  },
  transports: [
    new winston.transports.Console(),
    new winston.transports.File({ filename: 'logs/error.log', level: 'error' }),
    new winston.transports.File({ filename: 'logs/combined.log' })
  ]
});

// Middleware de logging de peticiones
function requestLogger(req: Request, res: Response, next: NextFunction) {
  const correlationId = req.headers['x-correlation-id'] || uuid();
  const startTime = Date.now();

  // Adjuntar a petición para uso en handlers
  req.correlationId = correlationId;
  req.logger = logger.child({ correlationId });

  // Registrar inicio de petición
  req.logger.info('Petición iniciada', {
    method: req.method,
    path: req.path,
    query: req.query,
    userAgent: req.headers['user-agent'],
    ip: req.ip
  });

  // Registrar respuesta al terminar
  res.on('finish', () => {
    const duration = Date.now() - startTime;
    const level = res.statusCode >= 500 ? 'error' :
                  res.statusCode >= 400 ? 'warn' : 'info';

    req.logger.log(level, 'Petición completada', {
      method: req.method,
      path: req.path,
      statusCode: res.statusCode,
      durationMs: duration,
      contentLength: res.get('content-length')
    });
  });

  next();
}

// Logging de aplicación con contexto
async function createUser(req: Request, res: Response) {
  const { email, name } = req.body;

  req.logger.info('Creando usuario', { email });

  try {
    const user = await db.users.create({ email, name });

    req.logger.info('Usuario creado exitosamente', {
      userId: user.id,
      email
    });

    res.status(201).json(user);
  } catch (error) {
    req.logger.error('Fallo al crear usuario', {
      email,
      error: error.message,
      stack: error.stack,
      code: error.code
    });

    res.status(500).json({ error: 'Fallo al crear usuario' });
  }
}

// Niveles de log para diferentes propósitos
req.logger.debug('Info detallada de debugging', { rawData });  // Solo desarrollo
req.logger.info('Operaciones normales', { action: 'user_login' });  // Eventos de negocio
req.logger.warn('Problemas potenciales', { memoryUsage: '85%' });  // Advertencias
req.logger.error('Ocurrieron errores', { error, stack });  // Errores
req.logger.fatal('Sistema crítico', { service: 'down' });  // Fallos críticos

// Ejemplo de salida (log estructurado JSON):
// {
//   "timestamp": "2024-01-15T10:30:00.000Z",
//   "level": "info",
//   "service": "user-api",
//   "version": "1.2.3",
//   "environment": "production",
//   "correlationId": "abc-123-xyz",
//   "message": "Usuario creado exitosamente",
//   "userId": "user_456",
//   "email": "[email protected]"
// }

Diagram

flowchart LR
    subgraph Applications["Aplicaciones"]
        A1[Web API]
        A2[Worker]
        A3[Mobile Backend]
    end

    subgraph LogPipeline["Pipeline de Logs"]
        B[Log Shipper
Filebeat/Fluentd]
        C[Cola de Mensajes
Kafka]
        D[Procesador de Logs
Logstash]
    end

    subgraph Storage["Almacenamiento y Análisis"]
        E[(Elasticsearch
Índice)]
        F[Kibana
Dashboard]
        G[Alertas
PagerDuty]
    end

    A1 --> B
    A2 --> B
    A3 --> B
    B --> C
    C --> D
    D --> E
    E --> F
    E --> G

    style A1 fill:#93c5fd
    style A2 fill:#93c5fd
    style A3 fill:#93c5fd
    style E fill:#86efac
    style F fill:#fcd34d

Security Notes

SECURITY NOTES

CRÍTICO - …

Configuración y Validación:

Implementa redacción de logs para campos sensibles.
Usa patrones como “password”: “[REDACTADO]” o enmascara tarjetas de crédito como “4111-XXXX-XXXX-1234”.
Muchos frameworks de logging soportan redacción automática de campos sensibles conocidos.
Asegura el almacenamiento y acceso a logs.
Los logs frecuentemente contienen información útil para atacantes - direcciones IP, patrones de usuario, arquitectura del sistema.
Encripta logs en reposo y limita el acceso a personal autorizado.
Considera políticas de retención de logs para compliance.

Monitoreo y Protección:

GDPR, HIPAA, y PCI-DSS todos tienen requisitos sobre cuánto tiempo pueden guardarse los logs y quién puede accederlos.
Los logs que contienen datos de usuario pueden necesitar ser anonimizados o eliminados después de un período.
Ten cuidado con ataques de inyección en logs.
Input de usuario que termina en logs podría incluir entradas de log falsas o secuencias de escape de terminal.
Sanitiza input de usuario antes de registrar y usa logging estructurado para prevenir inyección.
Audita el acceso a logs.
Mantén logs de quién accedió a tus logs - esto crea una pista de auditoría mostrando que los datos de log no fueron manipulados o accedidos inapropiadamente..

Best Practices

Usa logging estructurado (JSON) - Hace los logs buscables, parseables, y analizables a escala
Incluye correlation IDs - Cada petición debería tener un ID que la siga a través de todos los servicios
Usa niveles de log apropiados - DEBUG para desarrollo, INFO para operaciones normales, WARN para problemas, ERROR para fallos
Añade contexto a cada log - Incluye datos relevantes como IDs de usuario, IDs de petición, información de timing
Centraliza logs - Agrega logs de todos los servicios en un sistema buscable (ELK, Splunk, Datadog)
Redacta datos sensibles - Nunca registres contraseñas, tokens, PII, o información de pago
Registra en límites de servicio - Los puntos de entrada y salida de tu servicio son ubicaciones críticas de logging
Incluye timestamps con timezone - Usa formato ISO 8601 con UTC para consistencia
No registres demasiado - El logging excesivo impacta rendimiento y cuesta dinero; registra lo que importa
Haz los logs accionables - Una entrada de log debería ayudar a alguien a entender qué pasó y qué hacer

Common Mistakes

Logs de texto no estructurado: console.log("error: " + error) se vuelve imposible de buscar a escala. Usa JSON estructurado.

Sin correlation IDs: Sin correlation IDs, no puedes rastrear una petición a través de servicios. Cada entrada de log necesita uno.

Registrar datos sensibles: Contraseñas, tokens, y PII en logs son pesadillas de seguridad y compliance.

Niveles de log incorrectos: Usar ERROR para todo (o DEBUG en producción) hace imposible encontrar logs importantes.

Sin contexto: “Ocurrió error” no te dice nada. “Fallo al procesar pago para order_id=123, user_id=456, error=card_declined” te dice todo.

Extremos en volumen de log: No registrar nada te deja ciego; registrar todo es caro y ruidoso. Encuentra el balance.

No registrar errores con stack traces: Cuando capturas una excepción, registra el stack trace completo - lo necesitarás para debugging.

Formatos de log inconsistentes: Diferentes formatos entre servicios hace el análisis centralizado difícil. Estandariza en un formato.

Standards & RFCs

1)RFC 5424- The Syslog Protocol (syslog estructurado)

2)RFC 3164- BSD Syslog Protocol (syslog original)

3)OTel- Logging Specification - Estándar moderno de observabilidad

4)- Elastic Common [Schema](https://reference.apios.info/es/terms/schema/) (ECS) - Nombres de campos de log estandarizados