Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท process

Node.js process.report object

Reference for process.report in Node.js: getReport(), writeReport(), automatic reports on errors and signals, and what the JSON diagnostic report contains.

process.report produces a diagnostic report: a JSON snapshot of the running process. It contains the JavaScript and native stack, V8 heap statistics, loaded libraries, open handles, environment variables, resource usage and details of the operating system. Support engineers love it because it explains a hang or a crash without a debugger.

You can create a report on demand with getReport() or writeReport(), or ask Node to write one automatically when an uncaught exception, a fatal error or a signal happens.

NODE
const report = process.report.getReport();
console.log(report.header.nodejsVersion);

Try it

Node.js Taking a report on demand

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.

Node.js Report settings and an error report

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

NODE
process.report.getReport([err])
process.report.writeReport([filename][, err])
process.report.compact          // boolean
process.report.directory        // string
process.report.filename         // string
process.report.reportOnFatalError       // boolean
process.report.reportOnSignal           // boolean
process.report.reportOnUncaughtException // boolean
process.report.excludeNetwork   // boolean
process.report.signal           // string, default 'SIGUSR2'
Name Description
err Optional Error. Its stack is used as the JavaScript stack of the report instead of the current one.
filename File name (or path) to write. Defaults to a generated name that includes the date, process id and sequence number.

Returns: getReport() returns the report as an object. writeReport() returns the file name it wrote.

Settings:

Property Meaning
compact Write single-line JSON instead of pretty-printed.
directory, filename Where automatic reports go. Empty strings mean the current directory and a generated name.
reportOnFatalError Write a report when the process dies from a fatal error such as out-of-memory.
reportOnUncaughtException Write a report on an uncaught exception.
reportOnSignal Write a report when the process receives signal. Not supported on Windows.
excludeNetwork Leave out network interface and DNS details, which can be slow to collect.

Errors / edge cases: a non-Error first argument throws ERR_INVALID_ARG_TYPE. If the file cannot be created, writeReport() throws an error from the file system.

Usage notes

  • The same switches exist as flags: --report-uncaught-exception, --report-on-fatalerror, --report-on-signal, --report-compact, --report-dir and --report-filename. Production services often start with the first two.
  • Reports contain secrets. The environmentVariables section lists every variable, including tokens and passwords. Treat report files like core dumps and never upload them publicly.
  • Reports are fairly large (hundreds of KB), because they include shared libraries and resource data. Generating one briefly blocks the event loop.
  • The header.trigger field says what caused it: GetReport, API, Exception, FatalError or Signal.
  • Find hangs: send the configured signal (kill -USR2 <pid>) to a stuck process that started with --report-on-signal and read the libuv section for open handles that keep the loop alive.
  • Leave the file name empty on servers that restart often, so each report gets a unique name.
  • Stability: the report format may gain fields between releases; code that parses it should ignore unknown keys.