Flame Graph

A profiler samples your running program many times per second and records the full call stack at each sample. For example, sampling at 99 Hz for 30 seconds gives roughly 2,970 stack snapshots. A flame graph takes all those stacks and merges them into one picture.

Every box is one function. A box sits directly on top of the function that called it, so a vertical stack of boxes is one call chain from the entry point at the bottom up to the function running at the top. The bottom row is usually main or a thread entry point, and the top is whatever was actually on the CPU when the sample was taken.

The width of a box is the only thing that means cost. A box that spans 40 percent of the width was on top of the stack in 40 percent of the samples, which means the program spent about 40 percent of its time in that function or its children. Color is normally random and carries no meaning. Left to right ordering is alphabetical or by stack frame, not chronological, so you cannot read time passing from left to right.

Step one is collection. A sampling profiler like Linux perf, async-profiler for the JVM, or py-spy for Python periodically interrupts the process, walks the stack, and writes out each captured stack as a single line of frame names. Sampling is cheap, often under a few percent overhead, which is why it can run on production systems.

Step two is folding. Many identical stacks get collapsed into a count. A stack like main;handleRequest;parseJson seen 600 times becomes one line with the number 600 next to it. Brendan Gregg's original toolkit does this with a stackcollapse script.

Step three is rendering. The folded stacks are turned into a self-contained SVG or an interactive HTML page. Boxes are sized by their sample count relative to the total. Clicking a box zooms so it fills the width, which lets you drill into a hot subtree. There is also the inverted icicle layout, where the root is on top and the graph grows downward, used by Chrome DevTools and many cloud profilers.

Use a flame graph when something is slow or burning CPU and you do not yet know where. It answers the question where is the time going faster than reading code or guessing. It is the standard view in production continuous profilers because a single picture summarizes thousands of stacks.

Pick the right variant for the question. A CPU flame graph (on-CPU) shows where the processor is busy. An off-CPU flame graph shows where threads are blocked waiting on locks, disk, or network, which is invisible in a pure CPU profile. A differential flame graph paints one capture against another in red and blue so you can see what got worse after a deploy.

Be aware of the limits. A flame graph hides time order, so it will not show that a slow function only fires on the first request. Sampling can miss very short or very rare functions. Without symbols, frames show up as raw addresses and the graph is useless, so you need debug symbols and, on the JVM, frame pointers or a profiler that unwinds correctly. It also measures aggregate cost, not a single slow request, so pair it with tracing when you need per-request latency.

Say a Java API server is pinned at 90 percent CPU and p99 latency has doubled. You attach async-profiler for 30 seconds with the command profiler.sh -d 30 -f out.html PID and open the resulting flame graph.

The bottom rows show the request handling threads. Most of the width sits under a single subtree: a JSON serialization library, and inside it a regular expression compile that is being called on every response instead of being cached. That one box is 35 percent of the total width.

You move the regex compilation to a static field so it runs once at startup. After redeploying you capture again, and that 35 percent box has shrunk to under 1 percent, CPU drops, and latency recovers. The flame graph turned a vague this is slow into a precise one line fix.