StackPractices
beginner Por Mathias Paulenko

Plantilla de Documento de Estándares de Logging

Una plantilla de documento para definir convenciones de logging estructurado, niveles de log, retención y requisitos de observabilidad en servicios.

Descripción General

Este documento define cómo tus servicios, aplicaciones e infraestructura emiten logs. Cuando todos los servicios loguean igual, la depuración, la monitorización, la investigación de seguridad y el cumplimiento se vuelven más fáciles. Esta plantilla cubre niveles de log, formatos estructurados, campos requeridos, retención, muestreo y reglas de seguridad.

Completa cada sección, asigna un responsable y una cadencia de revisión, y guarda el documento junto a tus runbooks — un estándar que nadie encuentra es un estándar que nadie sigue.

Cuándo Usar

Úsala cuando se incorpora un servicio nuevo o un equipo de desarrollo, cuando consolidas logs de varios sistemas en una plataforma central de observabilidad, o al prepararte para una auditoría de seguridad o de cumplimiento. También es el artefacto correcto tras un incidente de producción donde los logs resultaron incompletos o inconsistentes, y cuando defines la estrategia de logging para microservicios o entornos serverless.

Para una estrategia de observabilidad más amplia, consulta la Guía Completa de Observabilidad con el Stack de Grafana.

Prerrequisitos

  • Una plataforma de agregación de logs como ELK, Splunk, Datadog, Grafana Loki o CloudWatch.
  • Un acuerdo sobre un único estándar de timestamp y política de zona horaria.
  • La lista de eventos que consideras críticos — los que nunca pueden faltar en un flujo de logs.
  • Un acuerdo sobre clasificación de datos sensibles y reglas de redacción de logs.

Solución

Documento

1. Niveles de Log

NivelUsoEjemplo
DEBUGInformación detallada de diagnóstico durante desarrollocache miss para clave user:1234
INFOEventos normales de la aplicaciónusuario inició sesión, orden completada
WARNSituaciones inesperadas pero recuperablestimeout de conexión, reintentando
ERRORFallos que afectan la operaciónpasarela de pagos devolvió 500
FATALFallos críticos que requieren atención inmediatabase de datos no disponible, servicio detenido

Lineamientos:

  • DEBUG debe estar deshabilitado en producción por defecto.
  • INFO es el nivel por defecto en producción para la mayoría de los servicios.
  • ERROR debe disparar una alerta o ticket.
  • FATAL debe despertar al equipo de guardia.

2. Formato de Log Estructurado

Emite cada entrada de log como JSON con estos campos requeridos:

CampoTipoDescripciónEjemplo
timestampISO 8601Hora del evento en UTC2026-06-27T14:30Z
levelstringNivel de logINFO
servicestringNombre del servicio o aplicaciónpayment-service
environmentstringEntornoproduction
messagestringResumen legibleOrder 12345 completed
correlation_idstringID de traza de la solicitudabc-123-def
span_idstringID de span de OpenTelemetryspan-xyz-789

Campos opcionales:

  • user_id: Identidad del usuario asociado al evento.
  • tenant_id: Identificador para aislamiento multi-tenant.
  • duration_ms: Tiempo empleado en completar una operación.
  • error_code: Código de error estable para manejo programático.
  • source_file: Archivo y línea donde se emitió el log.

Elige una única convención de nombres — esta plantilla usa snake_case — y aplícala a cada campo, incluidos los de los objetos context anidados. Las convenciones mezcladas (correlation_id en un servicio, correlationId en otro) rompen cualquier consulta entre servicios.

3. Categorías de Eventos Requeridos

CategoríaEventos a RegistrarNivel
AutenticaciónLogin, logout, login fallido, reto MFAINFO / WARN
AutorizaciónAcceso denegado, escalada de permisosWARN
Cambios de datosCrear, actualizar, eliminar registros sensiblesINFO
ErroresExcepciones, fallos externos, reintentosERROR
RendimientoConsultas lentas, alta latencia, timeoutsWARN
SeguridadActividad sospechosa, rate limits, peticiones bloqueadasWARN
OperacionalArranque, apagado, cambios de configuraciónINFO
NegocioPedido realizado, pago recibido, flujo completadoINFO

4. Datos Sensibles y Redacción

Tipo de DatoSe RegistraRedacción
ContraseñasNuncaRedactar o excluir
Números de tarjetaNuncaTokenizar o excluir
API keysNuncaRedactar o excluir
Nombres de personasCon aprobaciónEnmascarar si no es necesario
EmailsPermitidoEnmascaramiento parcial para no-admins
IPsPermitidoPermitido en logs de seguridad
IDs de usuarioPermitidoPermitido

