126 lines
4.0 KiB
Markdown
126 lines
4.0 KiB
Markdown
# 01 — Trazas de Log y Centralización
|
|
## Estándar obligatorio de logging para Server Components, Client Components y API Routes
|
|
|
|
> **Uso:** Todo flujo, acción crítica del usuario (login, logout, accesos denegados) o error de integración DEBE registrar un log con el formato estándar del proyecto.
|
|
|
|
---
|
|
|
|
## 1. Arquitectura de Logs de Frontend
|
|
|
|
La aplicación utiliza un sistema centralizado de logs que asegura que todas las trazas (tanto del cliente como del servidor) queden consolidadas en el servidor en el archivo `logs/app.log`.
|
|
|
|
```
|
|
[Client Component] (use client)
|
|
│ (llama a client-logger)
|
|
▼
|
|
POST /api/logs
|
|
│
|
|
▼
|
|
[Route Handler] (app/api/logs/route.ts)
|
|
│
|
|
▼
|
|
[Server Logger] (lib/logger/server-logger.ts) ──► Escribe en logs/app.log
|
|
▲
|
|
│ (llamada directa)
|
|
[Server Component / API Route]
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Formato de las Trazas
|
|
|
|
El formato estándar del log es una sola línea estructurada para facilitar búsquedas y parseos:
|
|
|
|
```
|
|
[<Timestamp-ISO>] [<LEVEL>] <Mensaje-Descriptivo> | <Metadata-JSON>
|
|
```
|
|
|
|
### Niveles Aceptados:
|
|
- **`[INFO]`**: Acciones exitosas y flujos de negocio normales (ej. Login exitoso, Logout).
|
|
- **`[WARN]`**: Acciones sospechosas, intentos fallidos o no autorizados (ej. Login fallido, Acceso denegado a dashboard).
|
|
- **`[ERROR]`**: Fallos técnicos críticos, excepciones de red o integración (ej. Backend Spring Boot caído, fallo de descompresión).
|
|
|
|
---
|
|
|
|
## 3. Uso Práctico
|
|
|
|
### 3.1 Desde Server Components y API Route Handlers
|
|
En el servidor, importamos y llamamos directamente al `server-logger`:
|
|
|
|
```typescript
|
|
import { logInfo, logWarn, logError } from '@/lib/logger/server-logger';
|
|
|
|
// Registro de flujo regular (INFO)
|
|
logInfo('Usuario inició sesión exitosamente', { userId: '123', email: 'juan@banesco.com' });
|
|
|
|
// Intento de acceso fallido (WARN)
|
|
logWarn('Acceso no autorizado a dashboard', { redirectTo: '/login', path: '/dashboard' });
|
|
|
|
// Fallo de backend (ERROR)
|
|
logError('Error al conectar con el backend de Spring Boot', { error: 'ECONNREFUSED', endpoint: '/api/auth/me' });
|
|
```
|
|
|
|
### 3.2 Desde Client Components ('use client')
|
|
En el cliente, importamos `client-logger` que se encarga asíncronamente de enviar la traza al backend local mediante `POST /api/logs`:
|
|
|
|
```typescript
|
|
'use client';
|
|
import { logInfo, logWarn, logError } from '@/lib/logger/client-logger';
|
|
|
|
function FormularioTransferencia() {
|
|
const handleConfirmar = () => {
|
|
// Logueamos la acción en el cliente (viajará al servidor automáticamente)
|
|
logInfo('Click en confirmar transferencia', { monto: 1500, moneda: 'USD' });
|
|
};
|
|
|
|
const handleValidacionFallida = () => {
|
|
logWarn('Validación de saldo insuficiente en cliente', { saldoDisponible: 200, montoRequerido: 1500 });
|
|
};
|
|
|
|
return (
|
|
// ... JSX
|
|
);
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Estructura de la API Route de Logs (`app/api/logs/route.ts`)
|
|
|
|
La API `/api/logs` es el proxy encargado de recibir los logs del cliente. Debe validar que la petición no esté vacía y pasarla inmediatamente al `server-logger`:
|
|
|
|
```typescript
|
|
import { NextRequest, NextResponse } from 'next/server';
|
|
import { logInfo, logWarn, logError } from '@/lib/logger/server-logger';
|
|
|
|
export async function POST(req: NextRequest) {
|
|
try {
|
|
const { level, message, metadata } = await req.json();
|
|
|
|
switch (level.toUpperCase()) {
|
|
case 'INFO':
|
|
logInfo(message, metadata);
|
|
break;
|
|
case 'WARN':
|
|
logWarn(message, metadata);
|
|
break;
|
|
case 'ERROR':
|
|
logError(message, metadata);
|
|
break;
|
|
default:
|
|
logInfo(`[CLIENT-LOG] ${message}`, metadata);
|
|
}
|
|
|
|
return NextResponse.json({ status: 'success' }, { status: 200 });
|
|
} catch (err: any) {
|
|
return NextResponse.json({ error: 'Fallo al procesar logs en el proxy' }, { status: 500 });
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Reglas de Seguridad en Logs
|
|
- **NUNCA** guardes contraseñas de usuario, tokens JWT, llaves secretas o números de tarjeta de crédito (PAN) completos en los logs.
|
|
- Aplica mascarado de datos sensibles en el metadata (ej. `{"email": "ju***@banesco.com"}`).
|