Docs / Raw

Debugging Overview

Sourced from docs/debugging/DEBUGGING_OVERVIEW.md

Edit on GitHub

Debugging Overview

Last Updated: 2025-11-27 Audience: Developers, SREs, AI Assistants

This guide provides a high-level overview of debugging VoiceAssist components. For detailed component-specific debugging, see the linked documents.

Quick Reference: Where to Look

SymptomFirst Place to CheckDocument
Backend 500 errorsAPI Gateway logsBackend Debugging
Frontend not loadingBrowser console, network tabFrontend Debugging
WebSocket disconnectsRealtime service logsVoice/Realtime
Voice transcription failsSTT service logsVoice/Realtime
Docs site 404sApache rewrite rules, static filesDocs Site
Auth failuresJWT tokens, Redis sessionBackend Debugging
Database connection errorsPostgreSQL logs, connection poolBackend Debugging

Logs and Metrics

Backend Logs

Location: docker logs voiceassist-server -f (VoiceAssist runs in Docker)

Key Log Files:

  • API Gateway: /var/log/api-gateway/ or stdout in container
  • Structured JSON logs with trace IDs

Log Levels:

  • DEBUG - Verbose debugging
  • INFO - Normal operation
  • WARNING - Recoverable issues
  • ERROR - Failures requiring attention
  • CRITICAL - System-level failures

Frontend Logs

Location: Browser Developer Tools → Console

Key Areas:

  • Network tab for API failures
  • Console for JavaScript errors
  • React DevTools for component state

Infrastructure Metrics

Prometheus Metrics: http://localhost:8000/metrics

Key Metrics:

  • http_requests_total - Request counts by endpoint and status
  • http_request_duration_seconds - Latency histogram
  • db_connection_pool_* - Database connection health
  • redis_* - Cache performance
  • rag_* - RAG pipeline metrics

Common Symptoms and Causes

Backend Issues

SymptomLikely Causes
500 Internal Server ErrorUnhandled exception, database timeout, missing config
401 UnauthorizedExpired JWT, missing token, wrong audience
403 ForbiddenInsufficient role, RBAC policy violation
429 Too Many RequestsRate limiting triggered
503 Service UnavailableDependency down (DB, Redis, Qdrant)

Frontend Issues

SymptomLikely Causes
Blank pageJavaScript error, missing env vars, CORS
API calls failingNetwork issues, wrong base URL, auth token expired
State not updatingReact state mutation, missing useEffect deps
Slow renderingUnoptimized re-renders, large lists without virtual

Voice/Realtime Issues

SymptomLikely Causes
WebSocket won't connectCORS, proxy config, SSL termination
Audio not recordingBrowser permissions, MediaRecorder support
Transcription emptySTT service down, audio format unsupported
TTS not playingAudio context suspended, codec issues

Investigation Workflow

1. Reproduce the Issue

# Check container status
docker ps --filter name=voiceassist

# Watch logs in real-time
docker logs voiceassist-server -f

# Test API directly
curl -X GET http://localhost:8000/health
curl -X GET http://localhost:8000/ready

2. Identify the Component

User Request
    ↓
[Frontend] → Check browser console
    ↓
[API Gateway] → Check service logs
    ↓
[Database/Redis/Qdrant] → Check dependency health

3. Check Dependencies

# Database
psql -h localhost -U postgres -d voiceassist -c "SELECT 1"

# Redis
redis-cli ping

# Qdrant
curl http://localhost:6333/collections

4. Review Recent Changes

# Recent commits
git log --oneline -10

# Recent logs from past hour
docker logs voiceassist-server --since "1h"

Relevant Dashboards

DashboardURLPurpose
API Health/health, /readyService health checks
Prometheus Metrics/metricsRaw metrics
Grafana (if configured)http://localhost:3000Visualization
Apache Statushttps://assist.asimo.io/server-statusWeb server metrics

Detailed Debugging Guides

← All documentationHome
Beginning of guide
End of guide