Guida all'SDK Node.js

Il pacchetto dell'SDK KLA per Node.js è @kla-digital/otel-node. Inizializza OpenTelemetry, aggiunge gli attributi GenAI di KLA ed esporta helper per span di modello, middleware tRPC, campionamento e pubblicazione delle valutazioni.

Installazione

npm install @kla-digital/otel-node

Per il quickstart con Express:

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

Imposta servizio e collector prima dell'avvio dell'applicazione:

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

Prima traccia con Express

Carica l'SDK prima di Express e di qualsiasi client di modello.

// 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);

Eseguilo:

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

Apri KLA Control Plane, vai al Lineage Explorer e filtra per claims-agent-api. Lo span dovrebbe includere gen_ai.system, gen_ai.request.model e gli attributi di utilizzo dei token.

LangChain

Abilita l'instrumentor di LangChain prima di costruire chain, agent o tool.

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

new LangChainInstrumentor().enable();

Per span di modello espliciti:

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

Verifica del pacchetto

Il dry-run del pacchetto SDK viene eseguito in CI con:

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