Node.js SDK Leitfaden

Das KLA Node.js SDK-Paket ist @kla-digital/otel-node. Es initialisiert OpenTelemetry, ergänzt KLA-GenAI-Attribute und exportiert Helfer für Modell-Spans, tRPC-Middleware, Sampling und das Veröffentlichen von Evaluationen.

Installation

npm install @kla-digital/otel-node

Für den Express-Schnellstart:

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

Setzen Sie Service und Collector, bevor die Anwendung startet:

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

Erster Trace mit Express

Laden Sie das SDK vor Express und vor allen Modell-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);

Ausführen:

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

Öffnen Sie die KLA Control Plane, gehen Sie zum Lineage Explorer und filtern Sie nach claims-agent-api. Der Span sollte gen_ai.system, gen_ai.request.model und die Token-Usage-Attribute enthalten.

LangChain

Aktivieren Sie den LangChain-Instrumentor, bevor Sie Chains, Agents oder Tools erstellen.

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

new LangChainInstrumentor().enable();

Für explizite Modell-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();
}

Paketprüfung

Der Dry-Run des SDK-Pakets läuft in CI mit:

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