Skip to content
Tutorials Center
My learning

Topics

Lesson 170 of 201 ยท JVM and Advanced Topics

Profiling with JFR and VisualVM

Record with Java Flight Recorder, read hot methods, write custom JFR events, take heap dumps and use VisualVM.

When a Java service is slow, uses too much memory or stalls now and then, guessing is the worst strategy. A profiler tells you where the time and memory really go. Java comes with an excellent one built in: Java Flight Recorder (JFR), a low-overhead event recorder inside the JVM. It was designed to run in production, always on, like the flight recorder in an aircraft: when something goes wrong you already have the data.

This lesson shows how to record with JFR, how to read a recording, how to write your own events (and run a complete recording right here in a program), and how to investigate memory with heap dumps and VisualVM. It follows on from JVM Options and GC Tuning and from the measurement rules in Performance.

flowchart LR
    A["Symptom<br/>(slow, high memory, pauses)"] --> B["Record<br/>(JFR or a profiler)"]
    B --> C["Analyze<br/>(hot methods, allocations,<br/>GC, locks, heap dump)"]
    C --> D["Change one thing"]
    D --> E["Measure again"]
    E -->|"not enough"| B

Profiling is a loop: record, read, change one thing, check that it helped.

What a profiler can tell you

Different problems need different views:

Question View Source of data
Which methods burn CPU? Hot methods, flame graph Sampled stack traces
What allocates all the memory? Allocation profile Allocation events
Why is the app waiting? Lock contention, I/O, thread parking Monitor, park and I/O events
Are GC pauses a problem? GC pauses and heap after each GC GC events
What is holding memory? Retained size, dominator tree Heap dump
What are the threads doing right now? Thread dump jcmd Thread.print

Sampling is the main technique: every few milliseconds the profiler records the stack of running threads. A method that appears in 40% of the samples is using about 40% of the CPU time. Sampling is cheap and, with enough samples, accurate. It is why JFR can run in production with an overhead of around one or two percent.

Recording with JFR

JFR ships with OpenJDK (and is free to use). You can start a recording with the JVM at startup or attach to a running process.

At startup:

TEXT
java -XX:StartFlightRecording=duration=60s,filename=app.jfr,settings=profile -jar app.jar

On a running process, using its process id (list them with jcmd):

TEXT
jcmd 12345 JFR.start name=check settings=profile
...wait while the problem happens...
jcmd 12345 JFR.dump name=check filename=app.jfr
jcmd 12345 JFR.stop name=check

Two built-in settings files control what is recorded: default (very low overhead, meant for continuous recording) and profile (more detail such as a higher sampling rate, a bit more overhead). For a service that should always be recorded, a flag like -XX:StartFlightRecording=maxage=6h,maxsize=500m,dumponexit=true,filename=/dumps/last.jfr keeps a rolling window in memory and writes it when the JVM exits (use jcmd ... JFR.dump while it runs). When the incident happens, you dump the last hours.

Reading a recording

The JDK includes a command-line jfr tool:

TEXT
jfr summary app.jfr                                 # which events, how many
jfr print --events jdk.GarbageCollection app.jfr    # all GC events as text
jfr view hot-methods app.jfr                        # top methods by samples
jfr view allocation-by-class app.jfr                # what allocates most
jfr print --json --events jdk.ExecutionSample app.jfr

For a graphical view, use JDK Mission Control (JMC), a separate download. Open the .jfr file and you get an automated analysis page with findings in plain language ("hot method", "high GC pause"), a method profiling view, a flame graph, thread and lock views, and the memory and I/O timelines. IntelliJ IDEA Ultimate and several other tools can open JFR files as well.

JFR from inside your program

JFR is also an API in the jdk.jfr package, and recordings are readable by the jdk.jfr.consumer package. That means a program can record itself and analyze the result, which is how you can try everything in this lesson without installing anything.

The next program records a CPU profile of its own code. Two methods do work, one of them 20 times more than the other. JFR samples the running thread every 10 milliseconds; the program then reads the recording and counts which method was at the top of the stack. The exact counts change from run to run, which is normal for sampling, so only the stable conclusions are printed:

Java Profiling a program with JFR

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.

busyWork takes most of the samples, and that is exactly the answer a hot-methods view gives for a real application. Notice the habit from the Performance lesson: the results of the work are used (sink), so the JIT cannot remove it.

Custom events

JFR records JVM events (GC, class loading, locks, I/O, threads), but you can add your own application events. Anything you can describe as "this happened, for this long, with these fields" fits: a request, a cache refresh, a payment, a batch step. Events cost almost nothing when nobody is recording.

A custom event is a class that extends jdk.jfr.Event, with fields for the data. You call begin() before the work, fill the fields, and commit() afterwards; the event then records its own duration and thread:

