LLM Observability SDK

npm install @usetransactional/llm-node

import { initLlmOps, getLlmOps } from '@usetransactional/llm-node';
 
// Initialize once at startup
initLlmOps({
  dsn: 'https://pk_abc123@api.usetransactional.com/observability/42',
});
 
const llmOps = getLlmOps();
 
// Create a trace for a user interaction
const trace = llmOps.trace({
  name: 'chat-completion',
  input: { message: 'Explain quantum computing' },
  userId: 'user-123',
  tags: ['chat', 'physics'],
});
 
// Record an LLM generation within the trace
const generation = llmOps.generation({
  name: 'openai-response',
  traceId: trace.id,
  modelName: 'gpt-4o',
  input: [{ role: 'user', content: 'Explain quantum computing' }],
  modelParameters: { temperature: 0.7, maxTokens: 1000 },
});
 
// After receiving the LLM response
generation.end({
  output: 'Quantum computing uses quantum bits...',
  promptTokens: 12,
  completionTokens: 150,
  totalTokens: 162,
});
 
trace.end({
  output: { response: 'Quantum computing uses quantum bits...' },
  status: 'success',
});

import { initLlmOps } from '@usetransactional/llm-node';
 
initLlmOps({
  dsn: 'https://pk_abc123@api.usetransactional.com/observability/42',
  debug: true,
});

import { getLlmOps } from '@usetransactional/llm-node';
 
const llmOps = getLlmOps();

import { isInitialized } from '@usetransactional/llm-node';
 
if (isInitialized()) {
  const llmOps = getLlmOps();
  // record observations
}

import { resetLlmOps } from '@usetransactional/llm-node';
 
afterEach(() => {
  resetLlmOps();
});

initLlmOps({
  dsn: 'https://pk_abc123@api.usetransactional.com/observability/42',
});

initLlmOps({
  publicKey: 'pk_abc123',
  projectId: '42',
  baseUrl: 'https://api.usetransactional.com',
});

const llmOps = getLlmOps();
 
const trace = llmOps.trace({
  name: 'customer-support-agent',
  input: { question: 'How do I reset my password?' },
  userId: 'user-456',
  metadata: {
    environment: 'production',
    version: '1.2.0',
  },
  tags: ['support', 'auth'],
});

// Successful completion
trace.end({
  output: { answer: 'Go to Settings > Security > Reset Password' },
  status: 'success',
});
 
// Error completion
try {
  // ... LLM call
} catch (err) {
  trace.error(err);
}

llmOps.updateTrace(trace.id, {
  metadata: { resolvedBy: 'agent-v2' },
  tags: ['resolved'],
});

const generation = llmOps.generation({
  name: 'summarize-article',
  traceId: trace.id,
  modelName: 'gpt-4o',
  input: [
    { role: 'system', content: 'Summarize the following article.' },
    { role: 'user', content: articleText },
  ],
  modelParameters: {
    temperature: 0.3,
    maxTokens: 500,
  },
});
 
// After receiving the response
generation.end({
  output: 'The article discusses...',
  promptTokens: 2048,
  completionTokens: 120,
  totalTokens: 2168,
});

const span = llmOps.span({
  name: 'vector-search',
  traceId: trace.id,
  input: { query: 'password reset instructions', topK: 5 },
});
 
// After the operation completes
span.end({
  output: { results: documents, count: 5 },
});

llmOps.event({
  name: 'user-feedback',
  traceId: trace.id,
  input: { rating: 5, comment: 'Very helpful!' },
});

llmOps.updateObservation(generation.id, {
  metadata: { cached: true },
});

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { getLlmOps } from '@usetransactional/llm-node';
 
const llmOps = getLlmOps();
 
const wrappedGenerateText = llmOps.wrapAiSdk(generateText);
 
const result = await wrappedGenerateText({
  model: openai('gpt-4o'),
  prompt: 'Explain the theory of relativity in simple terms.',
});
 
console.log(result.text);

import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { getLlmOps } from '@usetransactional/llm-node';
 
const llmOps = getLlmOps();
 
const wrappedStreamText = llmOps.wrapStreamText(streamText);
 
const result = await wrappedStreamText({
  model: openai('gpt-4o'),
  prompt: 'Write a poem about observability.',
});
 
for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

import { ChatOpenAI } from '@langchain/openai';
import { TransactionalCallbackHandler } from '@usetransactional/llm-node/langchain';
 
const handler = new TransactionalCallbackHandler({
  sessionId: 'session-abc',
  userId: 'user-123',
});
 
const model = new ChatOpenAI({
  modelName: 'gpt-4o',
  temperature: 0.7,
  callbacks: [handler],
});
 
const response = await model.invoke('What is the capital of France?');
console.log(response.content);

await llmOps.flush();

process.on('SIGTERM', async () => {
  await llmOps.shutdown();
  process.exit(0);
});

export async function handler(event) {
  const llmOps = getLlmOps();
  // ... your logic
  await llmOps.flush();
  return response;
}

initLlmOps({
  dsn: 'https://pk_abc123@api.usetransactional.com/observability/42',
  batchSize: 50,       // Flush sooner under high throughput
  flushInterval: 2000, // Flush every 2 seconds
});

import type {
  TraceHandle,
  ObservationHandle,
  ObservationType,
  ObservationLevel,
  TraceStatus,
} from '@usetransactional/llm-node';