How To Take Thread Dump In Linux – Using Jstack For Java Processes

by

Generating a thread dump in Linux involves sending a specific signal to your Java application’s process ID. Understanding how to take thread dump in Linux is a critical skill for diagnosing performance issues, deadlocks, and high CPU usage in Java applications. This guide walks you through every method step by step, from basic commands to advanced automation.

Thread dumps capture the state of all active threads in a Java Virtual Machine (JVM) at a single moment. They are invaluable for troubleshooting application hangs, analyzing thread contention, and identifying bottlenecks. You don’t need any special tools beyond what Linux already provides.

How To Take Thread Dump In Linux

There are several reliable ways to generate a thread dump on Linux. The most common methods use the kill command, the jstack utility, or Java’s built-in tools. Each method works slightly differently, so choose the one that fits your environment best.

Prerequisites For Taking A Thread Dump

Before you start, you need to know the Process ID (PID) of your Java application. You can find it using the ps command or jps if Java tools are installed.

  • Run ps aux | grep java to list all Java processes
  • Look for your application name or main class in the output
  • Note the PID from the second column
  • Alternatively, use jps -l to list Java PIDs with full class names

Make sure you have the necessary permissions. You typically need to be the same user that owns the Java process or have root access. If you get a “permission denied” error, try with sudo.

Method 1: Using The Kill Command With SIGQUIT

The simplest way to generate a thread dump is sending the SIGQUIT signal to your Java process. This signal is number 3 on Linux systems.

  1. Find your Java application’s PID using ps aux | grep java
  2. Run kill -3 PID (replace PID with the actual number)
  3. The thread dump is written to the application’s standard output (stdout)
  4. If the application is running in a terminal, you’ll see the dump there
  5. If it’s a background process, check the logs or redirect stdout to a file

This method works even if you don’t have Java tools installed. It’s built into the JVM itself. The thread dump appears as a text block with all thread states, stack traces, and lock information.

One common mistake is forgetting to redirect output. If your application runs as a daemon, the dump might go to /dev/null. To capture it, start your Java process with output redirection: java -jar myapp.jar > app.log 2>&1.

Method 2: Using Jstack Utility

If you have the JDK installed, jstack is the most convenient tool. It gives you more control over where the dump is saved.

  1. Install JDK if not already present: sudo apt install default-jdk (Debian/Ubuntu) or sudo yum install java-11-openjdk-devel (RHEL/CentOS)
  2. Locate jstack in the JDK bin directory, usually /usr/lib/jvm/java-11-openjdk/bin/jstack
  3. Run jstack -l PID > threaddump.txt to save to a file
  4. The -l flag includes long listing with lock information
  5. Wait a few seconds and run again for a second dump (compare multiple dumps)

Jstack works best when you have the same user as the Java process. If you get “Unable to open socket file”, the process might be running in a container or with a different user. In that case, use sudo -u username jstack PID.

For older Java versions (pre-8), you might need to use jstack -F PID for forced dumps. This is useful when the JVM is hung and not responding to normal signals.

Method 3: Using Java’s Built-In Thread Dump

Modern Java versions (9+) include a built-in thread dump feature. You can trigger it from within the application or via the command line.

  • Press Ctrl+Break on Windows or Ctrl+\ on Linux if the app runs in the foreground
  • Use jcmd PID Thread.print to print the thread dump to stdout
  • Redirect output: jcmd PID Thread.print > dump.txt
  • For Java 8 and earlier, use jstack instead

The jcmd utility is part of the JDK and works with Java 7+ (though it’s more reliable in Java 8+). It’s actually the recommended tool for modern Java applications because it doesn’t require attaching to the process in the same way as jstack.

Method 4: Using The Jvisualvm GUI Tool

If you prefer a graphical interface, jvisualvm provides a visual way to take thread dumps. It’s included with the JDK but might need separate installation on some distributions.

  1. Launch jvisualvm: jvisualvm from the terminal
  2. In the left panel, find your Java application under “Local”
  3. Double-click the application to open its details
  4. Click the “Threads” tab
  5. Click the “Thread Dump” button at the top
  6. Save the dump as a text file using the save icon

This method is great for beginners because it shows thread states visually. However, it requires a GUI environment, so it’s not suitable for headless servers. For remote servers, you can use jstatd to connect remotely, but that adds complexity.

Method 5: Automating Thread Dumps With A Script

For production systems, you often need multiple thread dumps taken at intervals. A simple bash script can automate this.

#!/bin/bash
PID=$1
INTERVAL=$2
COUNT=$3
OUTPUT_DIR="/tmp/threaddumps"

mkdir -p $OUTPUT_DIR
for i in $(seq 1 $COUNT); do
    jstack -l $PID > "$OUTPUT_DIR/dump_$(date +%Y%m%d_%H%M%S).txt"
    sleep $INTERVAL
done
echo "Thread dumps saved to $OUTPUT_DIR"

Save this as threaddump.sh, make it executable with chmod +x threaddump.sh, and run it: ./threaddump.sh 1234 5 3. This takes 3 dumps, 5 seconds apart, for PID 1234.

You can also integrate this with cron for regular monitoring. Add a cron job that runs every hour during peak traffic to capture dumps automatically.

Understanding Thread Dump Output

Once you have a thread dump, you need to read it. The output contains several key sections.

Thread States

