Profiling & Performance

Source: Node.js API: Performance measurement APIs, Node.js API: Command-line options, Node.js API: Modules: node:module API, Node.js API: Benchmark runner, Node.js API: Inspector

Every CPU example below profiles the same small program, a stand-in for a Bookshelf start-up task that builds a catalogue and derives a digest per ISBN with a deliberately expensive synchronous call. The real culprit is obvious here; the point is to see how each tool reports it.

Source: Node.js Learn: Profiling Node.js Applications

--cpu-prof starts V8’s sampling CPU profiler when the process starts and writes a .cpuprofile file when it exits. A sampling profiler interrupts the thread at a fixed interval, records the current call stack, and later counts how often each function appeared at the top of the stack (self time) or anywhere on it (total time). --cpu-prof-interval sets the interval in microseconds (default 1000), --cpu-prof-dir the output directory (default: the current directory, or --diagnostic-dir if set) and --cpu-prof-name the file name; the name template supports ${pid}.

Source: Node.js API: --cpu-prof, Node.js API: --cpu-prof-dir

The default file name is CPU.<date>.<time>.<pid>.<tid>.<seq>.cpuprofile; the run above produced a three-digit sequence (001) where the CLI reference shows a single digit. --cpu-prof-name 'hot.${pid}.cpuprofile' --cpu-prof-interval 500 worked the same on Node.js 24.21.0 and Node.js 22.23.3, where pbkdf2Sync took about 98.8% and 98.6% of the time. A .cpuprofile is plain JSON (its top-level keys are nodes, startTime, endTime, samples and timeDeltas) in the format of the inspector’s Profiler domain, which DevTools-based viewers consume; loading it into a particular viewer was not tested for this page, so check that tool’s documentation. The following script is all that was needed to produce the table above.

Source: Node.js API: Command-line options (--cpu-prof), Node.js Learn: Poor Performance

Profile the code you care about, not the start-up: for a server, run it under --cpu-prof, drive realistic load, then stop it with a signal your shutdown handler turns into a normal exit (see Process, Signals & Exit Codes), because the profile is written when the process exits normally. To profile just one section of a running process, drive the V8 profiler from inside the process with the inspector’s promise API (Experimental, needs no flag).

Source: Node.js API: Inspector (CPU profiler)

--prof is the older built-in profiler. It writes a V8 log named isolate-0x<address>-<pid>-v8.log in the current directory, one line per event: each sampled "tick" plus compilation events. The log is not meant to be read directly; node --prof-process <log> turns it into a summary and a "bottom up" call tree where indented lines read as "was called by". Redirect the output to a file, because it is long.

Read the summary first: nearly all ticks are in "C", meaning native code (here OpenSSL, called from the JavaScript wrapper) rather than your JavaScript, so rewriting the JavaScript would not help. On macOS the C lines of this report were dominated by one absurdly long, wrongly resolved symbol name, an observation about this machine and not a Node.js rule; on Node.js 22.23.3 the same run put 99.9% of the ticks under "Unaccounted". The , ~ and ^ prefixes in front of function names tell you which code tier V8 was running: V8’s own profiling guide says a leading marks a function optimised by TurboFan, and the ~ and ^ markers seen here were not explained in the pages this page cites. node --prof-process --preprocess <log> prints JSON instead of text, for tooling.

Source: Node.js Learn: Profiling Node.js Applications, Node.js API: Command-line options (--prof, --prof-process), V8: Using V8’s sample-based profiler

For choosing between the two built-in profilers: --cpu-prof produces one self-contained JSON file that DevTools and other viewers open, has a configurable sampling interval and no processing step, so it is the default recommendation. --prof still has a role when you want V8’s view of compilation events, or when you follow the Learn guide’s walkthrough, and --prof-process is bundled with the Node.js binary so no extra install is needed.

A flame graph draws the sampled call stacks as nested boxes: the x axis is the share of samples (not time order), the y axis is stack depth, and a wide box at the top of a tower is a function that was on the CPU a lot. Two kinds of input exist. The first is a .cpuprofile, which viewers such as Chrome DevTools render directly. The second is a file of folded stacks, one line per distinct stack with the stack frames separated by semicolons and a sample count at the end, which is the input format of Brendan Gregg’s flamegraph.pl and of several web viewers. The script below converts a .cpuprofile into that folded format (here weighting by microseconds instead of sample counts).

