Observabilidad — Guía técnica

Cómo usar el SDK de observabilidad en el código, agregar métricas a nuevos módulos y crear dashboards en Kibana.

SDK de observabilidad

El SDK está en web/api/src/modules/integrations/observability.ts y exporta el objeto obs.

Importar

import { obs } from '../modules/integrations/observability.js';

Logs

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

// Warning
obs.log('warn', 'Stock bajo para artículo', { articuloId: 456, stock: 2 });

// Debug
obs.log('debug', 'Query ejecutada', { sp: 'usp_doc_Factura_List', durationMs: 45 });

Errores

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

Auditoría

// Registrar quién hizo qué
obs.audit('UPDATE_PRICE', {
  userId: req.user.userId,
  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,
});

Performance

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,
});

Eventos de negocio

// Eventos custom para BI dashboards
obs.event('invoice.created', {
  companyId, invoiceId, total: 1500.00, currency: 'USD',
});

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

obs.event('payroll.processed', {
  companyId, employeeCount: 45, totalAmount: 85000,
});

Middleware automático

El middleware en middleware/observability.ts ya registra automáticamente:

Cada HTTP request (método, ruta, status, duración, usuario, IP)
Requests lentos (>1s) van al topic de performance
Errores 5xx van al topic de errores
Eventos de negocio se detectan automáticamente en POST exitosos

Eventos detectados automáticamente

Ruta	Evento
/v1/auth/login	user.login
/v1/facturas	invoice.created
/v1/compras	purchase.created
/v1/clientes	customer.created
/v1/pagos	payment.created
/v1/nomina/procesar	payroll.processed
/v1/pos	pos.sale
/v1/crm/leads	crm.lead.created
/v1/contabilidad/asientos	accounting.entry.created
/v1/support/ticket	support.ticket.created

Agregar observabilidad a un nuevo módulo

Checklist cuando creas un módulo nuevo:

El middleware HTTP ya cubre las rutas automáticamente
Agrega obs.event() para eventos de negocio importantes
Agrega obs.audit() para cambios sensibles (precios, permisos, eliminaciones)
Agrega obs.perf() para operaciones que podrían ser lentas (reportes, queries complejas)
Envuelve errores críticos con obs.error()
Actualiza la tabla de eventos automáticos en middleware/observability.ts

Configuración

Variables de entorno en .env:

KAFKA_ENABLED=true
KAFKA_BROKERS=172.18.0.1:9092
SERVICE_NAME=zentto-api

Si KAFKA_ENABLED no está definido o es false, el SDK hace fallback a console.log. Esto permite desarrollo local sin Kafka.

Kibana — Queries útiles

# Errores de hoy
statusCode:500 AND @timestamp > now-1d

# Requests lentos de una empresa
companyId:5 AND durationMs>1000

# Todos los eventos de facturación
event:"invoice.created"

# Login fallidos
path:"/v1/auth/login" AND statusCode:401

# Auditoría de cambios de precio
action:"UPDATE_PRICE"

# Performance de un SP específico
operation:"sp.usp_doc_Factura_List" AND durationMs>500

Arquitectura de datos