Reglas:

  • Nunca loguees secretos ni credenciales.
  • Restringe los datos personales a una lista de campos permitidos.
  • Redacta o tokeniza valores antes de loguearlos.
  • Cifra los logs si contienen datos sensibles.

5. Retención y Muestreo

Tipo de LogRetenciónMuestreoNotas
Logs de aplicación30 días100%Conservar todos para depuración
Logs de seguridad1 año100%Requisito de cumplimiento
Logs de auditoría7 años100%Legal y regulatorio
Logs de debug7 días100%Solo cuando están activos
Logs de traza14 días1%Alto volumen, control de costo

6. Agregación y Transporte de Logs

RequisitoRegla
TransporteEnviar logs a la plataforma central con manejo de backpressure.
OrdenUsar timestamps para ordenar; tolerar desfases menores de reloj.
BufferingAlmacenar en buffer local si el colector no está disponible.
CodificaciónUsar JSON en UTF-8.
RespaldosReplicar los logs críticos a un almacenamiento secundario.
AlertasEnrutar los logs ERROR y FATAL al sistema de alertas.

Explicación

El logging consistente convierte archivos de texto ruidosos en datos estructurados y consultables. Al fijar niveles, campos y retención desde el inicio, los equipos pueden correlacionar eventos entre servicios, investigar incidentes más rápido y responder preguntas de cumplimiento sin arqueología. Los logs estructurados además se conectan directo con trazas y métricas — un correlation_id es la clave que une las tres señales.

El documento solo funciona si se hace cumplir, no solo si está escrito — ver Haciendo Cumplir el Estándar más abajo.

Ejemplo de Formato de Log Estructurado

{
  "timestamp": "2026-07-11T10:55:32.123Z",
  "level": "ERROR",
  "service": "auth-service",
  "environment": "production",
  "correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "user_id": "usr_8f7e6d5c",
  "message": "Validación JWT falló",
  "error_code": "AUTH_JWT_INVALID",
  "context": {
    "endpoint": "/api/v1/auth/verify",
    "method": "POST",
    "status_code": 401,
    "duration_ms": 12,
    "ip_address": "10.0.1.42",
    "user_agent": "MobileApp/2.3.1"
  },
  "error": {
    "type": "TokenExpiredError",
    "message": "jwt expired",
    "stack": "TokenExpiredError: jwt expired\n    at ..."
  }
}

Matriz de Decisión de Niveles de Log

=== Cuándo Usar Cada Nivel de Log ===

FATAL   - El sistema no puede continuar. El proceso terminará.
          Ejemplos: fallo al cargar config, error de puerto, OOM

ERROR   - La operación falló pero el sistema continúa.
          Ejemplos: petición fallida, error de query, timeout de API externa

WARN    - Condición inesperada pero recuperable.
          Ejemplos: reintento exitoso, cache miss, uso de API deprecada

INFO    - Evento significativo de negocio u operación.
          Ejemplos: login de usuario, pedido realizado, deploy iniciado

DEBUG   - Detalle de diagnóstico para troubleshooting.
          Ejemplos: estado de variables, parámetros de query, contenido de caché

TRACE   - Flujo de ejecución de máxima granularidad.
          Ejemplos: entrada/salida de función, conteo de iteraciones

REGLAS:
  - Producción: INFO y superiores (DEBUG/TRACE desactivados)
  - Staging: DEBUG y superiores
  - Desarrollo: TRACE y superiores
  - Nunca loguear en DEBUG en producción salvo depuración activa
  - ERROR debe ser accionable — si no lo es, es INFO

Haciendo Cumplir el Estándar

Un estándar que solo existe en papel deriva en un trimestre. Tres mecanismos baratos lo mantienen vivo:

  • Wrapper de logging compartido. Publica una librería por lenguaje que codifique los campos requeridos, aplique la convención de nombres y exponga los hooks de redacción. Nadie debería tener que recordar el esquema de memoria.
  • Check de esquema en CI. Un test que verifique que los logs emitidos son JSON válido y contienen timestamp, level, service, environment, message y correlation_id atrapa regresiones de formato antes del merge. Añade una pasada regex sobre patrones comunes de secretos (Bearer, password=, formatos de claves AWS) de paso.
  • Versionado y propiedad. Dale al documento un responsable, una sección de changelog y una cadencia de revisión (trimestral funciona). Añadir campos es retrocompatible; renombrarlos es un cambio incompatible que merece nota de migración.