Source: Node.js API: Inspector, CPU profiler, FlameGraph tools (GitHub)

Read it left to right as the call chain (buildCatalog called hashIsbn, which called pbkdf2Sync) followed by the weight. Pipe such a file to flamegraph.pl to get an SVG; that step was not run for the folded file above, but the equivalent perf pipeline was run end to end in the next section.

Source: Node.js Learn: Flame Graphs

perf is the Linux kernel’s profiler. It samples the whole process, so unlike the V8 profilers it sees native frames, OpenSSL, libuv and the kernel, at the price of needing help to name JavaScript functions: JIT-compiled code has no symbols on disk. Node.js can write a map from addresses to function names, /tmp/perf-<pid>.map, which perf reads. --perf-basic-prof maps every code object and keeps appending to the file, which can grow without bound; --perf-basic-prof-only-functions writes less and is the one the Learn guide recommends for production profiling. --interpreted-frames-native-stack gives interpreted functions their own entry points so their names show up too. Without these flags you still get a graph, but most boxes read v8::Function::Call.

On macOS there is no perf; the Node.js flags still ran there and wrote nothing but the map file in /tmp. The commands above were run on Linux in a privileged container of the official node:26-slim image (Node.js 26.10.0, perf 6.12.111, arm64, inside Docker Desktop’s virtual machine, where the sampling event shown by an earlier cycles:u attempt was the software event task-clock). The report listed native code first, as expected for a program that spends its time in OpenSSL, and the JavaScript callers were named thanks to the map file.

The Learn guide also shows a sed command that removes engine internals from perfs.out before collapsing. Its patterns match the older LazyCompile: prefix; the map written by Node.js 26 labels functions JS:~name and JS:^name, as the output above shows, so some filter patterns match nothing any more. The full pipeline (filter, stackcollapse-perf.pl, flamegraph.pl --colors=js) still produced a 40 KB SVG from this profile. Run the unfiltered graph too if the filtered one looks odd. In containers perf needs privileges (the run above used --privileged), so on a production cluster prefer a profile you can capture inside the process, such as --cpu-prof or the inspector. V8 also documents its own --perf-prof flag with perf inject --jit for a more complete symbol pipeline; that route was not tried here.

Source: Node.js Learn: Using Linux Perf, Node.js Learn: Flame Graphs, V8: Linux perf integration

node:perf_hooks implements parts of the W3C High Resolution Time, Performance Timeline, User Timing and Resource Timing specifications plus Node.js extensions. performance.now() gives a monotonic millisecond timestamp (use it instead of Date.now() for durations); performance.mark(name) records a named instant and performance.measure(name, start, end) records the duration between two marks, or between two timestamps passed in an options object. Entries land in the Performance Timeline, where a PerformanceObserver receives them asynchronously. Marks and measures accumulate until you clear them with clearMarks() and clearMeasures(), so a long-running server that measures every request must clear them or the timeline keeps growing.

In this run the entries reached the observer ordered by start time, not by the order the measure() calls were made, and the observer runs after the current synchronous code finishes, which is why the example yields before reading. Naming a start mark that does not exist throws.

Source: Node.js API: Performance measurement APIs

performance.timerify(fn) returns a wrapper that times every call. The timing is delivered as 'function' entries to an observer (the entry’s detail holds the call arguments), and, more usefully for hot functions, can be recorded into a histogram passed as the histogram option, so you keep the whole distribution instead of one number. If fn returns a promise the duration is reported when it settles. A histogram made by createHistogram() stores integers (nanoseconds when fed by timerify) and answers count, min, max, mean, stddev and percentile(p) with bounded memory, which is the reason to prefer it over an array of timings. Mind the cost: observing 'function' entries on a function called a hundred thousand times creates a hundred thousand entries, so use the histogram alone when you only need statistics.

Source: Node.js API: performance.timerify(), Node.js API: perf_hooks.createHistogram()

