Node.js Reference ยท CLI Flags
Node.js --cpu-prof and --heap-prof flags
Reference for node --cpu-prof and --heap-prof: write V8 CPU and heap profiles when a process exits, choose the folder and name, and open them in DevTools.
--cpu-prof starts V8's sampling CPU profiler when the process starts and writes a .cpuprofile file when it exits. --heap-prof does the same for the sampling heap profiler and writes a .heapprofile file. Both are the simplest way to profile a script without attaching a debugger: run the program once, then open the file in a tool.
CPU profiles answer "where does the time go?". Heap profiles answer "which call sites allocate the memory that is still alive?".
// shell: node --cpu-prof --cpu-prof-dir=./profiles app.js
Try it
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 node:readline or process.stdin), it gets the next line from this box.
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 node:readline or process.stdin), it gets the next line from this box.
Syntax
// shell
node --cpu-prof [--cpu-prof-dir=<dir>] [--cpu-prof-name=<file>] [--cpu-prof-interval=<microseconds>] <script>
node --heap-prof [--heap-prof-dir=<dir>] [--heap-prof-name=<file>] [--heap-prof-interval=<bytes>] <script>
| Name | Description |
|---|---|
--cpu-prof |
Enables the CPU profiler; writes <date>.<pid>.<tid>.<seq>.cpuprofile on exit. |
--heap-prof |
Enables the sampling heap profiler; writes a .heapprofile file on exit. |
--cpu-prof-dir / --heap-prof-dir |
Output folder (default: the current directory). |
--cpu-prof-name / --heap-prof-name |
Fixed file name instead of the generated one. |
--cpu-prof-interval |
CPU sampling interval in microseconds (default 1000). Smaller values give more detail and more overhead. |
--heap-prof-interval |
Average bytes allocated between heap samples (default 524288). |
Returns: nothing; the effect is a file on disk.
Edge cases: the profile is written when the process exits normally (end of the event loop or process.exit()). A hard kill with SIGKILL, a crash, or an out-of-memory abort writes nothing. Worker threads produce their own files, identified by the thread id in the default name.
Usage notes
- Open CPU profiles in Chrome DevTools (Performance or "JavaScript Profiler" panel, load the file) or in VS Code, which can display
.cpuprofilefiles directly. Flame charts and "bottom up" tables show which functions own the most self time. - Heap profiles load into the Memory panel ("Load profile"). They show allocation sites sorted by retained size, not individual objects; for object-level views use
v8.writeHeapSnapshot(). - Profile realistic work. A script that runs for 20 ms mostly measures startup. Run the hot path for seconds.
- Overhead is low but real. The sampler is cheap enough for staging and many production investigations; use a larger interval when in doubt.
- Servers that never exit: the file is written only on exit, so stop the server with a handler for
SIGINTthat callsprocess.exit()(or just let it close gracefully).SIGINTwithout a handler may skip writing. - Child processes inherit the flags only through
NODE_OPTIONS. Giving each a distinct--cpu-prof-dirkeeps files apart. - Source maps: function names and positions refer to the generated JavaScript; DevTools can map them if the source maps are reachable.
- Related tools:
--prof(the older V8 tick profiler),node --inspectfor interactive profiling, and thenode:inspectormodule for starting and stopping profiles from code.