@habasensei/observability-sdk

SDK ligero en TypeScript/JavaScript para enviar eventos de observabilidad a tu propio backend /ingest.

Forma parte de Cosmo (antes SIEL), una plataforma de observabilidad plug & play para APIs y microservicios.

• Saber rápido qué servicio y endpoint están fallando.
• Medir latencias p50/p95/p99 y error rate sin montar un stack gigante.
• Tener logs de negocio y traces de flujos críticos (checkout, login, pagos) en un dashboard ya armado.

Inspirado en herramientas como Datadog, Sentry y New Relic, pero con un enfoque más simple, barato y directo a APIs.

Cuándo usar este SDK

• Startups, freelancers y equipos pequeños sin SRE dedicado.
• Monolitos o pocos microservicios HTTP donde importa la salud de los endpoints.
• Proyectos que quieren:
  • Requests por minuto.
  • Latencia de endpoints.
  • Error rate y status codes.
  • Logs filtrables por servicio, entorno y nivel.

Cuándo NO es la mejor opción

• Si ya tienes Prometheus + Grafana bien configurados para toda tu infraestructura.
• Si necesitas dashboards ultra custom o métricas a nivel de host/nodo.
• Si tu equipo domina PromQL y el stack clásico de observabilidad.

Instalación

npm install @habasensei/observability-sdk

o con pnpm:

pnpm add @habasensei/observability-sdk

Uso básico

import { init, log } from "@habasensei/observability-sdk";

init({
  apiKey: "tu-api-key",
  service: "checkout-service",
  environment: "production",
  ingestUrl: "http://localhost:3000/ingest"
});

log.info(
  "Pedido actualizado correctamente",
  { orderId: "order_1" },
  { latency: 120, statusCode: 200, traceId: "trace-order-1" }
);

log.warn(
  "Advertencia en checkout",
  { orderId: "order_2", reason: "payment_failed" },
  { latency: 450, statusCode: 500, traceId: "trace-order-2" }
);

log.error(
  "Error en checkout",
  { orderId: "order_2", reason: "payment_failed" },
  { latency: 450, statusCode: 500, traceId: "trace-order-2" }
);

Modelo de datos

Cada evento que envía el SDK sigue un esquema pensado para APIs HTTP:

• service_name: servicio que envía el evento (por ejemplo checkout-service).
• environment: entorno (production, staging, development).
• level: nivel del log (info, warn, error, debug).
• message: mensaje principal.
• latency: tiempo de respuesta o duración total de la ejecución en milisegundos.
• status_code: código HTTP devuelto.
• timestamp: ISO string; si no lo envías, se genera automáticamente.
• metadata: JSON libre con contexto de negocio.
• trace_id: identificador de trace para seguir una petición end-to-end.
• spans: lista opcional de pasos internos con tiempos por función cuando usas breakpoints.

Este modelo es el que el backend usa para construir métricas como:

• Requests por minuto.
• Latencia p50/p95/p99.
• Error rate.
• Top endpoints ruidosos.

Opciones de init

• apiKey (string, requerido): API Key del proyecto en tu plataforma de observabilidad.
• service (string, requerido): nombre del servicio que envía los logs (por ejemplo auth-service).
• environment (string, opcional, por defecto "production"): entorno (production, staging, development, etc.).
• ingestUrl (string, opcional, por defecto "http://localhost:3000/ingest"): URL del endpoint de ingestión.
• batchSize (number, opcional, por defecto 10): cuántos eventos acumular antes de forzar un envío.
• flushInterval (number, opcional, por defecto 5000 ms): intervalo en milisegundos para enviar el buffer aunque no se haya llegado al batchSize.

Métodos disponibles

log.info("mensaje", { extra: "data" });
log.warn("algo raro pasó", { latency: 900 });
log.error("falló algo importante", { code: "E_TIMEOUT" });

Internamente todos llaman a un método log(level, message, metadata?, options?) que construye un evento compatible con el esquema de ingestión y lo envía a ingestUrl mediante peticiones HTTP POST.

El parámetro options te permite enviar información clave para debugging de APIs:

• latency: tiempo de respuesta del endpoint en milisegundos.
• statusCode: código HTTP devuelto al cliente.
• traceId: identificador de trace para seguir una petición end-to-end.
• timestamp: ISO string; si no lo envías, se genera automáticamente.

Tracing y breakpoints en controladores

Además de logs simples, este SDK soporta traces ligeros para medir:

• Tiempo total de un controlador.
• Tiempo entre pasos internos (breakpoints).

Patrón básico para un controller:

log.info(
  "ejemploController",
  {
    orderId: body.body.orderId,
    items: body.body.items
  },
  { traceId: "1234567890" }
);

const carro = retornarCARROEjemplo();

log.breakpoint("retornarCARROEjemplo", carro);

const estado = carro.name === "ejemplo" ? "bien" : "mal";

log.breakpoint("estado_validacion", estado);

log.end({ message: "Ejecución exitosa", statusCode: 200 });

Comportamiento:

• log.info con un tercer argumento inicia un trace interno. Si no envías traceId, el SDK genera uno.
• log.breakpoint(nombre, valor):
  • Registra un span con:
    • name: nombre del paso o función.
    • duration: tiempo desde el último punto.
    • timestamp: momento del breakpoint.
    • meta: el valor que enviaste (recortado si el JSON es demasiado grande).
  • También agrega ese valor al metadata del evento bajo la misma key si el tamaño es razonable.
• log.end:
  • Calcula la duración total del trace desde el log.info.
  • Envía un solo evento con latency total, trace_id y todos los spans.

Límites de seguridad:

• Máximo de 50 breakpoints por ejecución. Si se excede, se escribe en consola:
  • Observability SDK: se ha excedido el número máximo de breakpoints por ejecución.
• El JSON de valor en log.breakpoint se limita a un tamaño aceptable. Si lo supera o no se puede serializar:
  • Observability SDK: has excedido el limite de tamaño del json.
  • En ese caso se guarda solo el nombre y la duración del span sin la metadata pesada.

Este diseño permite:

• Caso simple: medir solo la latencia total de un controlador con log.info + log.end.
• Caso avanzado: añadir breakpoints en funciones clave con log.breakpoint sin cambiar la firma de tus controladores.

Release notes

• 1.1.0:
  • Unificación de tipos y esquemas desde @habasensei/observability-shared dentro del SDK.
  • Nuevo parámetro opcional options en log.* para enviar latency, statusCode, traceId y timestamp.
  • Soporte de traces ligeros con log.info + log.breakpoint + log.end y almacenamiento de spans.