The observer line prints last because entries are delivered after the synchronous loop ends. The maximum is orders of magnitude above the median: averages hide exactly the outliers (a garbage collection, a JIT compile) that users notice, so report percentiles.

Histograms also grew a statistics toolkit recently, handy for comparing two builds. welchTest() compares two means, cohensD() and cliffsD() give effect sizes, ksTest() compares distributions, percentileCI() and (from 26.9.0) meanCI() give confidence intervals, and burnRate() and ewmaMean track a service-level objective. They need Node.js 26.8.0 or later, or 24.21.0 on the 24 line, and do not exist on Node.js 22.

The two lines show why a p-value is not a verdict: the same code gave a convincing result on one run and an inconclusive one on another, and Cohen’s d says the difference, even when "significant", is small relative to the noise. Treat such numbers as a prompt to measure again with a proper benchmark runner, covered below. The observer-free histogram API is also how you export latency from a service: record request durations, and read percentile(99) on a timer.

Source: Node.js API: Performance measurement APIs (timerify, createHistogram, Histogram)

Two more entry sources are worth knowing. A PerformanceObserver for the 'gc' entry type receives one entry per collection, with kind in detail (constants.NODE_PERFORMANCE_GC_MINOR for a scavenge, NODE_PERFORMANCE_GC_MAJOR, NODE_PERFORMANCE_GC_INCREMENTAL, NODE_PERFORMANCE_GC_WEAKCB, and NODE_PERFORMANCE_GC_MINOR_MARK_SWEEP in the Node.js 26 documentation). The older top-level kind and flags properties of such an entry are deprecated, so read entry.detail. performance.nodeTiming reports when the process, V8 and the event loop started.

On the same program Node.js 24 recorded 33 entries (24.7 ms) and Node.js 22 recorded 112 entries (120.2 ms), a reminder that collector behaviour differs by V8 version, so compare runs on the same line. GC tuning and heap analysis continue in the page on memory and leaks.

Source: Node.js API: Performance measurement APIs (PerformanceNodeEntry, Garbage Collection details, performance.nodeTiming)

Two metrics describe whether the single JavaScript thread keeps up. Event loop delay (ELD) is how late a timer fires: monitorEventLoopDelay({ resolution }) samples with a repeating timer (default every 10 ms) and records the lateness into a histogram in nanoseconds; call enable() to start and disable() to stop (an ELDHistogram is also disposable since v24.2.0). Event loop utilisation (ELU) is the fraction of time the loop was busy rather than waiting in the OS for events: performance.eventLoopUtilization() returns cumulative idle, active and utilization, and passing an earlier result returns the difference since then. ELU is not CPU usage: a loop blocked in a synchronous call, even a sleep, counts as 100% utilised.

Source: Node.js API: perf_hooks.monitorEventLoopDelay(), Node.js API: performance.eventLoopUtilization()

At a 10 ms resolution an idle loop reports about 11 ms: the timer interval itself shows up in the samples (an observation on this machine), so judge a loop by how far the percentiles move from the idle baseline, not by the absolute value. The blocking call stretched the maximum to about a hundred milliseconds and pushed ELU from near zero to 0.65. Calling reset() on the histogram immediately before a long blocking section lost that sample in a run of this page’s code, so take the readings you need before resetting. Since 26.5.0 (and 24.19.0) monitorEventLoopDelay({ samplePerIteration: true }) samples once per loop iteration instead of by timer; the two modes give significantly different numbers and must not be compared with each other, and the per-iteration mode does not keep an idle loop alive.

In production, export percentile(99) of delay and the ELU of a window as metrics (see the page on diagnostic reports, logging and observability), alert when delay or ELU stays high, and use ELU to decide whether to add processes with Cluster & Scaling or threads with Worker Threads: high ELU with low CPU points at blocking synchronous work, high ELU with high CPU at real computation. ELU is available inside worker threads too, where it describes that thread’s own loop.

Source: Node.js API: Performance measurement APIs (monitorEventLoopDelay, eventLoopUtilization), Node.js Learn: Poor Performance

