Guide du SDK Node.js

Le paquet du SDK KLA pour Node.js est @kla-digital/otel-node. Il initialise OpenTelemetry, ajoute les attributs GenAI de KLA et exporte des utilitaires pour les spans de modèle, le middleware tRPC, l'échantillonnage et la publication d'évaluations.

Installation

npm install @kla-digital/otel-node

Pour le démarrage rapide avec Express :

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

Définissez le service et le collector avant le démarrage de l'application :

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

Première trace avec Express

Chargez le SDK avant Express et avant tout client de modèle.

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

Exécutez-le :

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

Ouvrez KLA Control Plane, allez dans le Lineage Explorer et filtrez sur claims-agent-api. Le span doit inclure gen_ai.system, gen_ai.request.model et les attributs d'usage de tokens.

LangChain

Activez l'instrumenteur LangChain avant de construire des chains, des agents ou des outils.

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

new LangChainInstrumentor().enable();

Pour des spans de modèle explicites :

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

Vérification du paquet

Le dry-run du paquet SDK s'exécute en CI avec :

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