Observabilidad — Guía técnica

Zentto utiliza Grafana Loki como plataforma centralizada de observabilidad: recolecta logs de todas las aplicaciones (API, workers, containers) y los pone a disposición en dashboards Grafana. El stack es ligero (~1.2 GB RAM) y está optimizado para correr en el mismo servidor que el ERP sin competir por recursos.

Arquitectura general

Componentes y puertos

Total: ~1.2 GB RAM. Sin restricción de memoria sería ~2-3 GB. Cada contenedor tiene mem_limit para coexistir en el servidor con el ERP.

Flujo de logs

Vía Promtail (stdout/stderr — automático)

1. Cualquier aplicación en Docker escribe a stdout (console.log() en Node.js).
2. Docker captura el log en su daemon JSON driver.
3. Promtail (con acceso a /var/run/docker.sock) descubre containers automáticamente y tailing los logs.
4. Promtail añade labels (container name, stream, compose project) y envía vía HTTP batch push a Loki.
5. Loki almacena en filesystem con retención 7 días.
6. Grafana queryea Loki vía LogQL para visualizar.

Ventaja: Sin cambios en el código de la app. Solo ejecuta console.log() como siempre; Promtail se encarga de recolectar.

Vía @zentto/obs SDK (push directo a Loki)

1. Aplicación importa @zentto/obs y configura OBS_TRANSPORT=loki.
2. SDK recibe llamadas como obs.log(), obs.error(), obs.audit(), obs.perf(), obs.event().
3. SDK acumula eventos en lotes y hace push HTTP directo a Loki en http://172.18.0.1:3101/loki/api/v1/push.
4. Los eventos llegan estructurados como JSON (no solo texto): se pueden queryear by campo.

Ventaja: Estructuración. Un evento obs.event('invoice.created', {...}) llega a Loki con campos indexados (no blob de texto).

Trampa crítica: LOKI_URL

SDK de observabilidad @zentto/obs v2

El SDK unificado de observabilidad exporta las funciones obs.* y el middleware httpMiddleware(obs). Está en npm privado @zentto/obs.

Configuración requerida

# En .env de la API:
OBS_TRANSPORT=loki              # transporte: loki (default) o stdout
LOKI_URL=http://172.18.0.1:3101 # OBLIGATORIO si OBS_TRANSPORT=loki
OBS_BATCH_SIZE=100              # tamaño de lotes antes de push
OBS_BATCH_INTERVAL_MS=5000      # intervalo máximo entre pushes
OBS_TIMEOUT_MS=3000             # timeout de request HTTP a Loki

obs.log(level, message, context)

import { obs } from '@zentto/obs';

obs.log('info', 'Factura creada', {
  facturaId: 123,
  companyId: 1,
  total: 1500.00
});

obs.log('warn', 'Stock bajo', {
  articuloId: 456,
  stock: 2
});

obs.error(error, context)

try {
  await someOperation();
} catch (err) {
  obs.error(err, {
    module: 'ventas',
    operation: 'createInvoice',
    userId: req.user.sub
  });
  throw err;
}

obs.audit(action, context)

obs.audit('UPDATE_PRICE', {
  userId: req.user.sub,        // string (sub del JWT)
  userName: req.user.userName,
  companyId: req.user.companyId,
  module: 'inventario',
  entity: 'Articulo',
  entityId: articuloId,
  before: { precio: 10.00 },
  after: { precio: 15.00 },
  ip: req.ip,
});

obs.perf(operation, durationMs, context)

const start = Date.now();
const result = await callSp('usp_doc_Factura_List', params);
obs.perf('sp.usp_doc_Factura_List', Date.now() - start, {
  companyId,
  rowCount: result.recordset.length,
});

obs.event(eventName, context)

obs.event('invoice.created', {
  companyId,
  invoiceId,
  total: 1500.00,
  currency: 'USD'
});

obs.event('lead.won', {
  companyId,
  leadId,
  value: 25000,
  pipeline: 'CORP'
});

Middleware automático (HTTP observability)

El middleware en middleware/observability.ts usa httpMiddleware(obs) de @zentto/obs y cubre automáticamente todos los endpoints HTTP sin intervención manual:

• Cada HTTP request: log estructurado con método, ruta, status, duración, userId, companyId, IP.
• Requests lentos (mayor a 1s): etiqueta especial perf=true.
• Errores 5xx: log de error con stack trace.
• POSTs exitosos en rutas conocidas: evento de negocio (ej. invoice.created en POST /v1/facturas).

