Threadscope

An offline JVM thread-dump workbench, built with Java and Swing.

A service is stuck. You have a thread dump, but the useful evidence is buried in hundreds of stack traces. Threadscope turns that snapshot into a searchable thread table, monitor wait graph, stack groups, and a report you can keep with an incident.

Run it

Requires JDK 17 or newer. No Maven, Gradle, or third-party runtime dependencies.

# Linux / macOS
sh build.sh
java -jar build/threadscope.jar

# Windows PowerShell
./build.ps1
java -jar build/threadscope.jar

The build runs the parser tests and packages the application. The initial view loads a synthetic incident with two threads in a monitor cycle and two requests queued behind them. The fixture is intentionally small enough to audit by hand.

Capture a real snapshot with your JDK's jcmd <pid> Thread.print -l, save its text as UTF-8, and open it using Open dump, Ctrl+O, or drag-and-drop. You can also pass the path on launch:

java -jar build/threadscope.jar server-thread-dump.txt
java -jar build/threadscope.jar --report server-thread-dump.txt

The second command prints the same analysis without opening Swing, including on a headless machine.

Read the incident

1. Filter to BLOCKED to isolate threads waiting for intrinsic monitors.
2. Select settlement-worker; it holds the account monitor and waits for the journal.
3. Inspect journal-flusher; it holds the journal and waits for the account.
4. Open Monitor graph to see ownership edges. Cycle participants use a warm accent; other waits use green.
5. Open Analysis for grouped top frames and a text explanation of the cycle. Export the report to keep it with the original dump.

Search is literal, case-insensitive, and covers complete thread blocks, not just the visible top frame. Thread IDs disambiguate duplicate names. Loading a dump happens off the Swing event-dispatch thread; stale load results cannot replace a more recent selection.

What the graph means

An arrow points from a waiting thread to the thread observed holding the monitor it needs. The parser recognizes locked, waiting to lock, and monitor re-entry records. A closed chain in these edges is reported as a monitor cycle.

Object.wait() releases its monitor. Threadscope removes those released monitors from the ownership set even when a lower stack frame says locked. Ambiguous owners are flagged instead of guessed. Parked java.util.concurrent synchronizers are not treated as intrinsic monitor ownership.

Scope and limits

• Intended for traditional HotSpot text dumps (jcmd Thread.print / jstack style), one snapshot per file.
• It does not attach to processes, sample CPU, upload data, or analyze virtual-thread JSON dumps.
• Monitor-cycle analysis does not cover native locks, AQS synchronizer ownership, distributed waits, or every possible deadlock. An empty cycle list does not prove the process is healthy.
• Interactive input is capped at 32 MiB. All parsed data lives in memory.
• Top-frame grouping indicates a shared stopping point; it is not a CPU profile.
• Exports contain thread names and stack details from the input. Keep them with the same care as the dump.

Development

The build scripts run 13 parser and graph checks, including duplicate names, ambiguous ownership, Object.wait, parked threads, malformed inputs, and a 1,500-thread chain.

To exercise Swing filtering and render the actual window without taking a desktop screenshot:

java -jar build/threadscope.jar --smoke-test docs/workbench.png

This requires a graphical environment; Linux CI uses Xvfb. The image above is rendered from the actual Swing component tree using the bundled fixture.

Read the analysis design for tradeoffs. MIT licensed.