Your First Trace
In this tutorial, you’ll build a simple RAG (Retrieval-Augmented Generation) chatbot that’s fully traced with ThinkHive. By the end, you’ll have:
- A working chatbot with retrieval and LLM calls
- Complete observability into every operation
- Automatic quality evaluation
What We’re Building
Prerequisites
- Node.js 18+ or Python 3.8+
- ThinkHive API key
- OpenAI API key
Project Setup
mkdir thinkhive-demo && cd thinkhive-demo
npm init -y
npm install @thinkhive/sdk openai- package.json
- index.js
- .env
Step-by-Step Implementation
Configure Environment
Create a .env file:
THINKHIVE_API_KEY=thk_your_api_key
OPENAI_API_KEY=sk-your_openai_keyInitialize ThinkHive
index.js
import 'dotenv/config';
import { init, traceLLM, traceRetrieval, traceChain } from '@thinkhive/sdk';
import OpenAI from 'openai';
// Initialize ThinkHive
init({
serviceName: 'rag-demo',
debug: true, // Enable debug logging
});
const openai = new OpenAI();Create a Simple Knowledge Base
index.js
// Simple in-memory knowledge base
const knowledgeBase = [
{
id: 'doc1',
content: 'ThinkHive is an AI observability platform that helps teams monitor and improve their AI agents.',
embedding: [0.1, 0.2, 0.3], // Simplified for demo
},
{
id: 'doc2',
content: 'ThinkHive supports RAG evaluation, hallucination detection, and drift monitoring.',
embedding: [0.2, 0.3, 0.4],
},
{
id: 'doc3',
content: 'ThinkHive integrates with OpenAI, LangChain, and supports OpenTelemetry for tracing.',
embedding: [0.3, 0.4, 0.5],
},
];
// Simple similarity search (in production, use a vector database)
function simpleSearch(query, topK = 2) {
// Return top K documents (simplified - no actual embedding comparison)
return knowledgeBase.slice(0, topK);
}Implement Traced Retrieval
index.js
async function searchDocuments(query) {
// Wrap retrieval in a traced span
const documents = await traceRetrieval({
name: 'knowledge-search',
query: query,
topK: 2,
}, async () => {
const results = simpleSearch(query, 2);
return results;
});
return documents;
}Implement Traced LLM Call
index.js
async function generateResponse(query, context) {
const response = await traceLLM({
name: 'answer-generation',
modelName: 'gpt-4',
provider: 'openai',
input: query,
}, async () => {
const completion = await openai.chat.completions.create({
model: 'gpt-4',
messages: [
{
role: 'system',
content: `You are a helpful assistant. Answer based on this context:\n\n${context}`,
},
{
role: 'user',
content: query,
},
],
temperature: 0.7,
});
return completion;
});
return response.choices[0].message.content;
}Create the RAG Pipeline
index.js
async function ragChat(userQuestion) {
// Wrap entire pipeline in a chain trace
const answer = await traceChain({
name: 'rag-pipeline',
input: { question: userQuestion },
}, async () => {
// Step 1: Retrieve relevant documents
const documents = await searchDocuments(userQuestion);
// Step 2: Build context from documents
const context = documents.map(d => d.content).join('\n\n');
// Step 3: Generate response
const response = await generateResponse(userQuestion, context);
return response;
});
return answer;
}
// Main execution
async function main() {
console.log('Starting RAG Demo...\n');
const questions = [
'What is ThinkHive?',
'What features does ThinkHive support?',
'How does ThinkHive integrate with other tools?',
];
for (const question of questions) {
console.log(`Question: ${question}`);
const answer = await ragChat(question);
console.log(`Answer: ${answer}\n`);
}
console.log('Check your traces at https://app.thinkhive.ai/traces');
}
main().catch(console.error);Run and View Traces
node index.jsWhat You’ll See in ThinkHive
After running your application, open app.thinkhive.ai/traces to see:
Trace Timeline
A visual timeline showing:
- The parent
rag-pipelinechain span - Nested
knowledge-searchretrieval span - Nested
answer-generationLLM span
Span Details
For each span, you’ll see:
- Duration: How long each operation took
- Input/Output: What went in and came out
- Token Usage: For LLM calls
- Retrieved Documents: For retrieval operations
Quality Metrics
ThinkHive automatically evaluates:
- Groundedness: Is the response supported by the retrieved documents?
- Hallucination Risk: Are there unsupported claims?
- Latency Analysis: Where is time being spent?
Next Steps
Congratulations! You’ve built a fully traced RAG application. Now explore:
- RAG Evaluation Guide - Deep dive into quality metrics
- Hallucination Detection - Catch and prevent hallucinations
- JavaScript SDK Reference - Full SDK documentation
- API Reference - REST API for advanced integrations
Pro Tip: Add custom attributes to your spans for richer analysis:
await traceLLM({
name: 'answer-generation',
modelName: 'gpt-4',
provider: 'openai',
metadata: {
customerId: 'cust_123',
channel: 'chat',
intent: 'product_inquiry',
},
}, async () => { /* ... */ });