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.
const report = process.report.getReport(); console.log(report.header.nodejsVersion);
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
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-dirand--report-filename. Production services often start with the first two. - Reports contain secrets. The
environmentVariablessection 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.triggerfield says what caused it:GetReport,API,Exception,FatalErrororSignal. - Find hangs: send the configured signal (
kill -USR2 <pid>) to a stuck process that started with--report-on-signaland read thelibuvsection 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.