Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 119 ยท Logging and Tooling

Debugging and Profiling Tools

Debug and profile Java apps like a pro. Use IDE breakpoints, remote debugging, jcmd, jstack and jmap, thread and heap dumps, Java Flight Recorder and Mission Control.

Logs tell you what the application chose to report. When that is not enough (a request hangs, memory grows until the process dies, an endpoint is mysteriously slow) you need tools that look inside the running JVM: debuggers that pause it and show every variable, dumps that capture every thread or every object, and profilers that tell you where time and memory actually go.

The JDK ships an excellent set of these tools, and most developers use only a fraction of them. This lesson tours the ones professionals rely on: IDE and remote debugging, the command-line diagnostics jcmd, jstack, jmap and jstat, thread dumps and deadlock detection, heap dumps, Java Flight Recorder (JFR) with JDK Mission Control, and a sound method for performance work. Because the examples here run on a server you cannot attach tools to, the runnable demos use the same APIs the tools use internally: the management beans (MXBeans) and JFR's Java API. For a gentler start, see Debugging Java Programs.

The IDE debugger: more than breakpoints

Every Java IDE (IntelliJ IDEA, Eclipse, VS Code with the Java extensions) has a full debugger. Start the program with Debug instead of Run and the JVM pauses at your breakpoints. The features worth mastering:

Feature What it does When to use it
Line breakpoint pauses before a line runs the basic "what is the state here?"
Conditional breakpoint pauses only when an expression is true, like orderId == 42 a bug that shows up on the 10,000th loop iteration
Logpoint (non-suspending breakpoint) prints a message or expression without pausing adding "println debugging" without editing code
Exception breakpoint pauses when a given exception is thrown, even if it is caught finding where a swallowed exception comes from
Field watchpoint pauses when a field is read or written "who keeps changing this value?"
Step over / into / out runs the next line / enters the call / finishes the method following the flow
Run to cursor continues to the line under the cursor skipping uninteresting code
Evaluate expression runs any Java expression in the paused frame testing a hypothesis without restarting
Reset frame (drop frame) rewinds to the start of the current method re-running a method after changing a variable
HotSwap reloads changed method bodies into the running JVM small fixes during a long debugging session

Two habits make debugging faster. First, form a hypothesis before you set a breakpoint ("the discount is applied twice, probably in applyCoupons"), so you pause where the answer is. Second, reproduce the bug in a test first when you can: a failing test is a breakpoint you can hit again and again in seconds. HotSwap only replaces method bodies; adding fields or methods needs a restart (or a JVM with enhanced class redefinition, such as JetBrains Runtime).

Remote debugging

A JVM started with the JDWP agent listens for a debugger on a socket, so you can debug an application running in a container, a VM or a test environment with your local IDE:

Terminal
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar shop.jar
  • server=y makes the JVM listen; suspend=y would wait for the debugger before running main (useful for startup bugs).
  • address=*:5005 listens on all interfaces. Since Java 9, a plain 5005 binds to localhost only, which is the safer default.
  • In the IDE, create a "Remote JVM Debug" (IntelliJ) or "Remote Java Application" (Eclipse) configuration pointing at the host and port, with the same source code checked out.
  • For Kubernetes, kubectl port-forward pod/shop-7d9 5005:5005 tunnels the port to your machine.

Never expose a JDWP port to an untrusted network. Anyone who can connect can run arbitrary code inside the JVM. Bind to localhost and tunnel with SSH or port-forwarding, and never leave the agent enabled in production by default. Remember also that a breakpoint pauses the threads that hit it, so a paused server stops answering requests.

The JDK's diagnostic command line

Every JDK includes command-line tools in its bin folder that attach to a running JVM by process id. They work on production servers where no IDE is available, which is why every backend developer should know them.

