mini-erp/mini-backend/docs/logs-viewing.md

# Visualización de logs

El backend escribe en `logs/backend.log` una línea JSON por evento (ver
[logging-plan.md](logging-plan.md)), con campos como `webUser`, `emp_id`,
`full_name`, `http_method`, `endpoint` y `status_code`. Es el formato
correcto para buscar/cargar en un dashboard, pero incómodo de leer a simple
vista con `cat`/`tail`. Estas son las dos formas recomendadas de verlo
cómodo desde la terminal.

## `jq` — filtrar y colorear en vivo

Instalación: `brew install jq`

```bash
# seguir el log en vivo, con formato e indentación
tail -f logs/backend.log | jq .

# solo las líneas de un empleado puntual (emp_id es string, ej. "11")
tail -f logs/backend.log | jq 'select(.emp_id == "11")'

# solo errores/warnings
tail -f logs/backend.log | jq 'select(.level == "ERROR" or .level == "WARNING")'

# solo llamadas a un endpoint específico
tail -f logs/backend.log | jq 'select(.endpoint == "Items")'

# ver solo unos campos, en una línea por evento
tail -f logs/backend.log | jq -c '{ts: .timestamp, user: .full_name, ep: .endpoint, status: .status_code}'
```

## `lnav` — visor interactivo

Instalación: `brew install lnav`

```bash
lnav logs/backend.log
```

`lnav` detecta el formato JSON automáticamente y da un visor interactivo con:

- colores por nivel (`INFO`/`WARNING`/`ERROR`).
- búsqueda de texto con `/`.
- filtros en vivo con `:filter-in` / `:filter-out` (por ejemplo
  `:filter-in emp_id.:.11` para quedarte solo con el empleado 11).
- queries tipo SQL sobre los campos del log con `;` (por ejemplo
  `;SELECT emp_id, full_name, endpoint, status_code FROM backend_log WHERE level = 'ERROR'`).

Es la opción más cómoda para explorar el log completo o investigar un
incidente puntual sin escribir comandos `jq` largos.

## Dashboard centralizado (a futuro)

Si más adelante se necesita buscar por usuario desde una UI (no la terminal)
o cruzar logs de varios despliegues, la opción estándar es enviar
`logs/backend.log` a algo como Grafana Loki + Promtail. Es infraestructura
adicional, no necesaria mientras el volumen de logs se maneje bien con `jq`/`lnav`.