Guía del SDK de Node.js

El SDK de Telemetría de KLA para Node.js (@kla-digital/otel-node) ofrece instrumentación automática de OpenTelemetry lista para usar en flujos de trabajo de Node.js. Se conecta directamente con las herramientas de ejecución más populares, enmascara claves sensibles y comunica metadatos con el KLA Control Plane.

---

Instalación

Instale el paquete de telemetría con el gestor de paquetes de su espacio de trabajo:

pnpm add @kla-digital/otel-node

---

Inicialización básica

Para habilitar la instrumentación automática, debe cargar el módulo del SDK al inicio mismo del ciclo de vida de su aplicación, antes de importar cualquier cliente de modelos (como OpenAI o LangChain).

Cree un archivo llamado instrumentation.ts:

// instrumentation.ts
import { KLAInstrumentation } from '@kla-digital/otel-node';

const kla = new KLAInstrumentation({
  tenantId: process.env.KLA_TENANT_ID || 'default-tenant',
  apiKey: process.env.KLA_API_KEY,
  collectorUrl: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'https://api.kla.digital/collector',
  maskPii: true,
});

kla.start();
console.log('KLA Telemetry initialized.');

Cargue este módulo de instrumentación al iniciar su servidor:

node -r ts-node/register --import ./instrumentation.ts src/index.ts

---

Spans manuales y puntos de control de acciones

Si bien la instrumentación automática captura las solicitudes estándar a la API, puede establecer controles explícitos sobre funciones de alto riesgo mediante spans de transacción personalizados:

import { KLAClient } from '@kla-digital/otel-node';

const client = new KLAClient({ agentId: 'agt_9f81a7' });

async function processPayment(userId: string, amount: number) {
  // Crea un punto de control de auditoría para la acción de pago
  const checkpoint = await client.checkpoint('process_payment', {
    userId,
    amount,
  });

  if (checkpoint.approved) {
    try {
      const receipt = await gateway.charge(userId, amount);
      // Ancla la telemetría de éxito
      await checkpoint.success({ receiptId: receipt.id });
      return receipt;
    } catch (error) {
      await checkpoint.fail(error as Error);
      throw error;
    }
  } else {
    // Escala la revisión
    throw new Error(`Transaction rejected by KLA policy: ${checkpoint.rejectionReason}`);
  }
}