Terminal
jps -l                                  # list running JVMs with their main class or JAR
jcmd 4321 help                          # list every diagnostic command this JVM supports
jcmd 4321 VM.version                    # JDK version and vendor
jcmd 4321 VM.flags                      # effective JVM flags (heap size, GC, ...)
jcmd 4321 VM.system_properties          # system properties
jcmd 4321 Thread.print                  # thread dump (same as jstack)
jcmd 4321 GC.heap_info                  # heap regions and usage
jcmd 4321 GC.class_histogram | head -20 # object counts and bytes per class
jcmd 4321 GC.heap_dump /tmp/shop.hprof  # full heap dump to a file
jcmd 4321 JFR.start duration=60s filename=/tmp/shop.jfr   # start a flight recording
jstat -gcutil 4321 1000                 # GC statistics every second

jcmd is the one tool to remember: it does what the older single-purpose tools do (jstack for thread dumps, jmap -histo and jmap -dump:live,format=b,file=heap.hprof for heap analysis, jinfo for flags) and more. Run jcmd <pid> help to see everything a particular JVM offers. Tools must run as the same operating system user as the target JVM; inside containers, run them with docker exec or kubectl exec in the same container.

Graphical tools build on the same mechanisms: JConsole (included in the JDK) shows live MXBean data, while VisualVM, JDK Mission Control and Eclipse Memory Analyzer are free separate downloads.

Thread dumps: what is every thread doing?

A thread dump lists every thread with its state (RUNNABLE, BLOCKED, WAITING, TIMED_WAITING) and its current stack trace. It is the first thing to take when an application hangs or a request never finishes. Take three dumps a few seconds apart: threads that are stuck show the same stack each time.

The JVM can also find deadlocks for you: threads waiting for each other's locks in a cycle (see Deadlocks, Livelocks and Starvation). jstack prints "Found one Java-level deadlock" at the end of the dump. The example creates a real deadlock and then uses ThreadMXBean, the API that jstack and jcmd Thread.print read from, to detect it and print the dump.

Java Detecting a deadlock with ThreadMXBean

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Each deadlocked thread is BLOCKED, waiting for a lock (shown as java.lang.Object@ plus an identity hash) that the other thread holds. The stack frames point at the lambda inside worker. A real jstack dump shows the same information as - waiting to lock <0x...> and - locked <0x...> lines. The fix is always to acquire locks in one global order, or to use tryLock with a timeout from java.util.concurrent.locks.

What to look for in a thread dump:

  • Many threads BLOCKED on the same lock: lock contention. Find the thread that holds it.
  • Many threads WAITING in a connection pool's getConnection: the pool is exhausted, often because connections leak or a slow query holds them.
  • Threads RUNNABLE in the same method in every dump: a hot loop or an infinite loop.
  • Virtual threads: jcmd <pid> Thread.dump_to_file -format=json threads.json includes them; the classic dump only lists platform threads. See Virtual Threads and Structured Concurrency.

Memory: heap statistics, GC and heap dumps

When memory is the problem, start with numbers before reaching for a dump. Is the heap actually full? Is garbage collection running constantly? The MemoryMXBean, MemoryPoolMXBean and GarbageCollectorMXBean give the same data jstat and jcmd GC.heap_info print. The example allocates and releases memory and reports the heap and GC activity.

Java Heap and GC statistics with MXBeans

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Used memory rises by about 40 MB while the list holds the arrays and drops back after the collection, because nothing references them any more. The Flags line shows how this sandbox starts the JVM: a 256 MB heap (-Xmx256m) and the Serial collector (-XX:+UseSerialGC), whose two halves appear as Copy (young generation) and MarkSweepCompact (old generation). On a typical server you would see G1's G1 Young Generation and G1 Old Generation instead. Exact numbers depend on the machine. How the heap and collectors work is covered in Memory and Garbage Collection.

The signs of a memory leak are a heap whose used size after each full collection keeps climbing over hours, GC time growing, and finally java.lang.OutOfMemoryError: Java heap space. For that you need a heap dump: a snapshot of every object and who references it.

