Documentation
Integration Examples/Simple LLM Integration

Simple LLM Integration

Complete working example of basic LLM call tracing with Noveum

This example shows how to trace a basic LLM call using Noveum. You'll learn how to set up tracing, add context, and view results in the dashboard.

🎯 Use Case

Customer Support Chatbot: A simple chatbot that answers customer questions using GPT-4. We'll trace the LLM call to monitor performance, costs, and response quality.

🚀 Complete Working Example

Here's a complete, working example you can copy and run:

import os
import time
from noveum_trace import trace_llm, trace_operation
import openai
import noveum_trace
 
# Initialize Noveum (add this once at the start of your app)
noveum_trace.init(
    api_key=os.getenv("NOVEUM_API_KEY"),
    project="customer-support-bot",
    environment="development"
)
 
def customer_support_bot(user_question: str, customer_id: str = None):
    """
    A simple customer support chatbot that traces LLM calls
    """
    
    # Create a trace for the entire customer interaction
    with trace_operation("customer-support-query") as main_span:
        # Add customer context
        main_span.set_attributes({
            "customer.id": customer_id or "anonymous",
            "query.length": len(user_question),
            "query.type": "customer_support",
            "bot.version": "1.0.0"
        })
        
        # Add start event
        main_span.add_event("customer.query.received", {
            "timestamp": time.time(),
            "query.preview": user_question[:50] + "..." if len(user_question) > 50 else user_question
        })
        
        try:
            # Trace the LLM call
            with trace_llm(model="gpt-4", provider="openai") as llm_span:
                # Add LLM-specific attributes
                llm_span.set_attributes({
                    "ai.model": "gpt-4",
                    "ai.provider": "openai",
                    "ai.temperature": 0.7,
                    "ai.max_tokens": 1000
                })
                
                # Add LLM start event
                llm_span.add_event("ai.completion.started", {
                    "timestamp": time.time(),
                    "prompt.length": len(user_question)
                })
                
                # Make the LLM call
                response = openai.chat.completions.create(
                    model="gpt-4",
                    messages=[
                        {
                            "role": "system", 
                            "content": "You are a helpful customer support assistant. Answer questions clearly and concisely."
                        },
                        {"role": "user", "content": user_question}
                    ],
                    temperature=0.7,
                    max_tokens=1000
                )
                
                # Extract the response
                ai_response = response.choices[0].message.content
                
                # Set usage attributes for cost tracking
                llm_span.set_usage_attributes(
                    input_tokens=response.usage.prompt_tokens,
                    output_tokens=response.usage.completion_tokens
                )
                
                # Add completion event
                llm_span.add_event("ai.completion.finished", {
                    "timestamp": time.time(),
                    "response.length": len(ai_response),
                    "tokens.used": response.usage.total_tokens,
                    "finish.reason": response.choices[0].finish_reason
                })
                
                # Add response attributes
                llm_span.set_attributes({
                    "response.length": len(ai_response),
                    "response.quality": "high" if len(ai_response) > 50 else "low",
                    "cost.usd": response.usage.total_tokens * 0.00003  # Approximate cost
                })
            
            # Add success event
            main_span.add_event("customer.query.answered", {
                "timestamp": time.time(),
                "response.length": len(ai_response),
                "success": True
            })
            
            # Set final status
            main_span.set_status("success")
            
            return ai_response
            
        except Exception as e:
            # Add error event
            main_span.add_event("customer.query.failed", {
                "timestamp": time.time(),
                "error.type": type(e).__name__,
                "error.message": str(e)
            })
            
            # Set error status
            main_span.set_status("error", str(e))
            
            # Return fallback response
            return "I'm sorry, I'm having trouble processing your request right now. Please try again later."
 
# Example usage
if __name__ == "__main__":
    # Set your OpenAI API key
    openai.api_key = os.getenv("OPENAI_API_KEY")
    
    # Example questions
    questions = [
        "How do I reset my password?",
        "What are your business hours?",
        "Can I cancel my subscription?",
        "How do I contact support?"
    ]
    
    # Process each question
    for i, question in enumerate(questions, 1):
        print(f"\n--- Question {i} ---")
        print(f"User: {question}")
        
        response = customer_support_bot(
            user_question=question,
            customer_id=f"cust_{i:03d}"
        )
        
        print(f"Bot: {response}")
        print("-" * 50)

