Guide du SDK Node.js

Le SDK de télémétrie Node.js de KLA (@kla-digital/otel-node) fournit une auto-instrumentation OpenTelemetry prête à l'emploi pour les workflows Node.js. Il s'intègre directement aux outils d'exécution les plus courants, masque les clés sensibles et échange des métadonnées avec le KLA Control Plane.

---

Installation

Installez le bundle de télémétrie à l'aide du gestionnaire de paquets de votre espace de travail :

pnpm add @kla-digital/otel-node

---

Initialisation de base

Pour activer l'auto-instrumentation, vous devez charger le module du SDK au tout début du cycle de vie de votre application, avant d'importer le moindre client de modèle (comme OpenAI ou LangChain).

Créez un fichier nommé 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.');

Chargez ce module d'instrumentation au lancement de votre serveur :

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

---

Spans manuels et points de contrôle d'action

Si l'auto-instrumentation capture les requêtes API standard, vous pouvez en outre établir des points de contrôle explicites sur les fonctions à haut risque à l'aide de spans de transaction personnalisés :

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

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

async function processPayment(userId: string, amount: number) {
  // Create an audit checkpoint for the payment action
  const checkpoint = await client.checkpoint('process_payment', {
    userId,
    amount,
  });

  if (checkpoint.approved) {
    try {
      const receipt = await gateway.charge(userId, amount);
      // Anchor success telemetry
      await checkpoint.success({ receiptId: receipt.id });
      return receipt;
    } catch (error) {
      await checkpoint.fail(error as Error);
      throw error;
    }
  } else {
    // Escalate review
    throw new Error(`Transaction rejected by KLA policy: ${checkpoint.rejectionReason}`);
  }
}