Before JavaScript runs, V8 must compile it. The module compile cache stores V8’s code cache on disk, so the next process can skip most of that work for CommonJS, ES module and TypeScript sources alike. The first load of a module graph is slightly slower (it also writes the cache); later loads of unchanged modules are faster. Enable it with NODE_COMPILE_CACHE=<dir> in the environment or by calling module.enableCompileCache() as early as possible (it never throws: inspect the returned status, which is one of module.constants.compileCacheStatus: FAILED, ENABLED, ALREADY_ENABLED or DISABLED). Without a directory it uses a folder under os.tmpdir() or the environment variable. This example loads a large dependency (the typescript package, version 5.9.3, installed with npm in a scratch project) and times it.

Source: Node.js API: module.enableCompileCache(), Node.js API: module.constants.compileCacheStatus

The status is ALREADY_ENABLED because the environment variable enabled the cache before the script ran. The cold-to-warm times were 93 to 45 ms on Node.js 26, 94 to 43 ms on 24.21.0 and 151 to 90 ms on 22.23.3 (on Node.js 22 the JavaScript API takes only a directory string, and the documentation labels it Active Development). Facts to remember:

It pays off for command-line tools and short-lived processes (a CLI, a serverless function, test workers) whose time goes into loading code; a long-running server benefits only at start-up. Create the cache in a build step and ship it with the application for the best effect.

Source: Node.js API: node:module (Module compile cache), Node.js API: Command-line options (NODE_COMPILE_CACHE), V8: Improved code caching

node:bench is a benchmark runner in core, new in Node.js 26.9.0, and the only part of this page that is not Stable. The module is marked Stability 1.0 (Early Development) and the CLI flags 1 (Experimental), it is only available when Node.js starts with --experimental-bench, it can only be imported with the node: scheme, and it does not exist on Node.js 24 or 22. A benchmark calls b.start() and b.end(operations) exactly once around the measured work (or b.record(sample) with an externally measured sample), so setup and cleanup stay outside the timing. The runner executes benchmarks serially, warms them up, collects samples, and the default spec reporter prints the mean rate, a 95% confidence interval, the median and warnings (noisy for a coefficient of variation above 5%, skewed for an absolute skewness above 1).

Source: Node.js API: suite(), Node.js API: bench()

Useful options: --bench-name-pattern=<regex> runs only matching benchmarks (the others are reported as skipped), --bench-samples=<n> and --bench-warmup=<n> override the counts, --bench-reporter=json emits newline-delimited JSON events (bench:plan, bench:start, bench:sample, bench:complete, bench:summary) and --bench-isolation=process (the default) runs each file in its own child process. Benchmark files declare benchmarks and must not call run() themselves; embedders can use createRunner() instead.

The documentation’s own warnings are the lesson. A statistically tidy result does not prove you measured what you meant: make the result of the measured work observable (the example sums the slug lengths and checks the total, so the engine cannot discard the calls), batch enough operations per sample to amortise timer reads, look at the raw samples for GC pauses or insufficient warm-up, and confirm surprising results with a differently shaped benchmark. node:bench does not choose a baseline or give a pass/fail verdict; it exposes samples so a higher-level tool can run the statistics, and the histogram methods above are the same toolkit.

Source: Node.js API: Benchmark runner, Node.js API: Command-line options (--bench)

Source: Node.js Learn: Poor Performance, Node.js Learn: Node.js, the difference between development and production

Three habits matter more than any flag. Profile a production-like build (NODE_ENV=production, the same Node.js version, the same data volume). Profile under load that resembles real traffic, because an idle process profiles as idle. And keep every number in its context: sampling profilers perturb the program, a single run proves little, and a laptop, a container and a VM disagree.

The Learn guides and older articles still describe the pipeline as it was when LazyCompile: appeared in perf output and when external tools were needed to read V8 ticks; the tools they point to (the V8 tick processor, perf) are still valid, but flags, labels and file names have moved on as shown above.

Samer Buna’s Efficient Node.js (O’Reilly, 2025) mentions the built-in --prof profiler and the DevTools profiler in its debugging chapter, and times asynchronous code with console.time and console.timeEnd. Both still work. Missing or superseded for current Node.js:

Jonathan Wexler’s Node.js Projects (O’Reilly, 2025) is a project-building book in which profiling is not a topic, so it stays a source for the Bookshelf-style scenarios rather than for this page.