Guía del SDK de Node.js

El paquete del SDK de KLA para Node.js es @kla-digital/otel-node. Inicializa OpenTelemetry, añade los atributos GenAI de KLA y exporta ayudantes para spans de modelo, middleware de tRPC, muestreo y publicación de evaluaciones.

Instalación

npm install @kla-digital/otel-node

Para el inicio rápido con Express:

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

Defina el servicio y el collector antes de que arranque la aplicación:

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

Primera traza con Express

Cargue el SDK antes de Express y de cualquier cliente de modelo.

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

Ejecútelo:

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

Abra KLA Control Plane, vaya al Lineage Explorer y filtre por claims-agent-api. El span debería incluir gen_ai.system, gen_ai.request.model y los atributos de uso de tokens.

LangChain

Habilite el instrumentador de LangChain antes de construir chains, agentes o herramientas.

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

new LangChainInstrumentor().enable();

Para spans de modelo explícitos:

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

Verificación del paquete

El dry-run del paquete del SDK se ejecuta en CI con:

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