SDK Integration Guide

Integrate Noveum.ai tracing into your AI applications with Python or TypeScript SDKs

The Noveum.ai SDKs provide comprehensive tracing and observability for your AI applications with minimal code changes. Whether you're building LLM applications, RAG systems, or multi-agent workflows, our SDKs automatically capture essential metrics and traces.

🚀 Quick Start

1. Create Your Account & Get API Key

Sign up at noveum.ai
Create a project in your dashboard
Generate an API key from the integration page
Choose your SDK based on your application language

2. Install the SDK

pip install noveum-trace

Requirements: Python 3.8+

3. Initialize the Client

import noveum_trace
import os
 
# Initialize once at app startup
noveum_trace.init(
    api_key=os.getenv("NOVEUM_API_KEY"),
    project="my-ai-app",
    environment="production",  # or "development", "staging"
)

Environment Variables:

export NOVEUM_API_KEY="your-api-key"
export NOVEUM_PROJECT="my-ai-app"
export NOVEUM_ENVIRONMENT="production"

🎯 Basic Usage

Trace LLM Calls

import openai
from noveum_trace import trace_llm
 
@trace_llm
def generate_response(prompt: str) -> str:
    """Automatically traces this LLM call"""
    response = openai.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": prompt}],
        temperature=0.7
    )
    return response.choices[0].message.content
 
# Usage
result = generate_response("Explain quantum computing")
# ✅ Automatically tracked: latency, cost, tokens, model, etc.

Alternative - Context Manager:

with noveum_trace.trace_llm_call("gpt-4-completion") as span:
    span.set_attribute("user.id", user_id)
    span.set_attribute("prompt.length", len(prompt))
 
    response = openai.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": prompt}]
    )
 
    span.set_attribute("response.length", len(response.choices[0].message.content))
    return response.choices[0].message.content

Trace RAG Pipelines

@noveum_trace.trace("rag-pipeline")
def answer_question(question: str) -> str:
    # Step 1: Generate embeddings
    with noveum_trace.trace_step("generate-embeddings") as step:
        embeddings = get_embeddings(question)
        step.set_attribute("embedding.model", "text-embedding-ada-002")
        step.set_attribute("embedding.dimensions", len(embeddings))
 
    # Step 2: Retrieve documents
    with noveum_trace.trace_step("retrieve-documents") as step:
        documents = vector_search(embeddings, k=5)
        step.set_attribute("documents.retrieved", len(documents))
        step.set_attribute("documents.sources", [doc.source for doc in documents])
 
    # Step 3: Generate answer
    with noveum_trace.trace_step("generate-answer") as step:
        context = "\n".join([doc.content for doc in documents])
 
        @noveum_trace.trace_llm
        def generate_with_context(question: str, context: str) -> str:
            return openai.chat.completions.create(
                model="gpt-4",
                messages=[
                    {"role": "system", "content": f"Answer based on this context: {context}"},
                    {"role": "user", "content": question}
                ]
            ).choices[0].message.content
 
        answer = generate_with_context(question, context)
        step.set_attribute("answer.length", len(answer))
        return answer
 
# Usage
answer = answer_question("What is the capital of France?")

🔧 Framework Integrations

Next.js Integration

// app/api/chat/route.ts
import { withNoveumTracing } from '@noveum/trace/integrations/nextjs';
 
export const POST = withNoveumTracing(
  async (request: Request) => {
    const { message } = await request.json();
 
    // Your AI logic here - automatically traced
    const response = await processMessage(message);
 
    return Response.json({ response });
  },
  {
    spanName: 'chat-completion',
    captureRequest: true,
    captureResponse: true,
  }
);

Express.js Integration

import express from 'express';
import { noveumMiddleware } from '@noveum/trace/integrations/express';
 
const app = express();
 
// Add tracing middleware
app.use(noveumMiddleware({
  captureRequest: true,
  captureResponse: true,
  ignoreRoutes: ['/health', '/metrics'],
}));
 
app.post('/chat', async (req, res) => {
  // All requests automatically traced
  const response = await processMessage(req.body.message);
  res.json({ response });
});

FastAPI Integration (Python)

from fastapi import FastAPI
from noveum_trace.integrations.fastapi import NoveumMiddleware
 
app = FastAPI()
 
# Add tracing middleware
app.add_middleware(NoveumMiddleware)
 
@app.post("/chat")
@noveum_trace.trace("chat-endpoint")
async def chat(message: str):
    # Automatically traced
    response = await process_message(message)
    return {"response": response}

📊 Advanced Features

Custom Attributes & Events

@noveum_trace.trace("user-interaction")
def handle_user_request(user_id: str, request: str):
    # Add custom attributes
    noveum_trace.set_attribute("user.id", user_id)
    noveum_trace.set_attribute("user.plan", get_user_plan(user_id))
    noveum_trace.set_attribute("request.category", classify_request(request))
 
    # Add events
    noveum_trace.add_event("request.received", {
        "timestamp": datetime.now().isoformat(),
        "request.length": len(request)
    })
 
    try:
        result = process_request(request)
        noveum_trace.add_event("request.completed", {
            "success": True,
            "response.length": len(result)
        })
        return result
    except Exception as e:
        noveum_trace.add_event("request.failed", {
            "error.type": type(e).__name__,
            "error.message": str(e)
        })
        raise

Sampling Configuration

# Python
noveum_trace.init(
    api_key="your-api-key",
    project="my-app",
    sampling_rate=0.1,  # Sample 10% of traces
    sampling_rules=[
        {"trace_name": "health-check", "rate": 0.01},  # 1% for health checks
        {"trace_name": ".*error.*", "rate": 1.0},      # 100% for errors
    ]
)

// TypeScript
const client = initializeClient({
  apiKey: 'your-api-key',
  project: 'my-app',
  sampling: {
    rate: 0.1, // 10% default sampling
    rules: [
      { traceNamePattern: 'health-check', rate: 0.01 }, // 1% for health
      { traceNamePattern: '.*error.*', rate: 1.0 },     // 100% for errors
    ],
  },
});

🔗 What's Captured Automatically

📊 Performance Metrics: Latency, throughput, error rates
💰 Cost Tracking: Token usage, API costs across providers
🔍 Request/Response: Configurable capture of inputs/outputs
🏷️ Metadata: Model names, parameters, user context
🌊 Context Flow: Trace relationships across services
🐛 Error Details: Stack traces, error classification

📈 View Your Data

Once integrated, visit your Noveum Dashboard to:

🔍 Search & Filter traces by any attribute
📊 Analyze Performance trends and bottlenecks
💰 Monitor Costs across different models and providers
🐛 Debug Issues with detailed trace timelines
👥 Collaborate with your team on insights

🔒 Security & Privacy

🔐 Encryption: All data encrypted in transit and at rest
🎛️ Configurable Capture: Control what data is collected
🏠 Data Residency: Choose your data storage region
⏰ Retention Control: Set custom data retention policies

Next Steps

Tracing Concepts - Learn about traces, spans, and observability best practices
Framework Integrations - Deep dive into specific framework setups
Multi-Agent Tracing - Observe complex agent workflows
Dashboard Guide - Master the Noveum platform interface