SDK de servidor

Distribución privada y autorización del collector

# Node.js 22 o superior. Verifica antes el SHA-256 recibido.
npm install --ignore-scripts ./distribuciones/reks-sdk-node-0.2.0.tgz

El paquete ofrece ESM, CommonJS y declaraciones independientes del monorepo. El servidor necesita su credencial revisada y un adaptador de autenticación del collector que compruebe alcance, servicios permitidos, expiración y revocación. Ninguna credencial sintética constituye esa configuración de producción.

Contexto y ciclo de vida explícitos

import { installNodeSDK } from "@reks/sdk-node";

export function createObservability() {
  return installNodeSDK({
    scope: {
      organizationId: "TU_ORGANIZACION",
      projectId: "TU_PROYECTO",
      environment: "preview",
      serviceId: "api",
      releaseId: "TU_RELEASE",
    },
    collectorOrigin: "https://collector.example.test",
    credential: process.env.REKS_SERVER_EVIDENCE_CREDENTIAL,
    privacyPolicy: {
      policyVersion: 1,
      projectId: "TU_PROYECTO",
      allowedRouteTemplates: ["/panel"],
      prohibitedRoutePrefixes: ["/privado"],
      allowedActionSelectors: [],
      prohibitedSelectors: [],
      structuredLogs: {
        schemaVersion: 1,
        minLevel: "info",
        definitions: [{
          code: "panel_saved",
          category: "system",
          attributes: { result: { values: ["ok", "failed"] } },
        }],
      },
    },
  });
}

export async function runExample() {
  const sdk = createObservability();
  try {
    await sdk.run("/panel", async () => {
      sdk.logger.info("panel_saved", { result: "ok" });
    });
  } finally {
    await sdk.shutdown(1500);
  }
}
// REKS_SERVER_EVIDENCE_CREDENTIAL es una variable de TU servidor en este
// ejemplo, no una credencial incluida ni un endpoint ya habilitado.

installNodeSDK es la entrada tolerante a configuración inválida: devuelve un handle inactivo y run/operation siguen ejecutando tu código. createNodeSDK es el constructor estricto para puntos de composición que validan la instalación deliberadamente. Importar no instala captura automática.

El scope no cambia durante la vida del SDK. Mantén instancias y grants revisados por organización/entorno y detén la anterior antes de cambiar de tenant. No tomes un organizationId arbitrario del cuerpo de una petición como autorización.

HTTP, Fastify y trabajos

import { instrumentFastify } from "@reks/sdk-node/fastify";
import type { NodeSDK } from "@reks/sdk-node";

type FastifyTarget = Parameters<typeof instrumentFastify>[0];
export function attachReksToFastify(app: FastifyTarget, sdk: NodeSDK) {
  instrumentFastify(app, sdk); // Una vez, antes de registrar rutas.
}
// En Nest + Fastify, úsalo sobre el adaptador antes de init()/listen().
// No es un adaptador Express ni instala un proveedor OpenTelemetry global.

El adaptador usa AsyncLocalStorage, plantillas routeOptions.url, estado/duración y clase de excepción normalizada. No lee cuerpos, query strings, headers de autorización ni texto del error; no sustituye el manejo de excepciones del host. Una plantilla o método inválido omite evidencia.

run(template, fn, traceparent?) conserva retornos y el mismo objeto lanzado. operation(template, code, fn, attributes?) crea una operación técnica hija y duración/resultado acotados. Un job puede usarla explícitamente; no es un heartbeat firmado ni una confirmación de que un cron se entregó.

No se instala Express ni un proveedor OpenTelemetry global. Para otro logger, mapea códigos/atributos revisados a sdk.logger; no reenvíes registros arbitrarios.

Trazas y excepciones

Sólo se acepta traceparent v00 exacto con IDs hex no nulos y flags instalados. Un valor inválido/futuro inicia una traza nueva. No se propagan baggage, tracestate o identidad. Los IDs técnicos no conceden acceso y no son identificadores de una operación de negocio.

logger.captureException(error, code, attributes) emite un log aprobado; captureException(error) conserva una observación técnica acotada. No se envía el mensaje, stack o cause arbitrario. Evita emitir dos veces una excepción que ya observa tu adaptador de HTTP.

Presupuestos y cierre

flush() hace un intento acotado. shutdown(ms) drena hasta un fallo o deadline; después aborta y descarta pendientes. Los timers no mantienen vivo el proceso. Un append durable parcial puede preceder un timeout: reintentar eventos idénticos reconcilia duplicados, sin afirmar exactly-once.

SIGKILL, process.exit, crash o terminación del host pueden perder pendientes. Conecta el cierre del SDK al lifecycle real de tu servidor. No suprimas excepciones ni cambies el exit code del proceso para aparentar salud.

Qué observar y cómo retirarlo

• Consulta diagnostics locales: selected, rejected, sampledOut, expired, oversize, dropped, queued/pending/sent y bytes.
• Comprueba la política y el grant del servicio antes de interpretar un contador cero como un problema de transporte.
• En cambio de organización/entorno, cierra la instancia anterior; no reutilices su contexto.
• Para desinstalar, retira hooks/wrappers instalados por tu aplicación, ejecuta shutdown con deadline y elimina la dependencia en un release revisado.

• Problemas habitualesInactivo, sin eventos, ACK inválido o credencial no autorizada.