Guida all'SDK Node.js

Il KLA Node.js Telemetry SDK (@kla-digital/otel-node) offre un'auto-strumentazione OpenTelemetry pronta all'uso per i workflow Node.js. Si aggancia direttamente ai più diffusi strumenti di esecuzione, maschera le chiavi sensibili e comunica i metadati al KLA Control Plane.

---

Installazione

Installa il pacchetto di telemetria con il package manager del tuo workspace:

pnpm add @kla-digital/otel-node

---

Inizializzazione di base

Per abilitare l'auto-strumentazione, devi caricare il modulo dell'SDK all'inizio assoluto del ciclo di vita dell'applicazione, prima di importare qualsiasi client del modello (come OpenAI o LangChain).

Crea un file chiamato 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.');

Carica questo modulo di strumentazione all'avvio del server:

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

---

Span manuali e checkpoint delle azioni

Mentre l'auto-strumentazione cattura le richieste API standard, puoi definire gate espliciti sulle funzioni ad alto rischio utilizzando span di transazione personalizzati:

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

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

async function processPayment(userId: string, amount: number) {
  // Crea un checkpoint di audit per l'azione di pagamento
  const checkpoint = await client.checkpoint('process_payment', {
    userId,
    amount,
  });

  if (checkpoint.approved) {
    try {
      const receipt = await gateway.charge(userId, amount);
      // Ancora la telemetria di successo
      await checkpoint.success({ receiptId: receipt.id });
      return receipt;
    } catch (error) {
      await checkpoint.fail(error as Error);
      throw error;
    }
  } else {
    // Escalation per la revisione
    throw new Error(`Transaction rejected by KLA policy: ${checkpoint.rejectionReason}`);
  }
}