Node.js SDK Guide

The KLA Node.js Telemetry SDK (@kla-digital/otel-node) provides drop-in OpenTelemetry auto-instrumentation for Node.js workflows. It hooks directly into popular execution tools, masks sensitive keys, and communicates metadata with the KLA Control Plane.

---

Installation

Install the telemetry bundle using your workspace package manager:

pnpm add @kla-digital/otel-node

---

Basic Initialization

To enable auto-instrumentation, you must load the SDK module at the very beginning of your application lifecycle, before importing any model clients (like OpenAI or LangChain).

Create a file named 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.');

Load this instrumentation module when launching your server:

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

---

Manual Spans & Action Checkpoints

While auto-instrumentation captures standard API requests, you can establish explicit gates on high-risk functions using custom transaction spans:

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}`);
  }
}