{ "type": "module", "source": "doc/api/report.md", "introduced_in": "v11.8.0", "stability": 2, "stabilityText": "Stable", "miscs": [ { "textRaw": "Diagnostic report", "name": "report", "introduced_in": "v11.8.0", "type": "misc", "stability": 2, "stabilityText": "Stable", "desc": "

Delivers a JSON-formatted diagnostic summary, written to a file.

\n

The report is intended for development, test and production use, to capture\nand preserve information for problem determination. It includes JavaScript\nand native stack traces, heap statistics, platform information, resource\nusage etc. With the report option enabled, diagnostic reports can be triggered\non unhandled exceptions, fatal errors and user signals, in addition to\ntriggering programmatically through API calls.

\n

A complete example report that was generated on an uncaught exception\nis provided below for reference.

\n
{\n  \"header\": {\n    \"reportVersion\": 1,\n    \"event\": \"exception\",\n    \"trigger\": \"Exception\",\n    \"filename\": \"report.20181221.005011.8974.0.001.json\",\n    \"dumpEventTime\": \"2018-12-21T00:50:11Z\",\n    \"dumpEventTimeStamp\": \"1545371411331\",\n    \"processId\": 8974,\n    \"cwd\": \"/home/nodeuser/project/node\",\n    \"commandLine\": [\n      \"/home/nodeuser/project/node/out/Release/node\",\n      \"--report-uncaught-exception\",\n      \"/home/nodeuser/project/node/test/report/test-exception.js\",\n      \"child\"\n    ],\n    \"nodejsVersion\": \"v12.0.0-pre\",\n    \"glibcVersionRuntime\": \"2.17\",\n    \"glibcVersionCompiler\": \"2.17\",\n    \"wordSize\": \"64 bit\",\n    \"arch\": \"x64\",\n    \"platform\": \"linux\",\n    \"componentVersions\": {\n      \"node\": \"12.0.0-pre\",\n      \"v8\": \"7.1.302.28-node.5\",\n      \"uv\": \"1.24.1\",\n      \"zlib\": \"1.2.11\",\n      \"ares\": \"1.15.0\",\n      \"modules\": \"68\",\n      \"nghttp2\": \"1.34.0\",\n      \"napi\": \"3\",\n      \"llhttp\": \"1.0.1\",\n      \"http_parser\": \"2.8.0\",\n      \"openssl\": \"1.1.0j\"\n    },\n    \"release\": {\n      \"name\": \"node\"\n    },\n    \"osName\": \"Linux\",\n    \"osRelease\": \"3.10.0-862.el7.x86_64\",\n    \"osVersion\": \"#1 SMP Wed Mar 21 18:14:51 EDT 2018\",\n    \"osMachine\": \"x86_64\",\n    \"cpus\": [\n      {\n        \"model\": \"Intel(R) Core(TM) i7-6820HQ CPU @ 2.70GHz\",\n        \"speed\": 2700,\n        \"user\": 88902660,\n        \"nice\": 0,\n        \"sys\": 50902570,\n        \"idle\": 241732220,\n        \"irq\": 0\n      },\n      {\n        \"model\": \"Intel(R) Core(TM) i7-6820HQ CPU @ 2.70GHz\",\n        \"speed\": 2700,\n        \"user\": 88902660,\n        \"nice\": 0,\n        \"sys\": 50902570,\n        \"idle\": 241732220,\n        \"irq\": 0\n      }\n    ],\n    \"networkInterfaces\": [\n      {\n        \"name\": \"en0\",\n        \"internal\": false,\n        \"mac\": \"13:10:de:ad:be:ef\",\n        \"address\": \"10.0.0.37\",\n        \"netmask\": \"255.255.255.0\",\n        \"family\": \"IPv4\"\n      }\n    ],\n    \"host\": \"test_machine\"\n  },\n  \"javascriptStack\": {\n    \"message\": \"Error: *** test-exception.js: throwing uncaught Error\",\n    \"stack\": [\n      \"at myException (/home/nodeuser/project/node/test/report/test-exception.js:9:11)\",\n      \"at Object.<anonymous> (/home/nodeuser/project/node/test/report/test-exception.js:12:3)\",\n      \"at Module._compile (internal/modules/cjs/loader.js:718:30)\",\n      \"at Object.Module._extensions..js (internal/modules/cjs/loader.js:729:10)\",\n      \"at Module.load (internal/modules/cjs/loader.js:617:32)\",\n      \"at tryModuleLoad (internal/modules/cjs/loader.js:560:12)\",\n      \"at Function.Module._load (internal/modules/cjs/loader.js:552:3)\",\n      \"at Function.Module.runMain (internal/modules/cjs/loader.js:771:12)\",\n      \"at executeUserCode (internal/bootstrap/node.js:332:15)\"\n    ]\n  },\n  \"nativeStack\": [\n    {\n      \"pc\": \"0x000055b57f07a9ef\",\n      \"symbol\": \"report::GetNodeReport(v8::Isolate*, node::Environment*, char const*, char const*, v8::Local<v8::String>, std::ostream&) [./node]\"\n    },\n    {\n      \"pc\": \"0x000055b57f07cf03\",\n      \"symbol\": \"report::GetReport(v8::FunctionCallbackInfo<v8::Value> const&) [./node]\"\n    },\n    {\n      \"pc\": \"0x000055b57f1bccfd\",\n      \"symbol\": \" [./node]\"\n    },\n    {\n      \"pc\": \"0x000055b57f1be048\",\n      \"symbol\": \"v8::internal::Builtin_HandleApiCall(int, v8::internal::Object**, v8::internal::Isolate*) [./node]\"\n    },\n    {\n      \"pc\": \"0x000055b57feeda0e\",\n      \"symbol\": \" [./node]\"\n    }\n  ],\n  \"javascriptHeap\": {\n    \"totalMemory\": 6127616,\n    \"totalCommittedMemory\": 4357352,\n    \"usedMemory\": 3221136,\n    \"availableMemory\": 1521370240,\n    \"memoryLimit\": 1526909922,\n    \"heapSpaces\": {\n      \"read_only_space\": {\n        \"memorySize\": 524288,\n        \"committedMemory\": 39208,\n        \"capacity\": 515584,\n        \"used\": 30504,\n        \"available\": 485080\n      },\n      \"new_space\": {\n        \"memorySize\": 2097152,\n        \"committedMemory\": 2019312,\n        \"capacity\": 1031168,\n        \"used\": 985496,\n        \"available\": 45672\n      },\n      \"old_space\": {\n        \"memorySize\": 2273280,\n        \"committedMemory\": 1769008,\n        \"capacity\": 1974640,\n        \"used\": 1725488,\n        \"available\": 249152\n      },\n      \"code_space\": {\n        \"memorySize\": 696320,\n        \"committedMemory\": 184896,\n        \"capacity\": 152128,\n        \"used\": 152128,\n        \"available\": 0\n      },\n      \"map_space\": {\n        \"memorySize\": 536576,\n        \"committedMemory\": 344928,\n        \"capacity\": 327520,\n        \"used\": 327520,\n        \"available\": 0\n      },\n      \"large_object_space\": {\n        \"memorySize\": 0,\n        \"committedMemory\": 0,\n        \"capacity\": 1520590336,\n        \"used\": 0,\n        \"available\": 1520590336\n      },\n      \"new_large_object_space\": {\n        \"memorySize\": 0,\n        \"committedMemory\": 0,\n        \"capacity\": 0,\n        \"used\": 0,\n        \"available\": 0\n      }\n    }\n  },\n  \"resourceUsage\": {\n    \"userCpuSeconds\": 0.069595,\n    \"kernelCpuSeconds\": 0.019163,\n    \"cpuConsumptionPercent\": 0.000000,\n    \"maxRss\": 18079744,\n    \"pageFaults\": {\n      \"IORequired\": 0,\n      \"IONotRequired\": 4610\n    },\n    \"fsActivity\": {\n      \"reads\": 0,\n      \"writes\": 0\n    }\n  },\n  \"uvthreadResourceUsage\": {\n    \"userCpuSeconds\": 0.068457,\n    \"kernelCpuSeconds\": 0.019127,\n    \"cpuConsumptionPercent\": 0.000000,\n    \"fsActivity\": {\n      \"reads\": 0,\n      \"writes\": 0\n    }\n  },\n  \"libuv\": [\n    {\n      \"type\": \"async\",\n      \"is_active\": true,\n      \"is_referenced\": false,\n      \"address\": \"0x0000000102910900\",\n      \"details\": \"\"\n    },\n    {\n      \"type\": \"timer\",\n      \"is_active\": false,\n      \"is_referenced\": false,\n      \"address\": \"0x00007fff5fbfeab0\",\n      \"repeat\": 0,\n      \"firesInMsFromNow\": 94403548320796,\n      \"expired\": true\n    },\n    {\n      \"type\": \"check\",\n      \"is_active\": true,\n      \"is_referenced\": false,\n      \"address\": \"0x00007fff5fbfeb48\"\n    },\n    {\n      \"type\": \"idle\",\n      \"is_active\": false,\n      \"is_referenced\": true,\n      \"address\": \"0x00007fff5fbfebc0\"\n    },\n    {\n      \"type\": \"prepare\",\n      \"is_active\": false,\n      \"is_referenced\": false,\n      \"address\": \"0x00007fff5fbfec38\"\n    },\n    {\n      \"type\": \"check\",\n      \"is_active\": false,\n      \"is_referenced\": false,\n      \"address\": \"0x00007fff5fbfecb0\"\n    },\n    {\n      \"type\": \"async\",\n      \"is_active\": true,\n      \"is_referenced\": false,\n      \"address\": \"0x000000010188f2e0\"\n    },\n    {\n      \"type\": \"tty\",\n      \"is_active\": false,\n      \"is_referenced\": true,\n      \"address\": \"0x000055b581db0e18\",\n      \"width\": 204,\n      \"height\": 55,\n      \"fd\": 17,\n      \"writeQueueSize\": 0,\n      \"readable\": true,\n      \"writable\": true\n    },\n    {\n      \"type\": \"signal\",\n      \"is_active\": true,\n      \"is_referenced\": false,\n      \"address\": \"0x000055b581d80010\",\n      \"signum\": 28,\n      \"signal\": \"SIGWINCH\"\n    },\n    {\n      \"type\": \"tty\",\n      \"is_active\": true,\n      \"is_referenced\": true,\n      \"address\": \"0x000055b581df59f8\",\n      \"width\": 204,\n      \"height\": 55,\n      \"fd\": 19,\n      \"writeQueueSize\": 0,\n      \"readable\": true,\n      \"writable\": true\n    },\n    {\n      \"type\": \"loop\",\n      \"is_active\": true,\n      \"address\": \"0x000055fc7b2cb180\"\n    }\n  ],\n  \"workers\": [],\n  \"environmentVariables\": {\n    \"REMOTEHOST\": \"REMOVED\",\n    \"MANPATH\": \"/opt/rh/devtoolset-3/root/usr/share/man:\",\n    \"XDG_SESSION_ID\": \"66126\",\n    \"HOSTNAME\": \"test_machine\",\n    \"HOST\": \"test_machine\",\n    \"TERM\": \"xterm-256color\",\n    \"SHELL\": \"/bin/csh\",\n    \"SSH_CLIENT\": \"REMOVED\",\n    \"PERL5LIB\": \"/opt/rh/devtoolset-3/root//usr/lib64/perl5/vendor_perl:/opt/rh/devtoolset-3/root/usr/lib/perl5:/opt/rh/devtoolset-3/root//usr/share/perl5/vendor_perl\",\n    \"OLDPWD\": \"/home/nodeuser/project/node/src\",\n    \"JAVACONFDIRS\": \"/opt/rh/devtoolset-3/root/etc/java:/etc/java\",\n    \"SSH_TTY\": \"/dev/pts/0\",\n    \"PCP_DIR\": \"/opt/rh/devtoolset-3/root\",\n    \"GROUP\": \"normaluser\",\n    \"USER\": \"nodeuser\",\n    \"LD_LIBRARY_PATH\": \"/opt/rh/devtoolset-3/root/usr/lib64:/opt/rh/devtoolset-3/root/usr/lib\",\n    \"HOSTTYPE\": \"x86_64-linux\",\n    \"XDG_CONFIG_DIRS\": \"/opt/rh/devtoolset-3/root/etc/xdg:/etc/xdg\",\n    \"MAIL\": \"/var/spool/mail/nodeuser\",\n    \"PATH\": \"/home/nodeuser/project/node:/opt/rh/devtoolset-3/root/usr/bin:/usr/local/bin:/usr/bin:/usr/local/sbin:/usr/sbin\",\n    \"PWD\": \"/home/nodeuser/project/node\",\n    \"LANG\": \"en_US.UTF-8\",\n    \"PS1\": \"\\\\u@\\\\h : \\\\[\\\\e[31m\\\\]\\\\w\\\\[\\\\e[m\\\\] >  \",\n    \"SHLVL\": \"2\",\n    \"HOME\": \"/home/nodeuser\",\n    \"OSTYPE\": \"linux\",\n    \"VENDOR\": \"unknown\",\n    \"PYTHONPATH\": \"/opt/rh/devtoolset-3/root/usr/lib64/python2.7/site-packages:/opt/rh/devtoolset-3/root/usr/lib/python2.7/site-packages\",\n    \"MACHTYPE\": \"x86_64\",\n    \"LOGNAME\": \"nodeuser\",\n    \"XDG_DATA_DIRS\": \"/opt/rh/devtoolset-3/root/usr/share:/usr/local/share:/usr/share\",\n    \"LESSOPEN\": \"||/usr/bin/lesspipe.sh %s\",\n    \"INFOPATH\": \"/opt/rh/devtoolset-3/root/usr/share/info\",\n    \"XDG_RUNTIME_DIR\": \"/run/user/50141\",\n    \"_\": \"./node\"\n  },\n  \"userLimits\": {\n    \"core_file_size_blocks\": {\n      \"soft\": \"\",\n      \"hard\": \"unlimited\"\n    },\n    \"data_seg_size_kbytes\": {\n      \"soft\": \"unlimited\",\n      \"hard\": \"unlimited\"\n    },\n    \"file_size_blocks\": {\n      \"soft\": \"unlimited\",\n      \"hard\": \"unlimited\"\n    },\n    \"max_locked_memory_bytes\": {\n      \"soft\": \"unlimited\",\n      \"hard\": 65536\n    },\n    \"max_memory_size_kbytes\": {\n      \"soft\": \"unlimited\",\n      \"hard\": \"unlimited\"\n    },\n    \"open_files\": {\n      \"soft\": \"unlimited\",\n      \"hard\": 4096\n    },\n    \"stack_size_bytes\": {\n      \"soft\": \"unlimited\",\n      \"hard\": \"unlimited\"\n    },\n    \"cpu_time_seconds\": {\n      \"soft\": \"unlimited\",\n      \"hard\": \"unlimited\"\n    },\n    \"max_user_processes\": {\n      \"soft\": \"unlimited\",\n      \"hard\": 4127290\n    },\n    \"virtual_memory_kbytes\": {\n      \"soft\": \"unlimited\",\n      \"hard\": \"unlimited\"\n    }\n  },\n  \"sharedObjects\": [\n    \"/lib64/libdl.so.2\",\n    \"/lib64/librt.so.1\",\n    \"/lib64/libstdc++.so.6\",\n    \"/lib64/libm.so.6\",\n    \"/lib64/libgcc_s.so.1\",\n    \"/lib64/libpthread.so.0\",\n    \"/lib64/libc.so.6\",\n    \"/lib64/ld-linux-x86-64.so.2\"\n  ]\n}\n
", "miscs": [ { "textRaw": "Usage", "name": "usage", "desc": "
node --report-uncaught-exception --report-on-signal \\\n--report-on-fatalerror app.js\n
\n\n

Signal based report generation is not supported in Windows.

\n

Under normal circumstances, there is no need to modify the report triggering\nsignal. However, if SIGUSR2 is already used for other purposes, then this\nflag helps to change the signal for report generation and preserve the original\nmeaning of SIGUSR2 for the said purposes.

\n\n

A report can also be triggered via an API call from a JavaScript application:

\n
process.report.writeReport();\n
\n

This function takes an optional additional argument filename, which is\nthe name of a file into which the report is written.

\n
process.report.writeReport('./foo.json');\n
\n

This function takes an optional additional argument err which is an Error\nobject that will be used as the context for the JavaScript stack printed in the\nreport. When using report to handle errors in a callback or an exception\nhandler, this allows the report to include the location of the original error as\nwell as where it was handled.

\n
try {\n  process.chdir('/non-existent-path');\n} catch (err) {\n  process.report.writeReport(err);\n}\n// Any other code\n
\n

If both filename and error object are passed to writeReport() the\nerror object must be the second parameter.

\n
try {\n  process.chdir('/non-existent-path');\n} catch (err) {\n  process.report.writeReport(filename, err);\n}\n// Any other code\n
\n

The content of the diagnostic report can be returned as a JavaScript Object\nvia an API call from a JavaScript application:

\n
const report = process.report.getReport();\nconsole.log(typeof report === 'object'); // true\n\n// Similar to process.report.writeReport() output\nconsole.log(JSON.stringify(report, null, 2));\n
\n

This function takes an optional additional argument err, which is an Error\nobject that will be used as the context for the JavaScript stack printed in the\nreport.

\n
const report = process.report.getReport(new Error('custom error'));\nconsole.log(typeof report === 'object'); // true\n
\n

The API versions are useful when inspecting the runtime state from within\nthe application, in expectation of self-adjusting the resource consumption,\nload balancing, monitoring etc.

\n

The content of the report consists of a header section containing the event\ntype, date, time, PID and Node.js version, sections containing JavaScript and\nnative stack traces, a section containing V8 heap information, a section\ncontaining libuv handle information and an OS platform information section\nshowing CPU and memory usage and system limits. An example report can be\ntriggered using the Node.js REPL:

\n
$ node\n> process.report.writeReport();\nWriting Node.js report to file: report.20181126.091102.8480.0.001.json\nNode.js report completed\n>\n
\n

When a report is written, start and end messages are issued to stderr\nand the filename of the report is returned to the caller. The default filename\nincludes the date, time, PID and a sequence number. The sequence number helps\nin associating the report dump with the runtime state if generated multiple\ntimes for the same Node.js process.

", "type": "misc", "displayName": "Usage" }, { "textRaw": "Configuration", "name": "configuration", "desc": "

Additional runtime configuration of report generation is available via\nthe following properties of process.report:

\n

reportOnFatalError triggers diagnostic reporting on fatal errors when true.\nDefaults to false.

\n

reportOnSignal triggers diagnostic reporting on signal when true. This is\nnot supported on Windows. Defaults to false.

\n

reportOnUncaughtException triggers diagnostic reporting on uncaught exception\nwhen true. Defaults to false.

\n

signal specifies the POSIX signal identifier that will be used\nto intercept external triggers for report generation. Defaults to\n'SIGUSR2'.

\n

filename specifies the name of the output file in the file system.\nSpecial meaning is attached to stdout and stderr. Usage of these\nwill result in report being written to the associated standard streams.\nIn cases where standard streams are used, the value in directory is ignored.\nURLs are not supported. Defaults to a composite filename that contains\ntimestamp, PID and sequence number.

\n

directory specifies the filesystem directory where the report will be written.\nURLs are not supported. Defaults to the current working directory of the\nNode.js process.

\n
// Trigger report only on uncaught exceptions.\nprocess.report.reportOnFatalError = false;\nprocess.report.reportOnSignal = false;\nprocess.report.reportOnUncaughtException = true;\n\n// Trigger report for both internal errors as well as external signal.\nprocess.report.reportOnFatalError = true;\nprocess.report.reportOnSignal = true;\nprocess.report.reportOnUncaughtException = false;\n\n// Change the default signal to 'SIGQUIT' and enable it.\nprocess.report.reportOnFatalError = false;\nprocess.report.reportOnUncaughtException = false;\nprocess.report.reportOnSignal = true;\nprocess.report.signal = 'SIGQUIT';\n
\n

Configuration on module initialization is also available via\nenvironment variables:

\n
NODE_OPTIONS=\"--report-uncaught-exception \\\n  --report-on-fatalerror --report-on-signal \\\n  --report-signal=SIGUSR2  --report-filename=./report.json \\\n  --report-directory=/home/nodeuser\"\n
\n

Specific API documentation can be found under\nprocess API documentation section.

", "type": "misc", "displayName": "Configuration" }, { "textRaw": "Interaction with workers", "name": "interaction_with_workers", "meta": { "changes": [ { "version": "v12.16.2", "pr-url": "https://github.com/nodejs/node/pull/31386", "description": "Workers are now included in the report." } ] }, "desc": "

Worker threads can create reports in the same way that the main thread\ndoes.

\n

Reports will include information on any Workers that are children of the current\nthread as part of the workers section, with each Worker generating a report\nin the standard report format.

\n

The thread which is generating the report will wait for the reports from Worker\nthreads to finish. However, the latency for this will usually be low, as both\nrunning JavaScript and the event loop are interrupted to generate the report.

", "type": "misc", "displayName": "Interaction with workers" } ] } ] }