Debugging Index

Last Updated: 2025-12-02 Version: 1.1.0 Audience: Developers, SREs, AI Assistants

Note: Voice/Realtime rows now target the Thinker-Talker pipeline at /api/voice/pipeline-ws. The legacy OpenAI Realtime API is documented separately.

This is the central hub for all VoiceAssist troubleshooting documentation. Use this index to quickly find the right debugging guide, logs, metrics, and runbooks for any subsystem.

Debug by Symptom

AI Agent Playbook

For AI assistants debugging VoiceAssist issues:

Required Information to Collect

1. Error context: Exact error message, timestamp, affected endpoint
2. Logs: Last 100 lines from relevant service (journalctl -u <service> -n 100)
3. Health status: Output of /health and /ready endpoints
4. Recent changes: Any deployments or config changes in past 24h

Standard Investigation Steps

# 1. Check container status
docker ps --filter name=voiceassist
docker logs voiceassist-server --tail 50

# 2. Check recent errors
docker logs voiceassist-server --since "30m" 2>&1 | grep -i error

# 3. Check health endpoints
curl -s https://assist.asimo.io/health | jq
curl -s https://assist.asimo.io/ready | jq

# 4. Check dependencies
docker exec voiceassist-redis redis-cli ping
curl -s http://localhost:6333/collections | jq  # Qdrant

What "Good" vs "Bad" Looks Like

Quick Reference: Subsystem Overview

Debugging Guides by Subsystem

Backend Services

Primary Guide: Backend Debugging

Key Logs:

# API Gateway logs (Docker container)
docker logs voiceassist-server -f

# With error filtering
docker logs voiceassist-server --tail 100 2>&1 | grep -i error

Key Health Endpoints:

• GET /health - Basic health check
• GET /ready - Readiness (includes dependencies)
• GET /metrics - Prometheus metrics

Related Runbooks:

• Production Deployment Runbook
• Disaster Recovery

Frontend (Web App & Admin Panel)

Primary Guide: Frontend Debugging

Key Logs:

• Browser DevTools → Console
• Browser DevTools → Network Tab
• React DevTools → Profiler

Debugging Tools:

• Chrome DevTools
• React Developer Tools extension
• Redux DevTools (if applicable)

Related Documentation:

• Web App Feature Specs
• Admin Panel Feature Specs

Voice & Realtime (WebSocket, STT, TTS)

Primary Guide: Voice & Realtime Debugging

Key Logs:

# Voice service logs (Docker container)
docker logs voiceassist-server --since "10m" 2>&1 | grep -i "websocket\|stt\|tts\|voice"

Key Endpoints:

• Voice Pipeline (T/T): wss://assist.asimo.io/api/voice/pipeline-ws
• Chat Streaming: wss://assist.asimo.io/api/realtime/ws
• Test tools: websocat, wscat

Related Documentation:

• Voice Mode Settings Guide
• Voice Ready State

Documentation Site

Primary Guide: Docs Site Debugging

Key Logs:

# Apache logs for docs site
sudo tail -f /var/log/apache2/assistdocs-error.log
sudo tail -f /var/log/apache2/assistdocs-access.log

Key Health Endpoints:

• GET / - Homepage
• GET /agent/index.json - AI agent discovery endpoint
• GET /agent/docs.json - Documentation list
• GET /agent/tasks.json - Common agent tasks
• GET /agent/schema.json - JSON Schema for API types
• GET /search-index.json - Search index
• GET /sitemap.xml - Sitemap

Related Documentation:

• Agent API Reference
• Agent Onboarding

Infrastructure

Primary Guide: Debugging Overview

Key Services:

# Check all major Docker containers
docker ps --filter name=voiceassist

# Check Apache
sudo systemctl status apache2

# Check systemd for failures
sudo systemctl list-units --failed

Key Health Checks:

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

# Redis
redis-cli ping

# Apache
sudo apachectl configtest

Related Documentation:

• Infrastructure Setup
• Apache Configuration
• SLO Definitions

Key Metrics & Monitoring

Prometheus Metrics (from /metrics)

Application Logs

Log format is structured JSON with trace IDs:

{
  "timestamp": "2025-11-27T12:00:00Z",
  "level": "ERROR",
  "trace_id": "abc123",
  "message": "Database connection failed",
  "service": "api-gateway"
}

Common Investigation Workflows

1. API Error Investigation

1. Check health endpoints: curl /health && curl /ready
2. Review recent errors: docker logs voiceassist-server --tail 100 | grep ERROR
3. Check dependencies: Redis, PostgreSQL, Qdrant
4. Look for trace ID in logs to follow request path

2. Frontend Issue Investigation

1. Open Browser DevTools (F12)
2. Check Console for JavaScript errors
3. Check Network tab for failed API calls
4. Verify environment variables

3. WebSocket/Voice Issue Investigation

1. Test voice pipeline: websocat "wss://assist.asimo.io/api/voice/pipeline-ws?token=..."
2. Check browser console for connection errors
3. Verify Apache WebSocket proxy configuration
4. Check audio permissions in browser

4. Docs Site Investigation

1. Verify static files exist: ls /var/www/assistdocs.asimo.io/
2. Test with explicit .html: curl /ai/onboarding.html
3. Check Apache rewrite rules
4. Run validation: pnpm validate:metadata

Runbooks & Operations

Related Documentation

• Implementation Status - Component status overview
• API Reference - API endpoint documentation
• Backend Architecture - System design
• Service Catalog - Service inventory