El modo de fallo a vigilar es el documento escrito una vez y olvidado: seis meses después, la mitad de los servicios loguean correlation_id, la otra mitad se decidió por trace_id, y nadie recuerda qué nombre siguen consultando los dashboards. Por eso el enforcement pesa más que la redacción — pon el estándar donde ocurre el code review, no en una wiki que nadie abre. Si un revisor puede bloquear un PR por loguear una contraseña u omitir correlation_id, el estándar sobrevive el contacto con la realidad. Si no puede, el documento es decoración.

Variantes

  • Estándares de logging en la nube: ajustados a AWS CloudWatch, Azure Monitor o Google Cloud Logging.
  • Logging en contenedores y Kubernetes: cubre shippers sidecar, Fluentd y convenciones de logs de pods.
  • Logging orientado a seguridad: enfatiza eventos de auditoría, integridad y detección de manipulación.
  • Logging serverless: aborda funciones efímeras, cold starts y recolección centralizada.
  • Logging móvil o de cliente: se centra en privacidad, batching y buffering offline.

Lo que funciona

Los equipos que le sacan valor a un estándar de logging comparten unos cuantos hábitos. Eligen un único formato estructurado para todos los servicios, llevan un correlation ID a lo largo de cada petición para que el distributed tracing realmente tracee, y registran resultados en los límites de negocio en lugar de narrar cada paso interno. Los mensajes quedan cortos — el contexto vive en los campos estructurados, no en la frase.

Además tratan los niveles de log como un contrato: un ERROR significa que alguien tiene que actuar, y eso es lo que mantiene las alertas legibles. Los datos sensibles nunca llegan al stream por defecto, la retención se revisa contra facturas de almacenamiento reales y necesidades de cumplimiento, y el parsing de logs junto con las reglas de alerta se ejercitan durante los despliegues como cualquier otra parte de la release.

Errores Comunes

El fallo clásico es loguear todo a INFO: los problemas reales se ahogan en ruido rutinario y las alertas dejan de significar algo. Le siguen de cerca los logs en texto plano imposibles de parsear, los timestamps ausentes o inconsistentes, y los servicios que cada uno inventa sus propios nombres de campo — correlation_id en uno, correlationId en el siguiente — de modo que las consultas entre servicios no coinciden con nada silenciosamente.

Los otros pecados recurrentes son de datos y retención: contraseñas o tokens que acaban en el stream, contexto insuficiente para reproducir un fallo a posteriori, y conservar todos los logs para siempre mientras la factura de almacenamiento sube sin que nadie lo note.

Troubleshooting

  • No hay logs para una petición que falla: verifica el envío de logs, la retención y que la petición llegó al servicio.
  • Campos que faltan o renombrados tras un despliegue: revisa la versión del wrapper compartido — un bump de librería suele cambiar el esquema silenciosamente.
  • Líneas de log duplicadas en el índice: busca dos shippers leyendo el mismo archivo, o un logger de envío directo conviviendo con el agente.
  • La alerta dispara pero el servicio está sano: ajusta umbrales y usa alertas multi-señal.
  • El volumen de logs explotó tras una release: busca un nuevo log INFO dentro de un bucle caliente o una ruta de reintentos; aplica muestreo a la categoría ruidosa.
  • La traza está incompleta entre servicios: asegura que todos los servicios propagan el contexto de traza. Instrumenta jobs asíncronos y en background.

Lectura Adicional

  • Guía de logging estructurado: la Guía Completa de Logging Estructurado profundiza en formatos y librerías.
  • Configuración del pipeline: la Guía de Agregación de Logs cubre envío, niveles de retención y selección de plataformas de extremo a extremo.
  • Configs ejecutables: la receta de agregación de logs tiene un stack Compose de Fluentd → Elasticsearch para probar.
  • Postmortems públicos: estudia incidentes reales de equipos que enfrentaron problemas similares en producción.

Notas de Producción

Despliega el estándar gradualmente: empieza con un servicio, corrige las sorpresas de esquema que saque a la luz y luego escala al resto. Mantén el documento versionado con un changelog visible, porque las ediciones silenciosas son justo la forma en que los servicios derivan. Revisa las reglas de redacción cada trimestre contra endpoints y campos nuevos, y consulta la sección de Troubleshooting antes de reportar bugs del pipeline — la mayoría de los huecos de logs tienen una causa aburrida.

