Documentación

Estiaje recibe lo que pasó en tu código y lo que le importa a tu negocio en un mismo río. Esta página es todo lo que necesitas: se lee en quince minutos y no hay una segunda parte escondida.

Instalar

npm install @estiaje/sdk

Cero dependencias. Node 18 o superior. Funciona igual en una API, en un front empaquetado y en una lambda.

Tu primer evento

ESTIAJE_URL=https://tu-estiaje.example.com
ESTIAJE_TOKEN=ck_live_…

import { estiajeFromEnv } from '@estiaje/sdk';

// UNO por proceso. No uno por request, ni uno por archivo.
export const estiaje = estiajeFromEnv({ service: 'mi-api' });

estiaje.log('usecase.ok', { usecase: 'GetVisits', ms: 128 });

Los tres verbos

La diferencia no es de estilo: decide cuánto vive cada cosa y qué preguntas vas a poder contestar dentro de un año.

También hay warn(), error() y fatal(): son log con severidad.

Nombra por lo que ocurrió, no por dónde ocurrió

order.created, no PedidoController.done. El nombre sobrevive al refactor; la ruta del archivo, no. Y en los eventos de negocio incluye siempre el identificador de la cosa (task_id, order_id, sn): es lo que permite emparejar el inicio con el final.

Contexto y linaje

El hilo, la entidad, el actor y las etiquetas del request no se escriben en cada llamada. Se declaran una vez y se pegan solos a todo lo que se emita.

estiajeFromEnv({
  service: 'api-pedidos',
  context: () => ({
    trace_id: hiloActual(),        // del interceptor / AsyncLocalStorage
    entity:   'sucursal:polanco',     // el ancla: la cosa del mundo real
    actor:    usuarioActual(),
    attrs:    { session_id, module: 'checkout' },
    geo:      posicionActual(),
  }),
})

Si el front manda su cabecera traceparent y tu interceptor la respeta, la misma traza va del click del usuario hasta la lambda sin que ningún caso de uso escriba un trace_id jamás. Eso es lo que dibuja el viaje.

Tus etiquetas nunca chocan con las del contexto

Si ambos traen la misma clave con distinto valor, gana la tuya y la del contexto se conserva con el sufijo _ctx. Nada se pisa en silencio.

Etiquetas (attrs)

Los attrs son pares clave/valor con los que después vas a buscar. Pueden ser texto, número o booleano — y si mandas otra cosa, el SDK no tira el evento: lo degrada con gracia y lo marca.

El atributo _coerced lista qué claves se degradaron. La idea es que el dato sucio sea visible y corregible, no invisible. Si tienes un objeto grande que sí quieres conservar entero, va en el tercer parámetro (body), que se guarda como JSON completo.

Dónde pasó: geo

geo no es un attr: es parte del sobre, como entity o trace_id. Puede ir en el evento o en el contexto, y las dos formas terminan igual.

estiaje.event('order.created', {
  geo: { lat: 25.6866, lon: -100.3161 },  // acc opcional, en metros
  slots: 8,
});

Solo lo que ocurre en un lugar real lo necesita: una visita, una venta, una tarea cerrada en sitio. Lo que pasa dentro del servidor, no. El territorio nunca inventa una posición: si un evento no la trae, lo dice.

Destinos (sinks)

Esta es la idea central del SDK: la declaración es estable y dura años; el destino es configuración. Manda a Estiaje, a la consola, a cualquier backend OTLP — Sentry, Datadog, Grafana — o a los cuatro a la vez.

import { createEstiaje, sinkConsole, sinkOtlp } from '@estiaje/sdk';

createEstiaje({
  service: 'mi-api',
  url: process.env.ESTIAJE_URL, token: process.env.ESTIAJE_TOKEN,
  sinks: [
    'estiaje',
    sinkConsole(),
    sinkOtlp('https://…ingest.sentry.io/api/…/otlp/v1/logs'),
    { name: 'mío', send: (evs) => miLogger.info(evs) },
  ],
})

Un sink tuyo solo necesita dos cosas:

interface EstiajeSink {
  name: string;
  send(events: EstiajeEvent[]): void | Promise<void>;
  immediate?: boolean;   // true = sin esperar al lote (así es la consola)
}

Variables de entorno

La copia a consola está encendida a propósito: se ve en desarrollo, y en AWS CloudWatch la captura sin configurar nada. Se apaga con ESTIAJE_ECHO=0 o echo: false.

Expectativas

Un error se ve. Un proceso que se quedó a la mitad no hace ruido. Las expectativas son la forma de enterarte del silencio sin escribir una línea de código extra.

Se declaran donde vive la operación, no en el código:

{
  "id":         "pedido-completo",
  "name":       "Pedido creado → pedido completado",
  "when":       "order.created",
  "expects":    "order.completed",
  "fails":      ["sales.rejected", "etl.failed"],
  "match_by":   "attrs.order_id",
  "window_min": 30,
  "severity":   "error"
}

Cada abridor termina en uno de tres finales, y solo uno se anuncia:

Y si tu código detecta que el proceso se truncó, dilo: estiaje.outcome('task.canceled', { task_id }). Un final malo declarado es información; lo que no sirve es el silencio.

Retención y cuotas

Los log son ruido y se borran según tu plan. Los event y outcome se conservan, porque son los que contestan preguntas de negocio meses después. Además hay un rollup por minuto que sobrevive al borrado: el volumen y la salud de cada servicio siguen ahí aunque el detalle ya no esté.

La cuota se cobra antes de leer el cuerpo de la petición — un lote enorme no te cuesta CPU si ya te pasaste. Si excedes, la puerta responde 429 con Retry-After, y el SDK reintenta solo.

API HTTP

El SDK es comodidad, no obligación. Todo se puede hacer con curl. La credencial va en Authorization: Bearer, y la organización sale siempre de la credencial — nunca del payload ni de un parámetro.

Mandar eventos

curl -X POST https://tu-estiaje/v1/events \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer ck_live_…' \
  -d '[{"service":"mi-api","kind":"event","name":"order.created",
       "attrs":{"order_id":"AND-8821"}}]'

Acepta un objeto o un arreglo. Responde 202 con {accepted, deduped, rejected[]}: un evento malo no tumba el lote — se rechaza solo él, con su índice y su razón.

Consultar

Dos tipos de credencial

Qué NO hacer

• No crear un cliente por request o por archivo. Uno por proceso.
• No envolver estiaje.* en try/catch. El SDK jamás lanza.
• No hacer await de log/event/outcome: son síncronos y fire-and-forget. Lo único que se espera es flush(), al apagar el proceso y al final de una lambda.
• No escribir space en cada evento: viene de la credencial.
• No inventar plazos ni "abrir/cerrar flujos" en el código. Los plazos los define la operación en las expectativas.