The team has spent three days trying to figure out why the report endpoint takes 4 seconds. They added timestamps. They added logs. They added a custom timer wrapper. The slowest thing they instrumented takes 90 ms; the other 3.9 seconds are unaccounted for. Somebody finally captures a flame graph; the bottleneck is a JSON.stringify in a middleware nobody had thought to instrument. Two-line fix. Three days of work avoided.

Flame graphs are the single best general-purpose tool for “where does the time go?” They are also the most under-used. Every developer has seen one in a blog post; few have generated one for their own code. This post is how to read a flame graph, how to capture one in Node.js (and Python, and a browser), and the four shapes that tell you what kind of bug you have.

How to read a flame graph

A flame graph is a stack of bars. The x-axis is time spent (or samples taken); the y-axis is call depth. Each bar represents a function. The bar’s width is what you care about: it shows how much time was spent in that function (and its children).

[main                                                              ]
[ handleRequest          ][ handleRequest         ][ handleRequest ]
[ middleware ][ db query ][ middleware ][ db query][ middleware ][ db ]
[ jsonStringify ]

The widest bar at any level is the place that took the most time. If a bar is wide and no children fill the width, the time is being spent in that function itself (CPU work, blocking call). If a bar is wide and its children fill the width, time is being spent in the children.

The right way to read it: start at the top. Find the widest bar. Drop down a level. Find the widest bar there. Repeat until you reach a leaf. That leaf is your bottleneck.

It is not “the tallest stack is the problem.” Height tells you call depth, not cost.

Capturing a flame graph in Node.js

Node has a built-in profiler. Run your service with --prof:

node --prof server.js
# ... hammer the slow endpoint ...
# Stop the process. A file like isolate-0xNNN-v8.log is generated.
node --prof-process isolate-0xNNN-v8.log > profile.txt

The profile.txt is human-readable but not visual. For an actual flame graph, use 0x:

npx 0x -- node server.js
# ... load the endpoint ...
# Ctrl-C
# Browser opens with an interactive flame graph.

Or clinic for a richer tooling suite:

npx clinic flame -- node server.js
npx clinic doctor -- node server.js  # diagnoses common issues

For a production service running under load, capture a profile via the V8 inspector:

node --inspect=0.0.0.0:9229 server.js
# Connect chrome://inspect, hit "Profile", run for 10s, download.
# Or:
curl http://localhost:9229/json/list | jq
# Use a tool like @observablehq/inspector or upload the cpuprofile to speedscope.app

speedscope.app is the best free flame graph viewer. Drop in a .cpuprofile, get an interactive graph.

Capturing in other runtimes

Python: py-spy is the right tool. It is non-invasive and attaches to a running process.

py-spy record -o profile.svg --duration 30 -- python app.py

Go: built-in pprof.

go tool pprof -http=:8080 http://localhost:6060/debug/pprof/profile?seconds=30

Browser JavaScript: Chrome DevTools → Performance tab → record. Then “Show flame chart.”

The general principle is the same: sample the running process at high frequency, build a stack-time graph, view in a flame visualizer.

The four shapes you’ll see

1. The flat-top. One function takes 90% of the width with no children visible. The bottleneck is in that function’s own code: a tight loop, a synchronous parse, a regex backtracking, JSON.stringify on a giant object.

[ getReport               ]
[ formatRows              ]
[ JSON.stringify          ]   ← this whole bar, no children

The function is doing CPU-intensive work. Either reduce its work (don’t stringify, stream), make it async (worker thread), or pre-compute upstream.

2. The wide-with-children. A function is wide, but its children are also wide and fill its width. The cost is in the children, not the function. Drill down.

[ handleRequest                                           ]
[ middleware ][ getUser ][ getOrders ][ render            ]
              [ db.query ][ db.query ][ render            ]
                                      [ template ][ render]

render is wide; drill into it.

