QUICKSTART_TIMING.md

Quick Start: Query Timing

✅ What Was Added

Query timing and performance monitoring is now active in your application. All database queries and API requests are automatically timed and logged.

🚀 How to Use

1. Start Your Application

uvicorn app.app:app --reload --port 8124

2. Watch the Logs

You'll automatically see timing information:

Query Timing:

2025-11-17 10:30:45 INFO sqlalchemy.query.timing Query took 0.678s: SELECT * FROM Projects WHERE Status = 5...
2025-11-17 10:30:46 WARNING sqlalchemy.query.timing SLOW QUERY (1.234s): SELECT COUNT(*) FROM Customers...

Request Timing:

2025-11-17 10:30:47 INFO app.request.timing Request took 1.123s: GET /api/v1/dashboard/widgets/info - Status 200
2025-11-17 10:30:48 WARNING app.request.timing SLOW REQUEST (2.456s): GET /api/v1/projects/ - Status 200

3. Check Response Headers

Every API response includes timing:

curl -v http://localhost:8124/api/v1/projects/
# Look for: X-Process-Time: 0.234

📊 Timing Thresholds

Database Queries

• 🟢 DEBUG (< 500ms): Fast queries - normal
• 🟡 INFO (500ms-1s): Medium queries - monitor
• 🔴 WARNING (>1s): Slow queries - needs attention

API Requests

• 🟢 DEBUG (< 1s): Fast requests - normal
• 🟡 INFO (1s-2s): Medium requests - monitor
• 🔴 WARNING (>2s): Slow requests - needs optimization

⚙️ Configuration

See All Queries

Edit app/core/logging.py:

query_logger.setLevel(logging.DEBUG)  # Show all queries

See Only Slow Queries

query_logger.setLevel(logging.WARNING)  # Show only slow queries

Default (Recommended)

query_logger.setLevel(logging.INFO)  # Show medium and slow queries

🔧 Manual Timing in Code

Add timing to specific operations:

from app.core.timing import timer

# Time a code block
with timer("Complex calculation"):
    result = perform_calculation()

# Or use a decorator
from app.core.timing import timed

@timed("Data processing")
def process_data(data):
    # ... your code ...
    return result

🧪 Test the Feature

Run the Demo

.venv/bin/python examples/query_timing_demo.py

Test with Live API

.venv/bin/python test_query_timing.py

(Make sure your application is running first!)

📖 Full Documentation

• Comprehensive Guide: QUERY_TIMING.md
• Implementation Details: IMPLEMENTATION_SUMMARY.md
• Code Examples: examples/query_timing_demo.py

🎯 What to Look For

1. Slow Queries: Look for WARNING logs with "SLOW QUERY"
2. Slow Endpoints: Look for WARNING logs with "SLOW REQUEST"
3. Response Headers: Check X-Process-Time in API responses
4. Pattern Analysis: Track which endpoints are consistently slow

💡 Next Steps

1. ✅ Run your application normally
2. ✅ Monitor logs for slow operations
3. ✅ Identify bottlenecks from WARNING messages
4. ✅ Optimize slow queries and endpoints
5. ✅ Set up alerts for production monitoring

🐛 Troubleshooting

Not seeing timing logs?

• Check that your app is running with uvicorn
• Verify LOG_LEVEL is set to INFO or DEBUG
• Look for logs with "sqlalchemy.query.timing" or "app.request.timing"

Want to disable timing?

• Set query_logger level to ERROR in app/core/logging.py
• Comment out the event listeners in app/db/session.py

✨ Benefits

• 🎯 Zero Code Changes: Works automatically with all existing queries
• 📊 Actionable Data: Clear indicators of what needs optimization
• 🔍 Production Ready: Minimal overhead, can be tuned per environment
• 📈 Scalable: Ready to integrate with monitoring tools (Prometheus, Datadog, etc.)

---

That's it! Your application now automatically tracks and logs query performance. Just run it and watch the logs! 🚀