rgoussu.dev
rgoussu@goussu: ~/library/java/jdk-and-tools
❯ ~/library/java/jdk-and-tools cat jstack.md

jstack — thread dumps

# Captures platform-thread stack traces with lock and deadlock information; superseded by jcmd, and blind to virtual threads.

Conceptsaved 2026-08-09 #java#jvm#tooling#diagnostics#concurrency

Overview

jstack <pid> prints a snapshot of every platform thread's stack, state and held/awaited monitors — the first tool to reach for when a service hangs, spins at 100% CPU, or a pool is exhausted. Functionally it is jcmd <pid> Thread.print under another name, and jcmd is the recommended spelling nowadays; the reading skills transfer unchanged.

Key points

  • Thread states: RUNNABLE (running or in native I/O), BLOCKED (waiting to enter a synchronized monitor — contention), WAITING/TIMED_WAITING (Object.wait, park, sleep — usually idle pool threads). Lots of BLOCKED on the same monitor = lock contention hotspot.
  • Lock lines: - locked <0x...> (holds monitor), - waiting to lock <0x...> (contends), - parking to wait for <0x...> (j.u.c locks via LockSupport). Matching the hex ids across threads reconstructs who blocks whom.
  • Deadlock detection: the dump ends with Found N Java-level deadlock(s) and the cycle, automatically — for monitors and (via -l) ReentrantLock-style ownable synchronizers.
  • Three dumps, seconds apart: a single dump is a photo, not a diagnosis. Take 3–5 dumps 5–10 s apart; threads still on the same frame across dumps are genuinely stuck (or hot), transient states wash out. Same rule for CPU spins: pair with top -H and match the native tid to the dump's nid=0x....
  • Virtual threads caveat: jstack/Thread.print show platform threads only — carriers appear, but the potentially millions of virtual threads do not. Use jcmd <pid> Thread.dump_to_file -format=json /tmp/td.json (Java 21+), which includes virtual threads grouped by scheduler.
  • -F (force): last resort for a wedged JVM that ignores attach; pauses the process and may produce a degraded dump. Alternative: kill -3 <pid> writes the dump to the JVM's stdout.
  • Same-user attach: like all attach-based tools, must run as the JVM's OS user.

Examples

for i in 1 2 3; do jstack 4242 > td-$i.txt; sleep 7; done
jcmd 4242 Thread.dump_to_file -format=json /tmp/threads.json   # virtual threads included

Related

  • JDK & tools — parent catalogue of the JDK toolchain.
  • jcmd — the modern front-end (Thread.print, Thread.dump_to_file).
  • jmap — companion memory-side snapshot tool.
  • JFR & Mission Control — continuous thread/lock-contention events instead of snapshots.
  • Concurrency & parallelism — the lock and thread-pool concepts dumps expose.