Puntos Clave

  • Un estándar de logging vale lo que vale su enforcement: wrapper compartido, check de esquema en CI y un responsable con nombre.
  • Una única convención de nombres en cada campo — aquí snake_case — o las consultas entre servicios se rompen.
  • ERROR debe ser accionable y FATAL debe avisar a guardia; cualquier cosa menor pertenece a INFO o WARN.
  • Nunca loguees secretos, y redacta datos personales antes de que lleguen al flujo de logs.

Errores Comunes en Producción

  • Dejar campos requeridos vacíos o usar respuestas vagas de una palabra.
  • Completar el documento una vez y nunca actualizarlo cuando cambia el alcance o las decisiones.
  • Guardar el documento donde el equipo no lo busca durante incidentes o revisiones.
  • No asignar un responsable, fecha límite o cadencia de revisión.
  • Copiar texto base sin eliminar secciones que no aplican.
  • Saltar el control de versiones, lo que impide rollback y responsabilidad.
  • No vincular el documento con decisiones relacionadas o acciones de seguimiento.
  • Evitar revisiones trimestrales que retirarían secciones obsoletas o sin uso.

Preguntas frecuentes

¿Deberíamos loguear en producción a nivel DEBUG?

No, DEBUG debe estar desactivado por defecto. Actívalo temporalmente para troubleshooting dirigido y desactívalo cuando el problema esté resuelto.

¿Qué es un correlation ID?

Un correlation ID es un identificador único que se pasa por todos los servicios que atienden una misma petición. Permite agrupar las entradas de log relacionadas a lo largo de un sistema distribuido.

¿Cómo manejamos datos sensibles en los logs?

Usa un enfoque de lista permitida: loguea solo campos explícitamente aprobados, y redacta o tokeniza los valores sensibles antes de que lleguen al flujo de logs.

¿Cómo implementamos correlation IDs en una arquitectura de microservicios?

Genera un correlation ID en el API gateway para cada petición entrante. Propágalo vía headers HTTP (p. ej., X-Correlation-Id). Cada servicio aguas abajo lee el header, lo incluye en todas sus entradas de log y lo pasa a llamadas posteriores. Para mensajes asíncronos, incluye el correlation ID en los metadatos del mensaje. Para jobs en background, guárdalo en el contexto del job. Usa middleware o interceptores para automatizar la propagación y que los desarrolladores no tengan que manejarla a mano. Asegura que el correlation ID aparezca en reportes de error y alertas de monitorización.

¿Qué es el muestreo de logs y cuándo deberíamos usarlo?

El muestreo de logs significa loguear solo un porcentaje de eventos para reducir volumen y costo. Úsalo para logs de alto volumen y bajo valor (p. ej., respuestas de health checks, peticiones de assets estáticos). Nunca muestrees logs de ERROR ni de seguridad. Estrategias comunes: muestreo aleatorio (loguear 1 de cada 100), por tasa (loguear las primeras N por segundo) o tail-based (loguear todos los errores, muestrear éxitos). Fluentd o Logstash pueden muestrear ya a nivel colector. Documenta la tasa de muestreo y asegúrate de que no oculta patrones importantes.

¿Cómo manejamos los costos de almacenamiento de logs?

Controla costos mediante: retención por niveles (almacenamiento hot de 7-30 días, archivo frío más largo), muestreo de logs de alto volumen, compresión de archivos de log, exclusión de endpoints ruidosos y uso de logging estructurado para consultas eficientes. Configura alertas de facturación para el almacenamiento. Revisa el volumen mensual e identifica a los mayores contribuyentes. Considera una solución de archivo dedicada (S3 Glacier, Azure Archive Storage) para retención a largo plazo en lugar de plataformas hot costosas.

¿Cuál es la diferencia entre logs, métricas y trazas?

Los logs son eventos discretos con timestamp — qué pasó en un momento concreto. Las métricas son mediciones agregadas en el tiempo — uso de CPU, conteo de peticiones, tasa de error. Las trazas recorren una misma petición a través de los límites de servicio — qué camino hizo y cuánto tardó en cada tramo. Juntas forman los tres pilares de la observabilidad. Los logs responden "qué pasó", las métricas "cuánto", y las trazas "dónde se fue el tiempo". Usa las tres para una observabilidad completa.

¿Cómo probamos el logging en CI/CD?

Añade tests que verifiquen: el formato de log es JSON válido, los campos requeridos están presentes (timestamp, level, service, correlation_id), no se loguean datos sensibles, los niveles de log se usan correctamente y el volumen no supera umbrales. Usa una suite de tests que capture la salida de logs y la valide contra el esquema. Ejecuta tests de parsing para asegurar que el pipeline de agregación puede ingerir los logs. Incluye los tests de logging en el checklist de despliegue.