How do you use Flamegraphs to diagnose performance and CPU bottlenecks in Node.js?

Short answer

Flamegraphs show how much CPU time each function uses by tracing the call stack; wider blocks indicate functions that consume more CPU time.

Explanation

To find why CPU usage reached 100%, run Node.js with the --cpu-prof flag to generate a performance profile, or connect the app to an advanced diagnostic tool such as clinic.js. The results appear as a flamegraph: the horizontal axis shows the percentage of total execution time, and the vertical axis shows call-stack depth, pointing you to the function responsible for the slowdown.

Code example

node --cpu-prof --cpu-prof-dir=./profiles app.js      # writes *.cpuprofile files
# Open the .cpuprofile in Chrome DevTools → Performance, or build an interactive flamegraph:
npx 0x -- node app.js
# Reading it: the x-axis is time spent (not chronology); wide frames at the top are the hot functions.

Common mistakes

• Assuming the application is slow because of CPU functions without first checking I/O wait times.

Follow-up questions

• How do Worker Threads differ from Child Processes in Node.js?

Sources

• Node.js — Flame Graphs