debug-observer

Debug Observer

Debug issues by gathering context from multiple sources: container logs, database state, cache state, recent git changes, and request execution traces. Auto-detects the infrastructure from the project.

Input

Provide one or more of:

• Entity ID (user ID, order ID, etc.) — trace a specific entity's state
• Endpoint — e.g., POST /api/users — trace request handling
• Error message — search logs and code for the source
• Symptom description — e.g., "user gets 500 on login"

Detection Strategy

Auto-detect infrastructure by scanning for:

• docker-compose.yml — containerized services (get service names)
• go.mod / package.json / requirements.txt — application stack
• redis in docker-compose or config — Redis cache/sessions
• postgres / mysql / mongo in docker-compose or config — database type
• .env files — connection strings and configuration

Investigation Process

Phase 1: Service Health and Recent Errors

1. Check service status (if Docker):

docker compose ps 2>/dev/null || docker-compose ps 2>/dev/null

1. Read recent logs (last 50 lines per service):

docker compose logs --tail=50 <service_name> 2>&1

1. Filter for errors:

docker compose logs --tail=200 <service_name> 2>&1 | grep -iE "error|fatal|panic|fail|exception|traceback"

If not Docker, check:

• Process status: ps aux | grep <service_name>
• Log files: check common locations (/var/log/, logs/, *.log)

Phase 2: Database State

Query relevant tables for the affected entity. Auto-detect database:

PostgreSQL (via docker exec or psql):

docker compose exec postgres psql -U <user> -d <db> -c "SELECT * FROM <table> WHERE id = '<entity_id>' LIMIT 5;"

MySQL (via docker exec or mysql):

docker compose exec mysql mysql -u<user> -p<pass> <db> -e "SELECT * FROM <table> WHERE id = '<entity_id>' LIMIT 5;"

MongoDB (via mongosh):

docker compose exec mongo mongosh <db> --eval "db.<collection>.find({_id: '<entity_id>'})"