3. The pile-of-narrow. Many narrow bars at the same level, summing to a lot of width. Often: many small calls to the same function, none individually expensive but repeated 10,000 times.

[ processItems                                            ]
[ pi ][ pi ][ pi ][ pi ][ pi ][ pi ][ pi ][ pi ][ pi ][...]

This is the N+1 query pattern, the loop-with-100k-iterations pattern, the “we call hashFunction 50,000 times in a request” pattern. Aggregate the operation, not the individual call.

4. The async-shaped gap. A function appears wide but with empty space underneath. The time is being spent waiting (I/O, network) rather than doing CPU work. CPU profilers often hide this; you need an event-loop or async profiler.

clinic doctor highlights event-loop blocking specifically. For pure async wait analysis, Node’s async-profiler or distributed tracing (see the OpenTelemetry post) are the right tool.

Reading a real flame graph

A common pattern: the team thought the database was slow. The flame graph showed:

[ http handler                                            ]
[ middleware ][ db.fetchOrder ][ JSON.stringify           ]
              [ pg.query     ][ JSON.stringify           ]
                              [ JSON.stringify (deeply nested) ]

The DB query was 50ms (narrow bar). JSON.stringify of the response was 800ms, because the response had a deeply nested object with circular references and 500 KB of data. The fix: a custom serializer that flattened the response to 30 KB.

The team had been adding console.time to the DB code for two days. The DB was never the problem.

How not to get fooled

Flame graphs are sampling-based. A few things to watch for:

Sample too short. A 1-second profile of a busy server might not capture the slow code path at all. Aim for at least 30 seconds under realistic load. Longer is better.

Optimization missed by V8. Node’s JIT can fold out function calls; what looks like one big bar might be five tiny ones the profiler couldn’t separate. Run with --no-turbo-inlining if you suspect this and need granular data.

Wall-clock vs CPU. Most profilers measure CPU samples, not wall time. If your slow function is await db.query(), the time spent waiting is not on the CPU and won’t show up. For wall-clock breakdown, use a tracing tool, not a flame graph.

Multi-threaded confusion. Worker threads, child processes, and goroutines may need separate profiles or merged graphs.

A workflow that works

The workflow I use when given a “this is slow” report:

1. Reproduce the slow request locally with realistic data.
2. Run with 0x or clinic flame.
3. Hit the slow endpoint a few times to warm up, then capture.
4. Open the flame graph. Find the widest top-level bar. Drop down. Find the next.
5. Identify the leaf. Make a hypothesis. Verify with a benchmark.
6. Fix. Re-profile. Confirm improvement.

This loop takes 20 minutes for a typical bottleneck. The “let me add some logs” version takes hours and often misses the actual cause.

Three cases where flame graphs are misleading:

• I/O-bound code. Use distributed tracing or async profiling instead.
• Memory issues. Use heap snapshots, not flame graphs.
• Garbage collection pauses. Use the V8 GC traces (--trace-gc) and a memory profiler.

For the canonical “function X is using too much CPU” question, flame graphs are the answer. For other questions, use the matching tool.

The takeaway

A flame graph turns “where does the time go” from a guessing game into a five-minute investigation. Capture one, find the widest top-level bar, drop down level by level until you hit a leaf. The leaf is your bottleneck. Make one change, re-profile, confirm.

The team that adopts flame graphs as a default investigation tool stops adding console.time to random places. The next time someone says “the API is slow,” the answer is “let’s profile it,” and 30 minutes later you have a fix.

A note from Yojji

The kind of performance investigation that takes “the dashboard says p99 is up” to “we found the regression in 20 minutes and shipped a fix” (flame graphs, profilers, the muscle memory to use them) is the kind of senior engineering Yojji’s teams bring to client work.

Yojji is an international custom software development company founded in 2016, with teams across Europe, the US, and the UK. They specialize in the JavaScript ecosystem, cloud platforms, and full-cycle product engineering, including the performance work that decides whether a feature still feels good at production load.