Master Node.js Diagnostics: Core Dump, Heap Dump, CPU Profiling & More

TL;DR This article introduces diagnostic tricks for Node.js: Core dump, Heap dump, CPU dump, Trace Event, and Diagnostic Reports.

Core Dump

When a server application crashes in unexpected states, the OS can generate a core file that contains memory, registers, and stack information. To enable core files, set ulimit -c unlimited. Three ways to produce a core file:

Send SIGSEGV: kill -11 <pid>

Start Node.js with --abort-on-uncaught-exception flag.

Use gcore <pid> (requires gdb).

Analyze the core file with LLDB, GDB, MDB, etc., to determine the crash cause.

Heap Dump

V8 provides built‑in heap profiling. Enable it with the --heap-prof family of flags, for example:

--heap-prof                    Start the V8 heap profiler on start up, and write the heap profile to disk before exit.
--heap-prof-dir=...            Directory where the V8 heap profiles generated by --heap-prof will be placed.
--heap-prof-interval=...       Sampling interval in bytes (default: 512 * 1024).
--heap-prof-name=...           File name of the V8 CPU profile.
--heapsnapshot-signal=...      Generate heap snapshot on specified signal.

After running the program, locate the generated *.heapprofile file, load it in Chrome DevTools → Memory tab, and inspect large objects that may cause memory‑related crashes.

Alternatively, use the heapdump npm package:

const {EventEmitter} = require('events');
const heapdump = require('heapdump');
global.test = new EventEmitter();
// first dump
heapdump.writeSnapshot('./' + Date.now() + '.heapsnapshot');
// run code that may leak
function run3() {
  const innerData = new Buffer(100);
  const outClosure3 = function () {
    void innerData;
  };
  test.on('error', () => {
    console.log('error');
  });
  outClosure3();
}
for (let i = 0; i < 10; i++) {
  run3();
}
gc(); // trigger GC
// second dump
heapdump.writeSnapshot('./' + Date.now() + '.heapsnapshot');

Chrome DevTools can diff two heap snapshots.

CPU Dump

Enable V8 CPU profiling with the --prof flag: NODE_ENV=production node --prof app.js After load testing (e.g., using ab -k -c 20 -n 250 http://localhost:8080/auth), a isolate-*.log file is generated. Convert it to a readable form with:

node --prof-process isolate-0x...-v8.log > tick.txt

The tick file shows where the program spends time; functions consuming >80% indicate performance bottlenecks. See the official V8 profiling guide for details.

Trace Event

Trace events can be enabled via the --trace-event-categories flag or the built‑in trace_events module. Common categories include:

node

node.async_hooks

node.bootstrap

node.console

node.dns.native

node.environment

node.fs.sync

node.perf (and sub‑categories node.perf.usertiming, node.perf.timerify)

node.promises.rejections

node.vm.script

v8

Enable them, for example:

node --trace-event-categories v8,node,node.async_hooks --trace-event-file-pattern '${pid}-${rotation}.log' server.js

Open the resulting .log files in chrome://tracing to visualize the trace data.

Diagnostic Reports

Diagnostic Reports collect crash‑related information without reproducing the crash. Enable with --experimental-report and trigger on uncaught exceptions using --report-uncaught-exception:

node --experimental-report --report-uncaught-exception test.js

The generated JSON report includes error stack, heap statistics, platform details, and resource usage. Additional flags: --report-on-fatalerror – collect C++ crash info. --report-on-signal – trigger via signal. --report-signal=signal – specify signal (default sigusr2). --report-directory=directory – set output directory. --report-filename=filename – set file name pattern.

See the official Node.js documentation for full details.