Node.js SDK Leitfaden

Das KLA Node.js Telemetry SDK (@kla-digital/otel-node) bietet eine sofort einsatzbereite OpenTelemetry-Auto-Instrumentierung für Node.js-Workflows. Es klinkt sich direkt in gängige Ausführungstools ein, maskiert sensible Schlüssel und tauscht Metadaten mit der KLA Control Plane aus.

---

Installation

Installieren Sie das Telemetry-Bundle mit dem Paketmanager Ihres Workspace:

pnpm add @kla-digital/otel-node

---

Grundlegende Initialisierung

Um die Auto-Instrumentierung zu aktivieren, müssen Sie das SDK-Modul ganz am Anfang des Lebenszyklus Ihrer Anwendung laden, noch bevor Sie irgendwelche Modell-Clients (wie OpenAI oder LangChain) importieren.

Erstellen Sie eine Datei namens 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.');

Laden Sie dieses Instrumentierungsmodul beim Start Ihres Servers:

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

---

Manuelle Spans & Aktions-Checkpoints

Während die Auto-Instrumentierung standardmäßige API-Anfragen erfasst, können Sie für risikoreiche Funktionen explizite Gates über benutzerdefinierte Transaktions-Spans einrichten:

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

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

async function processPayment(userId: string, amount: number) {
  // Erstellt einen Audit-Checkpoint für die Zahlungsaktion
  const checkpoint = await client.checkpoint('process_payment', {
    userId,
    amount,
  });

  if (checkpoint.approved) {
    try {
      const receipt = await gateway.charge(userId, amount);
      // Verankert die Erfolgstelemetrie
      await checkpoint.success({ receiptId: receipt.id });
      return receipt;
    } catch (error) {
      await checkpoint.fail(error as Error);
      throw error;
    }
  } else {
    // Eskaliert zur Prüfung
    throw new Error(`Transaction rejected by KLA policy: ${checkpoint.rejectionReason}`);
  }
}