Each thread has a state that tells you what it’s doing:

  • RUNNABLE: Thread is actively executing code
  • BLOCKED: Thread is waiting for a monitor lock
  • WAITING: Thread is waiting indefinitely (e.g., Object.wait())
  • TIMED_WAITING: Thread is waiting with a timeout (e.g., Thread.sleep())
  • TERMINATED: Thread has finished execution

Stack Traces

Each thread shows its call stack, from the current method back to the entry point. Look for patterns like:

  • Multiple threads in BLOCKED state waiting for the same lock (possible contention)
  • Threads stuck in the same method (possible infinite loop)
  • Threads in WAITING state that never progress (possible deadlock)

Lock Information

The -l option in jstack shows lock details. Look for:

  • Threads holding locks that others are waiting for
  • Circular waiting patterns (deadlock)
  • Threads waiting on condition variables

Common Issues And Solutions

Here are typical problems you might encounter when taking thread dumps.

Permission Denied

If you get “Operation not permitted” when using kill -3, you don’t have permission to send signals to that process. Use sudo kill -3 PID or switch to the process owner’s account.

Jstack Not Found

If jstack is missing, you only have the JRE installed, not the JDK. Install the JDK package for your distribution. Alternatively, use the kill -3 method which doesn’t require JDK tools.

Process Running In Container

For Docker containers, you need to execute the command inside the container. Use docker exec -it container_name jstack PID or docker exec -it container_name kill -3 PID.

Java Process Not Responding

If the JVM is completely hung, jstack might not work. Try jstack -F PID for forced dump, or use kill -3 which works at the OS level. If even that fails, you might need to restart the application.

Analyzing Thread Dumps For Deadlocks

Deadlocks occur when two or more threads are waiting for locks that each other holds. The thread dump will show this clearly.

  1. Look for threads in BLOCKED state
  2. Check which locks they are waiting for
  3. Find the threads holding those locks
  4. If those threads are also BLOCKED waiting for other locks, you have a cycle
  5. Jstack automatically detects deadlocks and prints a “Found one Java-level deadlock” message

When you see a deadlock, the solution is usually to redesign your locking strategy. Use java.util.concurrent locks with timeouts, or reorder lock acquisition to avoid cycles.

Best Practices For Thread Dumps

Follow these guidelines to get the most value from thread dumps.

  • Take at least 3-5 dumps at 5-10 second intervals to see thread progression
  • Capture dumps during the problem period, not after it resolves
  • Include the application version and environment details in the dump file name
  • Use the -l flag for lock information (essential for deadlock analysis)
  • Keep dumps for historical comparison (you might spot trends)
  • Automate dumps during known high-traffic periods

Remember that a single thread dump is just a snapshot. Multiple dumps show you how threads behave over time. A thread that’s always RUNNABLE in the same method might be in a loop, while a thread that alternates between states is likely normal.

Alternative Tools For Thread Dump Analysis

While raw text dumps are useful, several tools can help you visualize and analyze them.

  • FastThread: Online analyzer that highlights problems
  • Samurai: Open-source thread dump analyzer
  • IBM Thread and Monitor Dump Analyzer: Free tool for complex analysis
  • VisualVM: Can load saved thread dumps for analysis

These tools parse the dump and identify common issues like deadlocks, thread contention, and excessive GC activity. They save time compared to manually reading through hundreds of lines of stack traces.

When To Use Each Method

Different situations call for different approaches.

Situation Recommended Method
No JDK installed kill -3 PID
Need to save to file jstack -l PID > dump.txt
Java 9+ application jcmd PID Thread.print
GUI available jvisualvm
Automated monitoring Bash script with jstack
Containerized app docker exec with jstack or kill -3

Choose the method that matches your environment and requirements. For most production systems, a combination of kill -3 (for simplicity) and jstack (for file output) works best.

Frequently Asked Questions

What Is The Difference Between A Thread Dump And A Heap Dump?

A thread dump captures the state of all threads and their stack traces, showing what each thread is currently doing. A heap dump captures the memory contents of the JVM, showing all objects and their references. Thread dumps are used for concurrency issues, while heap dumps are for memory leaks.

Can I Take A Thread Dump Without Stopping The Application?

Yes, thread dumps are non-invasive. They capture a snapshot of thread states without interrupting the application. The JVM pauses briefly to generate the dump, but this is typically less than a second and doesn’t affect normal operation.

How Do I Take A Thread Dump For A Java Application Running As A Service?

Find the PID using ps aux | grep java or systemctl status service_name. Then use kill -3 PID and check the service’s log file (usually in /var/log/). Alternatively, use jstack PID > dump.txt if JDK is installed.

What Should I Look For In A Thread Dump To Diagnose High CPU Usage?

Look for threads in RUNNABLE state that are repeatedly calling the same method. Check for threads stuck in infinite loops or busy-waiting. Also look for excessive garbage collection threads (GC threads) that might indicate memory pressure.

Why Do I Get “Unable To Open Socket File” When Using Jstack?

This error occurs when jstack cannot connect to the JVM’s internal management interface. It often happens when the Java process is running with a different user, inside a container, or with security restrictions. Try using sudo -u username jstack PID or switch to the kill -3 method.

Taking thread dumps on Linux is straightforward once you know the commands. Practice with a test Java application to get comfortable with the output. Over time, you’ll learn to spot patterns that indicate specific problems. Keep this guide handy for reference when you need to diagnose production issues quickly.