LOGGING.md

Backend Logging Configuration

Files Modified with Comprehensive Logging:

1. app/logger.py (NEW)

• Centralized logging configuration
• Standardized log format with timestamps
• DEBUG, INFO, WARNING, ERROR levels

2. main.py

• Application startup/shutdown logs
• Qdrant initialization logging with error handling
• Root endpoint access logs

3. app/api/v1_endpoints.py

• POST /run endpoint: Request received, execution flow, completion status
• GET /stream endpoint: Stream start, event count, error handling
• Thread ID tracking for request correlation

4. app/agents/researcher.py

• Search plan generation with detailed steps
• Tavily search execution per task with result count
• DuckDuckGo fallback search logging
• Total results collected
• Error logging with full stack trace

5. app/agents/critics.py

• Source verification start with count
• Research summary preparation
• LLM invocation and feedback
• Approval vs Rejection status
• Error handling

6. app/agents/writer.py

• Report generation start
• Research sorting and filtering
• LLM invocation for report creation
• Final report size tracking
• Error handling

7. app/agents/router.py

• Routing decision logic
• State evaluation (iteration count, feedback presence)
• Route path (researcher loop vs writer)

8. app/agents/graph.py

• Graph building and compilation
• Node registration logging

Log Level Usage:

• DEBUG 🐛: Detailed execution flow, intermediate steps
• INFO ℹ️: Major milestones, request start/end, key decisions
• WARNING ⚠️: Non-critical issues, missing configs
• ERROR ❌: Exceptions with full traceback

Emoji Indicators:

• 🚀 Startup
• 📧 API Request
• 🔴 Stream Start
• 🔍 Researcher Agent
• 💼 Research Processing
• 🔎 Search Operations
• 📊 Data Processing
• 🤖 LLM Invocation
• ✅ Success
• ❌ Error
• ⚠️ Warning
• 🔀 Routing Logic

How to Use Logs:

1. Monitor Live: Watch terminal output for real-time flow
2. Debug Issues: Check error logs with full stack traces
3. Track Performance: See timing and counts for each step
4. Verify Integration: Confirm API connections (Tavily, DuckDuckGo, LLMs)

Example Log Output:

[2026-06-09 10:15:30] [INFO] [main:16] 🚀 Application starting...
[2026-06-09 10:15:30] [INFO] [main:18] 📦 Initializing Qdrant vector database...
[2026-06-09 10:15:31] [INFO] [main:20] ✅ Qdrant initialized successfully
[2026-06-09 10:15:35] [INFO] [v1_endpoints:20] 📧 POST /run - Query: Babar Azam in psl... [Thread ID: a1b2c3d4-...]
[2026-06-09 10:15:35] [INFO] [researcher:35] 🔍 Researcher Node: Starting research for query: Babar Azam...
[2026-06-09 10:15:36] [INFO] [researcher:52] 📊 Tavily: Retrieved 6 results
[2026-06-09 10:15:37] [INFO] [researcher:60] 🦆 DuckDuckGo: Retrieved 3 results
[2026-06-09 10:15:38] [INFO] [critic:48] ✅ Critic Node: Sources APPROVED
[2026-06-09 10:15:45] [INFO] [writer:25] ✍️ Writer Node: Starting report generation for 9 sources
[2026-06-09 10:15:55] [INFO] [writer:40] ✅ Report generated: 3450 chars
[2026-06-09 10:15:55] [INFO] [v1_endpoints:31] ✅ Graph execution completed for thread a1b2c3d4-...

This comprehensive logging will help identify:

• Where requests fail
• Which API calls are timing out
• Missing environment variables
• Graph execution flow
• Data aggregation progress