Terminal
# Take one now ("live" triggers a full GC first, so only reachable objects remain)
jcmd 4321 GC.heap_dump /tmp/shop.hprof

# Better: have the JVM write one automatically at the moment it runs out of memory
java -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/dumps -Xmx2g -jar shop.jar

Open the .hprof file in Eclipse Memory Analyzer (MAT) or VisualVM. MAT's Leak Suspects report and the dominator tree show which objects keep the most memory alive (their retained size), and the "path to GC roots" shows the reference chain that prevents collection: typically a static map used as a cache with no eviction, listeners that are never removed, or ThreadLocal values on pooled threads. Heap dumps are roughly as large as the used heap and contain all the data in memory (including passwords and personal data), so treat them as sensitive files.

Always set -XX:+HeapDumpOnOutOfMemoryError in production. The dump taken at the moment of failure is worth more than any amount of guessing afterward.

Java Flight Recorder and Mission Control

Java Flight Recorder (JFR) is a profiler and event recorder built into the JVM. It records hundreds of event types (method samples, allocations, GC pauses, lock contention, file and socket I/O, exceptions, class loading) with an overhead of around 1% with the default settings, which makes it safe to run in production, even continuously. JDK Mission Control (JMC) is the free desktop application that opens .jfr files and shows hot methods, flame graphs, GC pauses and automated analysis.

Terminal
# Record from startup for 2 minutes with the more detailed "profile" settings
java -XX:StartFlightRecording=duration=120s,filename=shop.jfr,settings=profile -jar shop.jar

# Or start and dump on a running JVM
jcmd 4321 JFR.start name=checkout settings=profile
jcmd 4321 JFR.dump name=checkout filename=/tmp/checkout.jfr
jcmd 4321 JFR.stop name=checkout

# Inspect a recording on the command line (no GUI needed)
jfr summary shop.jfr
jfr print --events jdk.GarbageCollection shop.jfr
jfr view hot-methods shop.jfr

JFR has a Java API too (jdk.jfr), which lets you start recordings in code, read .jfr files, and define your own events that show up in Mission Control next to the JVM's. The example records CPU samples and a custom ReportBuilt event while it runs two methods of different cost, then reads the recording back and counts which method the samples landed in. That is exactly what a sampling profiler does.

Java A tiny profiler with Java Flight Recorder

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Almost all samples land in expensiveMath, and only a few in cheapLoop, even though both loop two million times. That is the core insight of profiling: time is rarely spent where you guess. Exact counts vary between runs, which is normal for a sampling profiler. In Mission Control the same data appears as a "Method Profiling" page and a flame graph, with the full stack of each sample instead of just the top frame.

JFR keeps improving: JDK 25 added method timing and tracing events (JEP 520), which record exact call counts and durations for methods you name with a filter, and experimental CPU-time profiling on Linux (JEP 509). Spring Boot and Micrometer can also emit JFR events, and tools like async-profiler (a popular open-source sampling profiler for Linux and macOS) produce flame graphs that include native and kernel frames.

Profiling with a method

Tools are only half the story. A disciplined approach saves days:

  1. Define the problem as a number. "Checkout p95 latency is 1.8 s, target 500 ms" is actionable; "it feels slow" is not.
  2. Reproduce it with realistic data and load, ideally outside production.
  3. Measure before changing anything. Profile (JFR, async-profiler) to find where time actually goes: CPU, waiting on locks, waiting on the database, GC.
  4. Fix the biggest cost first. It is usually a query (missing index, N+1 queries), a remote call in a loop, excessive allocation, or lock contention, not the speed of a for loop.
  5. Measure again to confirm the change helped, and keep a test or benchmark that guards it.

Two kinds of profilers exist. Sampling profilers (JFR, async-profiler) look at stacks at intervals: low overhead, safe in production, statistically accurate for hot spots. Instrumenting profilers insert timing code into every method: exact call counts but heavy overhead that distorts results. Prefer sampling.

