| name | debug-lldb |
| description | Capture and analyze thread backtraces with LLDB/GDB to debug hangs, deadlocks, UI freezes, IPC stalls, or high-CPU loops across any language or project. Use when an app becomes unresponsive, switching contexts stalls, or you need thread stacks to locate lock inversion or blocking calls. |
Debug Lldb
Overview
Capture stack traces from a live process to explain stalls and freezes, then triage for deadlocks, blocking IPC, or tight loops. Prefer repeat sampling so the hang signature is obvious.
Workflow
1) Identify the process
- Use
ps/pgrep to get the PID.
- Prefer the foreground app PID (not the dev server).
2) Capture backtraces (fast path)
- Use the bundled script:
scripts/collect_stacks.sh --pid <pid> --out /tmp/hang --repeat 3 --sleep 0.5- Or by name:
scripts/collect_stacks.sh --name "<process-substring>" --out /tmp/hang
- Run in a separate terminal if the current one is interactive with the hung app.
3) Capture backtraces (manual)
- macOS (LLDB):
lldb -p <pid> -o 'thread backtrace all' -o 'detach' -o 'quit' > /tmp/hang.txt 2>&1
- Linux (GDB):
gdb -q -p <pid> -ex "thread apply all bt" -ex "detach" -ex "quit" > /tmp/hang.txt 2>&1
- Windows:
- Use WinDbg or cdb to capture all-thread backtraces.
4) Triage the hang
- Compare 3–5 samples taken 0.2–1s apart.
- Use
references/triage.md for quick pattern matching (deadlock vs busy loop vs blocking I/O).
5) Attach context
- Include what action triggered the stall and the exact time window.
- Add relevant app logs around the stall.
Resources
scripts/
scripts/collect_stacks.sh - attach to a PID or process name and capture N stack dumps.
references/
references/triage.md - quick patterns for deadlocks, blocking IPC, and busy loops.
