Diagnose a Hanging App with sample

01Command

$ sample TextEditor 5 -file /tmp/hang-sample.txt

02What it does

sample attaches to a running process and repeatedly records the call stack of every thread, then writes a self-contained report showing exactly which function the app is stuck in — for example waiting on a lock, a network call, or disk I/O. It needs no Xcode and is the standard first artifact to capture when an app beachballs; the top of the report highlights the heaviest stack. Get the process name from Activity Monitor or use the numeric PID instead of the name.

03Risk

04Undo

✓No undo needed — this command does not change persistent state.

05Sources

• sample(1) macOS man page
  unix.com · technical · 2026-09-17
  Evidence: Man page for sample: samples the call stack of a running process for a duration and writes a report file.
• Technical Note TN2124: Mac OS X Debugging Magic
  Apple · vendor-doc · 2026-09-17
  Evidence: Apple's overview of macOS debugging tools including sample, used to capture where a hung process is stuck.

Last verified: 2026-09-18 · Category: Developer

06Related solutions