📊 What This Example Does

1. Trace Structure

  • Root Span: customer-support-query - The entire customer interaction
  • Child Span: gpt-4 - The LLM call within the interaction
  • Events: Timeline of what happened during the interaction

2. Attributes Added

  • Customer Context: ID, query length, query type
  • AI Context: Model, provider, temperature, token usage
  • Response Context: Length, quality, cost
  • System Context: Bot version, timestamps

3. Events Tracked

  • Query Received: When the customer asks a question
  • AI Started: When the LLM call begins
  • AI Finished: When the LLM call completes
  • Query Answered: When the response is ready
  • Error Events: If something goes wrong

🎯 Expected Output

When you run this example, you'll see:

--- Question 1 ---
User: How do I reset my password?
Bot: To reset your password, please follow these steps:
1. Go to the login page
2. Click "Forgot Password"
3. Enter your email address
4. Check your email for reset instructions
5. Follow the link to create a new password

If you need further assistance, please contact our support team.
--------------------------------------------------

--- Question 2 ---
User: What are your business hours?
Bot: Our business hours are:
- Monday to Friday: 9:00 AM - 6:00 PM EST
- Saturday: 10:00 AM - 4:00 PM EST
- Sunday: Closed

For urgent matters outside business hours, please email us and we'll respond as soon as possible.
--------------------------------------------------

📈 Dashboard Visualization

In the Noveum dashboard, you'll see:

Trace View

customer-support-query (2.3s)
├── gpt-4 (1.8s)
    ├── ai.completion.started
    ├── ai.completion.finished
    └── customer.query.answered

Span Details

  • Duration: How long each operation took
  • Token Usage: Input and output tokens
  • Cost: Estimated cost of the LLM call
  • Status: Success or error
  • Attributes: All the metadata we added

Events Timeline

  • 10:30:00.000: customer.query.received
  • 10:30:00.100: ai.completion.started
  • 10:30:01.800: ai.completion.finished
  • 10:30:01.900: customer.query.answered

🔧 Customization Ideas

Add More Context

# Add customer tier and region
main_span.set_attributes({
    "customer.id": customer_id,
    "customer.tier": "premium",
    "customer.region": "us-west",
    "query.language": "en",
    "query.sentiment": "neutral"
})

Track Response Quality

# Add quality metrics
llm_span.set_attributes({
    "response.quality_score": calculate_quality_score(ai_response),
    "response.relevance_score": calculate_relevance_score(question, ai_response),
    "response.helpfulness_score": calculate_helpfulness_score(ai_response)
})

Add Business Metrics

# Track business KPIs
main_span.set_attributes({
    "business.metric.resolution_time": time.time() - start_time,
    "business.metric.customer_satisfaction": "high",
    "business.metric.escalation_needed": False
})

🔍 Troubleshooting

Common Issues

"API key not found" error:

# Make sure your environment variables are set
export NOVEUM_API_KEY="your-noveum-key"
export OPENAI_API_KEY="your-openai-key"

"No traces appearing" in dashboard:

  • Wait 30-60 seconds for traces to appear
  • Check that your API key is correct
  • Ensure you're looking at the right project

"OpenAI API error":

  • Verify your OpenAI API key is valid
  • Check that you have credits in your OpenAI account
  • Ensure the model name is correct

🎉 Success Checklist

Before moving on, make sure you can:

  • See your traces in the Noveum dashboard
  • View token usage and cost information
  • Understand the trace timeline
  • Add custom attributes to your traces
  • Handle errors gracefully in your traces

Congratulations! You've successfully traced your first LLM call. This foundation will help you build more complex AI applications with full observability.

Exclusive Early Access

Get Early Access to Noveum.ai Platform

Be the first one to get notified when we open Noveum Platform to more users. All users get access to Observability suite for free, early users get free eval jobs and premium support for the first year.

Sign up now. We send access to new batch every week.

Early access members receive premium onboarding support and influence our product roadmap. Limited spots available.