Node.js SDK Guide

The KLA Node.js SDK package is @kla-digital/otel-node. It initializes OpenTelemetry, adds KLA GenAI attributes, and exports helpers for model spans, tRPC middleware, sampling, and evaluation publishing.

Install

npm install @kla-digital/otel-node

For the Express quickstart:

npm install @kla-digital/otel-node express
npm install --save-dev typescript tsx @types/express

Set the service and collector before the app starts:

export OTEL_SERVICE_NAME=claims-agent-api
export KLA_TENANT_ID=kpmg-reporting
export OTEL_EXPORTER_OTLP_ENDPOINT=<kla-otlp-grpc-endpoint>
export KLA_PII_MASK=true

Express First Trace

Load the SDK before Express and any model clients.

// app.ts
import '@kla-digital/otel-node';

import { SpanStatusCode } from '@opentelemetry/api';
import express from 'express';
import {
  GenAIAttributes,
  addGenAIAttributes,
  tracer,
} from '@kla-digital/otel-node';

const app = express();
app.use(express.json());

app.post('/messages', async (req, res) => {
  const span = tracer.startSpan('agent.reply');

  try {
    const prompt = String(req.body.prompt ?? '');

    addGenAIAttributes(span, {
      [GenAIAttributes.SYSTEM]: 'openai',
      [GenAIAttributes.REQUEST_MODEL]: 'gpt-4o-mini',
      [GenAIAttributes.USAGE_PROMPT_TOKENS]: 24,
      [GenAIAttributes.USAGE_COMPLETION_TOKENS]: 12,
      [GenAIAttributes.USAGE_TOTAL_TOKENS]: 36,
    });

    span.setStatus({ code: SpanStatusCode.OK });
    res.json({ response: `Handled: ${prompt}` });
  } catch (error) {
    span.recordException(error as Error);
    span.setStatus({
      code: SpanStatusCode.ERROR,
      message: error instanceof Error ? error.message : 'unknown error',
    });
    res.status(500).json({ error: 'message_failed' });
  } finally {
    span.end();
  }
});

app.listen(3000);

Run it:

npx tsx app.ts
curl -s http://localhost:3000/messages \
  -H 'content-type: application/json' \
  -d '{"prompt":"Summarize the claim"}'

Open KLA Control Plane, go to Lineage Explorer, and filter by claims-agent-api. The span should include gen_ai.system, gen_ai.request.model, and token usage attributes.

LangChain

Enable the LangChain instrumentor before constructing chains, agents, or tools.

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

new LangChainInstrumentor().enable();

For explicit model spans:

import {
  GenAIAttributes,
  addGenAIAttributes,
  tracer,
} from '@kla-digital/otel-node';

const span = tracer.startSpan('langchain.agent.answer');

try {
  const result = await chain.call({ input: 'Review this transaction' });

  addGenAIAttributes(span, {
    [GenAIAttributes.SYSTEM]: 'openai',
    [GenAIAttributes.REQUEST_MODEL]: 'gpt-4o-mini',
    [GenAIAttributes.USAGE_TOTAL_TOKENS]: result?.usage?.totalTokens,
  });
} finally {
  span.end();
}

Package Verification

The SDK package dry-run runs in CI with:

pnpm --filter @kla-digital/otel-node run pack:dry-run