Saltar a contenido

Logs y trazabilidad

Todo el core registra a través de un helper único (shared/logger/logger.ts, sobre pino) con tres garantías:

  1. Jamás lanza — un log roto no puede dañar una operación del colegio.
  2. Masking por defecto — los datos personales nunca tocan el log (LOPDP).
  3. correlationId en cada línea — propagado desde el BFF por request y también dentro de los workers de cola.

Así se ven los logs reales

Líneas capturadas del contenedor durante la simulación de este manual (docker logs academic-system-core-1):

{"level":"info","correlationId":"019f8765-c580-…","partialId":"019f8765-999c-…","subjectId":"019f8765-a139-…","count":3,"msg":"notas registradas"}
{"level":"info","correlationId":"019f8765-d13f-…","partialId":"019f8765-999c-…","msg":"parcial cerrado"}
{"level":"info","correlationId":"019f8765-d322-…","rectificationId":"019f8765-d1a4-…","approve":true,"msg":"rectificación resuelta"}
{"level":"info","correlationId":"019f8765-d62a-…","paymentId":"019f8765-d62f-…","obligationId":"019f8765-d518-…","msg":"pago registrado"}
{"level":"info","correlationId":"019f8765-d76c-…","announcementId":"019f8765-d775-…","scope":"COLEGIO","msg":"comunicado publicado"}
{"level":"warn","correlationId":"019f82ad-d97a-…","accountId":"019f82ab-95ad-…","msg":"login fallido"}

Observe el patrón: solo UUIDs y el paso que ocurrió. Con el uuid se cruza contra la base para ver el dato real; el log en sí no filtra nada.

Masking en acción

Si un desarrollador pasa datos sensibles al contexto del log, el helper los enmascara automáticamente. Salida real del logger del proyecto:

{
  "correlationId": "019f8766-f032-749b-b232-2fd887de9ae9",
  "studentId": "019f8764-8fa3-7240-a9ce-0960bf606b96",
  "cedula": "[masked]",
  "firstName": "[masked]",
  "lastName": "[masked]",
  "email": "[masked]",
  "campo": "address",
  "msg": "ficha de alumno actualizada"
}

Campos redactados por defecto: contraseñas, tokens, cédulas, nombres, apellidos, emails, teléfonos, direcciones y fechas de nacimiento — en cualquier nivel de anidación.

Trazabilidad de extremo a extremo

Cada request recibe un correlationId (UUID v7) en el BFF, viaja al core por header, acompaña todos los logs de esa operación y vuelve al cliente:

POST /api/v1/auth/login
HTTP/1.1 201 Created
x-correlation-id: 019f8766-716c-74c2-8f6b-7d57dc18a9a4

Ante un reporte de error del colegio, ese id encadena: request del navegador → logs del BFF → logs del core → registro de auditoría (que guarda el mismo correlationId) → trabajo de cola derivado.

Cómo investigar un incidente

# 1. El usuario reporta un error a las 10:32 — buscar por ventana y nivel
docker logs academic-system-core-1 --since 2026-07-21T10:30:00 | grep '"level":"error"'

# 2. Con el correlationId del paso 1, reconstruir TODA la operación
docker logs academic-system-core-1 | grep '019f8766-716c-74c2-8f6b-7d57dc18a9a4'

# 3. Cruzar contra la auditoría (guarda el mismo correlationId)
docker exec academic-system-postgres-1 psql -U acdadmin -d academic_db \
  -c "SELECT * FROM \"AuditLog\" WHERE \"correlationId\" = '019f8766-…'"

Errores de aplicación pueden además enviarse a Sentry definiendo SENTRY_DSN (opcional, sin cambios de código).