Eventos de negocio detectados automáticamente

Nota sobre userId: El middleware extrae el userId del campo sub del JWT (no de userId). Se almacena como string en Loki para búsquedas exactas.

Loki — Almacenamiento y retención

Promtail — Recolección de Docker

Promtail se conecta a Docker vía socket (/var/run/docker.sock) y descubre containers automáticamente.

Labels automáticos que añade

• container: nombre del container (ej. zentto-api, zentto-notify).
• stream: stdout o stderr.
• project: nombre del proyecto Docker Compose (ej. zentto-observability), si existe.

En LogQL, filtrar por labels

# Todos los logs de zentto-api
{container="zentto-api"}

# Logs de API que son errores (nivel ERROR o error en el texto)
{container="zentto-api"} | regexp "ERROR|error"

# Logs de stderr (líneas de error)
{container="zentto-api", stream="stderr"}

Grafana — Dashboards y queries

URL pública: https://logs.zentto.net

Grafana se conecta a Loki como datasource. Los dashboards usan LogQL (lenguaje de query de Loki, similar a PromQL).

Ejemplos de queries LogQL

Conteo de logs por ruta en las últimas 24 horas

sum by (path) (
  count_over_time({container="zentto-api"} | json [24h])
)

Endpoints más lentos (trampa documentada)

# INCORRECTO — devuelve UNA sola serie con path vacío
topk(10, avg by (path) (
  avg_over_time({container="zentto-api"} | json dur=`durationMs` | unwrap dur [1h])
))

# CORRECTO — salen los 10 endpoints reales con su latencia
topk(10, avg by (path) (
  avg_over_time({container="zentto-api"} | json | unwrap durationMs [1h])
))

Eventos de negocio en el último día

sum by (companyId) (
  count_over_time({container="zentto-api"} | json | eventName="invoice.created" [24h])
)

Configuración del stack Loki

El stack se define en zentto-infra/observability/loki/ con tres archivos de configuración:

• docker-compose.yml: servicios (loki, promtail, grafana) con networks y volumes.
• loki-config.yml: config de Loki (storage, retención, schema).
• promtail-config.yml: config de Promtail (descubrimiento Docker, pipeline).

Variables de la API (.env)

OBS_TRANSPORT=loki                 # "loki" o "stdout" (dev)
LOKI_URL=http://172.18.0.1:3101     # OBLIGATORIO si OBS_TRANSPORT=loki
OBS_BATCH_SIZE=100                  # Eventos antes de flush
OBS_BATCH_INTERVAL_MS=5000          # Intervalo máximo sin activity

Si OBS_TRANSPORT no está definido o es "stdout", el SDK hace fallback a console.log. Esto permite desarrollo local sin Loki.

Operación y troubleshooting

Verificar que el stack está UP

# En el servidor, en el directorio del stack:
docker compose -f observability/loki/docker-compose.yml ps

# Debe mostrar:
# NAME           STATUS
# zentto-loki    Up (healthy)
# zentto-promtail Up
# zentto-grafana Up

Verificar que Loki recibe logs

# Acceder a Grafana: https://logs.zentto.net
# → Connections → Loki (ya configured)
# → Logs
# → Seleccionar labels {container="zentto-api"}
# → Ver últimos logs en tiempo real

Problemas comunes

Ver logs de los servicios

# Logs de Loki
docker compose -f observability/loki/docker-compose.yml logs -f zentto-loki

# Logs de Promtail
docker compose -f observability/loki/docker-compose.yml logs -f zentto-promtail

# Logs de Grafana
docker compose -f observability/loki/docker-compose.yml logs -f zentto-grafana

Checklist para nuevos módulos

1. Middleware HTTP: No requiere acción. El middleware en middleware/observability.ts cubre automáticamente todas las rutas.
2. Eventos de negocio: Si el módulo genera eventos POST, añadir a eventMap en middleware/observability.ts para que se registren automáticamente.
3. Auditoría: Para operaciones sensibles (cambio de precios, permisos), usar obs.audit().
4. Performance: Para operaciones potencialmente lentas (reportes, queries complejas), usar obs.perf().
5. Errores críticos: Para errores que requieran visibilidad inmediata, usar obs.error().
6. Verificación: Hacer un POST en el nuevo endpoint; revisar en Grafana que los logs llegan con los labels correctos.

Migración desde ELK (histórico)