Java A custom JFR event

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.

In production you would not start the recording in code. You would add your event, run with -XX:StartFlightRecording, and see "Order processed" events (with their durations) next to GC pauses and lock waits on the same timeline in Mission Control. Correlating "orders slowed down" with "a GC pause happened" is exactly the sort of insight a profiler gives you.

Profiling in practice

  • Profile realistic load. A profile of an idle app or of a tiny test says little. Replay production traffic, or run a load test.
  • Warm up first. The JIT needs time (see How Java Works). Ignore the first minute or two of a short recording.
  • Look at the top few items only. If one method has 40% of the samples, fixing it matters; the 0.5% methods don't.
  • Read the stack, not just the top frame. The hot method may be innocent: it is being called a million times by a caller that could call it once.
  • Look at waiting, not only CPU. A slow request with low CPU is waiting: for a lock, a database, a socket or a thread pool. Use the lock and I/O views, or a thread dump.
  • Change one thing and re-measure. Keep the baseline recording to compare.

Memory problems and heap dumps

If memory use only grows, the cause is usually a leak: objects that are still reachable, so the collector may not remove them. Typical culprits are a static Map used as an unbounded cache, listeners that are never unregistered, and ThreadLocals on long-lived pool threads.

A heap dump is a snapshot of every live object and what refers to it. Create one in any of these ways:

TEXT
jcmd 12345 GC.heap_dump /dumps/heap.hprof
jmap -dump:live,format=b,file=/dumps/heap.hprof 12345
-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/dumps     (automatic, at crash time)

The dump is as big as the heap in use, and creating it pauses the application, so be careful with large production heaps. Open it in VisualVM or Eclipse MAT. The key ideas:

  • Shallow size is the memory of the object itself. Retained size is the memory that would be freed if that object disappeared, including everything only it keeps alive. Sort by retained size to find what really holds memory.
  • The dominator tree shows objects ordered by what they retain. One HashMap retaining 1.2 GB is a very clear suspect.
  • Path to GC roots answers "why is this still alive?" by showing the chain of references from a root (a static field, a thread stack) to the object.
  • A class histogram (jcmd 12345 GC.class_histogram) is a quick, lighter alternative: a count and total size per class. Run it twice, a few minutes apart, and see which class keeps growing.

The real fix always starts with finding who holds the references. Remember, a leak in Java is not "lost" memory; it is memory you forgot to let go of.

VisualVM

VisualVM is a free graphical tool, downloaded separately from the JDK, that connects to a running local or remote JVM. It offers:

  • Live graphs of heap, threads, classes and CPU.
  • A sampler and a profiler (CPU and memory) for a quick look at hot methods and allocations.
  • Thread dumps with deadlock detection.
  • Heap dump creation and a heap viewer with retained sizes and instance browsers.
  • Plugins, including a JFR viewer.

Use it on a development machine or a test server when you want to click around and explore. For production, prefer JFR: it is built in, has lower overhead and needs no GUI attached to the server. Whichever tool you use, remember that profiling a remote process requires a secured connection: don't expose JMX ports to the internet without authentication and TLS (see Secure Coding).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why can JFR be used in production?

    JFR is part of the JVM and uses an efficient event buffer, so default recordings are cheap enough to leave on. The profile settings cost a little more.
  2. 2. A method appears in 40% of the sampled stack traces. What does this mean?

    Samples are taken at regular intervals, so the share of samples approximates the share of time.
  3. 3. Which jcmd command saves the contents of a running JFR recording named check to a file?

    JFR.dump writes the recording so far to a .jfr file that you can open with the jfr tool or JDK Mission Control.
  4. 4. In a heap dump, what is retained size?

    Retained size accounts for everything that would become unreachable together with the object, so it shows what a single object really costs.
  5. 5. A request is slow, but CPU usage is low and the hot-methods view shows nothing unusual. What should you check?

    Low CPU with high latency means waiting. Use the lock, I/O and thread views of JFR or a thread dump to see what the thread is blocked on.

Summary

  • Profile instead of guessing: sampling profilers show where time goes, and heap dumps show what holds memory.
  • JFR is built into the JVM. Start it with -XX:StartFlightRecording or jcmd <pid> JFR.start, dump with JFR.dump, and read it with the jfr tool or JDK Mission Control.
  • The default settings are cheap enough for continuous use; profile gives more detail.
  • Custom events (extends jdk.jfr.Event) put your own business operations on the same timeline as GC and locks.
  • For leaks, take a heap dump and sort by retained size; use the dominator tree and paths to GC roots to find who holds the references.
  • VisualVM is a friendly GUI for development; prefer JFR in production. Profile realistic load, warm up first, change one thing at a time.

Next: Benchmarking with JMH, where you measure small pieces of code correctly.