What a flamegraph is

A profiler that samples doesn't trace every call; it interrupts the program many times a second and records the current call stack. After a while you have a huge bag of stacks. Some call paths show up in thousands of samples (the program spent a lot of time there); some show up in a handful (it barely visited). A flamegraph aggregates that bag into one shape.

Each box is a stack frame — a function. A box sits on top of the function that called it, so height is call depth: main at the bottom, the deepest helper at the top. And the width of a box is the thing that matters: it's proportional to how often that frame appeared in the samples. Gregg's own description is exact:

The x-axis shows the stack profile population, sorted alphabetically (it is not the passage of time), and the y-axis shows stack depth, counting from zero at the bottom. Each rectangle represents a stack frame. The wider a frame is[,] the more often it was present in the stacks.

The axis everyone misreads

Here is the single most common misunderstanding, and clearing it up is half of learning to read these. The x-axis is not time. It looks like a timeline — a wide bar stretching left to right — but it isn't one. The horizontal direction is just the sample population sorted alphabetically by function name, so that identical call paths sit adjacent and merge into one wide box.

Why it matters: you cannot read left-to-right as "first this happened, then that." A frame on the far left isn't earlier than one on the right; it's just earlier in the alphabet. What you can read is width as proportion of total time, and the top edge as what was actually running. As Gregg puts it, "the top edge shows what is on-CPU." Everything below a top-edge frame is its ancestry — the chain of callers that led there.

One disambiguation before the rule hardens: some tools draw a sibling picture called a flame chart — Chrome DevTools' performance panel and speedscope's time-order view among them — where the x-axis is time, one stack per instant, nothing merged. Same flames, different geometry. The tell is merging: if identical call paths collapse into one wide box, width is share of samples and the axis is not time; if the same function appears again and again along the row, you're looking at a timeline.

Reading one: find the plateau

So the technique is almost embarrassingly direct. Scan for the widest boxes, especially wide boxes near the top — a wide plateau at the top edge is a function that was on-CPU in a large fraction of samples, which is to say, your hot spot. Narrow spikes are cheap, however deep they go. You are hunting for breadth, not depth.

Here is a flamegraph of a build — analysis versus execution versus linking, the structure the build system series has been about. The widths are illustrative, not a measurement of a specific run, but the shape is true to where build time generally goes. Click a box to zoom into its subtree; click a breadcrumb to zoom back out.

Look at it the way the technique prescribes and the answer jumps out: codegen, nested under compile under execution, is the widest box on the top edge. It doesn't matter that analysis sits to its left or that link is a sibling — width is the whole story, and codegen is the widest. If you had an afternoon to make this build faster, you'd spend it there, and the picture told you so in one glance.

Why it's a tree, and why that's the right shape

A flamegraph is exactly a tree of frames, each carrying its own sample count, where a parent's total is its own samples plus all its children's. That structure is not incidental — it's why the layout works. To size every box you compute, for each node, the sum of itself and everything beneath it, then divide the parent's width among its children in proportion. Computing "the total weight of every subtree" in one pass over a tree is a textbook fold (a catamorphism), which is exactly how the renderer on this page builds it.

The same tree, the same fold, gives you the close cousins for free: flip it and the root sits at the bottom (the classic flame shape); leave the root on top and it's an icicle; lay the children along a time axis instead of packing them and it's a profiling timeline. One data structure, several views — because once you have a weighted tree, where the weight is is the only question any of these pictures answers.

The honest limits

A flamegraph is a lens, not an oracle. Three things to keep in mind.

• It's statistical. Sampling is fair in expectation — a function collects samples in proportion to the CPU time it uses, however briefly each visit runs — but the estimates have variance (a rare-but-real cost needs many samples to show its true width), and work synchronized with the sample clock skews the count. That lockstep hazard is why the convention is 99 Hz rather than 100 — in Gregg's words, "to avoid accidentally sampling in lockstep with some periodic activity, which would produce skewed results." Widths are good estimates, not audited totals.

• A hot function split across many callers hides. Frames merge only when their entire ancestry matches, so a function called from forty sites — memcpy, an allocator, a serializer — appears as forty narrow boxes that never look wide, and the widest-box scan misses the biggest total in the profile. The remedy is the inverted (bottom-up) flame graph, which merges leaves first, or a per-function aggregate table. When the widest box looks innocent, invert the graph before concluding the profile is flat.

• Off-CPU time is invisible by default. A standard CPU flamegraph only shows time spent running. A program slow because it's waiting — on a lock, a disk, a network call — shows up as nothing at all, because no CPU samples land there. That needs a separate "off-CPU" flamegraph.

• It shows where, never why. The widest box tells you which function to look at; it can't tell you that the function is slow because of a bad algorithm, a cache miss, or a pathological input. The flamegraph ends the search and hands you to the debugger.

The whole idea, in one box

Strip everything away and a flamegraph is a single trick: take an unreadable pile of stack samples, fold it into a weighted tree, and draw the tree so that weight becomes width. After that, optimization starts where your eye already went — the biggest rectangle on the screen.

That's why it's become the default picture of performance work. Not because it's clever to draw, but because it moves the answer from "buried in tens of thousands of numbers" to "the widest thing you're looking at." The slow code stops hiding.

Lessons

• A flamegraph aggregates sampled stacks into a tree of frames: height is call depth, width is share of time.
• The x-axis is not time — it's the sample population sorted alphabetically so identical paths merge. Don't read it left to right. (A flame chart — DevTools' timeline view — is the sibling whose x-axis is time; the tell is whether identical paths merge.)
• Read widest-first: the widest box on the top edge is the hot spot. Depth is cheap; breadth is the bottleneck. When a hot function is split across many call sites, no box looks wide — invert the graph before trusting a flat-looking profile.
• It's a weighted tree sized by a fold — which is why icicles and profiling timelines are the same structure under different layouts.
• Limits: sampling is statistical; off-CPU (waiting) time is invisible without a separate graph; it shows where, never why.

References

1. Brendan Gregg. “Flame Graphs.” — the original, with the canonical reading rules
2. “The FlameGraph toolkit.” — and Linux perf — generating them from real profiles
3. “Catamorphisms.” — the fold that totals every subtree in one pass
4. “The Build Is Proportional to the Change.” — the system the example profiles

Mangalapilly, Y. J. (2026, June). The Widest Box Is the Bug. Saṃhitā Notes. https://yesudeep.com/blog/the-widest-box-is-the-bug/

@online{mangalapilly2026the,
          author  = {Yesudeep Jose Mangalapilly},
          title   = {The Widest Box Is the Bug},
          journal = {Sa\d{m}hit\=a Notes},
          year    = {2026},
          month   = {June},
          url     = {https://yesudeep.com/blog/the-widest-box-is-the-bug/},
          urldate = {2026-07-01},
        }

Yesudeep Jose Mangalapilly. “The Widest Box Is the Bug.” Saṃhitā Notes, 2026. https://yesudeep.com/blog/the-widest-box-is-the-bug/.

TY  - ELEC
        AU  - Mangalapilly, Yesudeep Jose
        TI  - The Widest Box Is the Bug
        T2  - Saṃhitā Notes
        PY  - 2026
        UR  - https://yesudeep.com/blog/the-widest-box-is-the-bug/
        Y2  - 2026-07-01
        ER  -