| name | debug-logs |
| description | Analyze Volatio debug logs from /tmp/volatio-debug/. Use when the user asks to check debug logs, analyze problems, or diagnose simulation issues. |
Debug Log Analysis
Read and analyze debug logs to diagnose problems in the simulation pipeline, Python worker, or API.
Log Files
All in /tmp/volatio-debug/:
| File | Source | What it captures |
|---|
debug-YYYY-MM-DD.log | TypeScript DEBUG() | Processor, simulate endpoint, bridge calls |
bridge-YYYY-MM-DD.log | FlowRegimeBridge | IPC requests/responses sent to Python worker |
worker-YYYY-MM-DD.log | Python DEBUG() | Signal generation, cache lookups, price fetches |
How to Read Logs
- Read all three log files for today (or most recent date with content)
- Events are chronological within each file — cross-reference by timestamp
- Bridge logs show the request/response boundary between Node.js and Python
How to Clear Logs
rm -f /tmp/volatio-debug/*.log
How to Tail Logs Live
tail -f /tmp/volatio-debug/*.log
How to Enable/Disable
DEBUG is on by default in development. To disable:
DEBUG_LOGGING=false bun run dev
How to Strip DEBUG Calls for Production
bun run scripts/remove-debug-logs.ts
bun run scripts/remove-debug-logs.ts --dry-run
Common Problems to Look For
| Pattern in logs | Meaning | Fix |
|---|
0 signals generated | No symbols matched or cache empty | Check symbols list and cache data |
'dict' object is not callable | Python DEBUG() missing lambda: wrapper | Wrap 3rd arg: DEBUG("loc", "msg", lambda: {...}) |
No cached data found | Z-score cache not seeded for date range | Run Phase A first, or seed with seed_zscore_cache.py |
no price for SYMBOL | Minute bars missing for that symbol/date | Check Polygon data availability |
Phase A failed or Phase A timed out | REST API fetch failed | Check Massive API connectivity |
BLOCKED in trade decisions | Signals filtered by entry rules | Check max_positions, no_existing_position in decisions |
symbols: [] or symbols: null | Session has no flowRegimeConfig.symbols | This is OK — empty means "use all clusters" |
DEBUG() Call Signatures
TypeScript:
DEBUG('message')
DEBUG('location', 'message')
DEBUG('location', () => ({ data: value }))
DEBUG('location', 'message', () => ({ data: value }))
Python:
DEBUG('message')
DEBUG('location', 'message')
DEBUG('location', lambda: {'data': value})
DEBUG('location', 'message', lambda: {'data': value})
The 3rd argument in Python MUST be a lambda:, never a raw dict.
