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
| Nivel | Uso | Ejemplo |
|---|---|---|
| DEBUG | Información detallada de diagnóstico durante desarrollo | cache miss para clave user:1234 |
| INFO | Eventos normales de la aplicación | usuario inició sesión, orden completada |
| WARN | Situaciones inesperadas pero recuperables | timeout de conexión, reintentando |
| ERROR | Fallos que afectan la operación | pasarela de pagos devolvió 500 |
| FATAL | Fallos críticos que requieren atención inmediata | base 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:
| Campo | Tipo | Descripción | Ejemplo |
|---|---|---|---|
timestamp | ISO 8601 | Hora del evento en UTC | 2026-06-27T14:30Z |
level | string | Nivel de log | INFO |
service | string | Nombre del servicio o aplicación | payment-service |
environment | string | Entorno | production |
message | string | Resumen legible | Order 12345 completed |
correlation_id | string | ID de traza de la solicitud | abc-123-def |
span_id | string | ID de span de OpenTelemetry | span-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ía | Eventos a Registrar | Nivel |
|---|---|---|
| Autenticación | Login, logout, login fallido, reto MFA | INFO / WARN |
| Autorización | Acceso denegado, escalada de permisos | WARN |
| Cambios de datos | Crear, actualizar, eliminar registros sensibles | INFO |
| Errores | Excepciones, fallos externos, reintentos | ERROR |
| Rendimiento | Consultas lentas, alta latencia, timeouts | WARN |
| Seguridad | Actividad sospechosa, rate limits, peticiones bloqueadas | WARN |
| Operacional | Arranque, apagado, cambios de configuración | INFO |
| Negocio | Pedido realizado, pago recibido, flujo completado | INFO |
4. Datos Sensibles y Redacción
| Tipo de Dato | Se Registra | Redacción |
|---|---|---|
| Contraseñas | Nunca | Redactar o excluir |
| Números de tarjeta | Nunca | Tokenizar o excluir |
| API keys | Nunca | Redactar o excluir |
| Nombres de personas | Con aprobación | Enmascarar si no es necesario |
| Emails | Permitido | Enmascaramiento parcial para no-admins |
| IPs | Permitido | Permitido en logs de seguridad |
| IDs de usuario | Permitido | Permitido |
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 Log | Retención | Muestreo | Notas |
|---|---|---|---|
| Logs de aplicación | 30 días | 100% | Conservar todos para depuración |
| Logs de seguridad | 1 año | 100% | Requisito de cumplimiento |
| Logs de auditoría | 7 años | 100% | Legal y regulatorio |
| Logs de debug | 7 días | 100% | Solo cuando están activos |
| Logs de traza | 14 días | 1% | Alto volumen, control de costo |
6. Agregación y Transporte de Logs
| Requisito | Regla |
|---|---|
| Transporte | Enviar logs a la plataforma central con manejo de backpressure. |
| Orden | Usar timestamps para ordenar; tolerar desfases menores de reloj. |
| Buffering | Almacenar en buffer local si el colector no está disponible. |
| Codificación | Usar JSON en UTF-8. |
| Respaldos | Replicar los logs críticos a un almacenamiento secundario. |
| Alertas | Enrutar 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,messageycorrelation_idatrapa 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.
Recursos Relacionados
Plantilla de Política de Monitoreo y Alertas
Una plantilla de política que define cómo se configuran, enrutan, escalan y revisan las alertas en servicios e infraestructura.
DocPlantilla de Runbook
Una plantilla reutilizable para runbooks operacionales: respuesta a incidentes, procedimientos de deployment y tareas rutinarias.
GuideLogging Estructurado: JSON, IDs de Correlación y Agregación
Logging estructurado con salida JSON, IDs de correlación y niveles de log. Python structlog, Node.js pino, Java SLF4J y stacks de agregación ELK y Loki.
GuideGuía Completa de Agregación de Logs
Guía práctica sobre agregación de logs: logs estructurados, estrategias de envío, políticas de retención y construcción de pipelines de logs consultables con ELK, Loki y soluciones nativas de la nube.
RecipeAgregación de Logs con ELK, Fluentd y Loki
Centraliza logs de servicios distribuidos con ELK, Fluentd y Loki para búsqueda, alertado y resolución de problemas en producción.
PatternStructured Logging: logs JSON con campos consistentes
Cómo emitir logs JSON estructurados con campos consistentes para hacerlos consultables. Cubre structlog en Python, Winston, pino, Serilog, niveles de log y agregación.