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.