For micro-level questions ("is StringBuilder faster than String.join here?"), never time code with System.nanoTime() in a loop. The JIT compiler warms up, inlines and removes dead code, so naive timings are often wrong by orders of magnitude. Use JMH, the OpenJDK benchmarking harness, which handles warm-up, forking and dead-code elimination:

Java
@State(Scope.Benchmark)
@Warmup(iterations = 3)
@Measurement(iterations = 5)
@Fork(1)
public class JoinBenchmark {
    List<String> words = List.of("alpha", "beta", "gamma", "delta");

    @Benchmark
    public String stringJoin() {
        return String.join(",", words);
    }

    @Benchmark
    public void builder(Blackhole sink) {
        var sb = new StringBuilder();
        for (String w : words) sb.append(w).append(',');
        sink.consume(sb.toString());   // stops the JIT from deleting the work
    }
}

General performance habits are collected in Java Performance Tips.

A troubleshooting cheat sheet

Symptom First tool What to look for
Request hangs, app unresponsive 3 thread dumps (jcmd Thread.print) threads stuck on the same lock, pool or I/O call; deadlock report
High CPU JFR or async-profiler; thread dumps hot methods; RUNNABLE threads in the same loop
Memory grows, OutOfMemoryError jstat -gcutil, then a heap dump in MAT used heap after GC rising; dominator tree, path to GC roots
Long pauses, latency spikes JFR GC events, GC logs (-Xlog:gc*) long or frequent collections; allocation rate
Slow endpoint, CPU idle JFR (socket/file I/O, lock events), thread dumps waiting on the database, remote calls or locks
Wrong result IDE debugger, a failing test the first point where state differs from your expectation

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. An application stops responding, but CPU usage is near zero. What should you capture first?

    A hang with idle CPU means threads are waiting. Comparing a few thread dumps shows which threads are stuck and on what lock, pool or I/O call.
  2. 2. Why is -agentlib:jdwp=...,address=*:5005 dangerous on a public server?

    The debug protocol has no authentication. Bind it to localhost and tunnel, and don't enable it in production by default.
  3. 3. What does ThreadMXBean.findDeadlockedThreads() return when two threads each hold one lock and wait for the other's?

    The JVM detects the cycle of monitor ownership and returns the ids of every thread in it. It returns null only when no deadlock exists.
  4. 4. Which JVM option makes sure you have evidence when the heap runs out?

    It writes a heap dump at the moment OutOfMemoryError is thrown, so you can open it in Eclipse MAT and see what filled the heap.
  5. 5. In the JFR example, most CPU samples land in expensiveMath although both methods loop two million times. What does this show?

    sqrt and sin cost far more per iteration than an addition. Sampling reveals real cost, which is why you profile before optimizing.

Summary

  • Master the IDE debugger beyond line breakpoints: conditional breakpoints, logpoints, exception breakpoints, watchpoints, evaluate expression and reset frame.
  • Remote debugging uses -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=...; never expose the port to untrusted networks.
  • jcmd <pid> is the Swiss army knife: Thread.print, GC.heap_info, GC.class_histogram, GC.heap_dump, JFR.start, VM.flags. jps, jstack, jmap and jstat cover the same ground in older style.
  • Thread dumps diagnose hangs and deadlocks; the same data is available in code through ThreadMXBean.
  • Memory problems: watch heap-after-GC with jstat or MXBeans, enable -XX:+HeapDumpOnOutOfMemoryError, and analyze dumps in Eclipse MAT.
  • Java Flight Recorder is a low-overhead, production-safe profiler; open recordings in JDK Mission Control or with the jfr tool, and add custom events with jdk.jfr.Event.
  • Profile with a method: define the problem as a number, measure, fix the biggest cost, measure again; use JMH for microbenchmarks.

Next: Code Quality and Static Analysis, where tools find bugs before the code even runs.