{ "type": "module", "source": "doc/api/report.md", "introduced_in": "v11.8.0", "stability": 1, "stabilityText": "Experimental", "miscs": [ { "textRaw": "Diagnostic Report", "name": "report", "introduced_in": "v11.8.0", "type": "misc", "stability": 1, "stabilityText": "Experimental", "desc": "
Delivers a JSON-formatted diagnostic summary, written to a file.
\nThe 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.
\nA complete example report that was generated on an uncaught exception\nis provided below for reference.
\n{\n \"header\": {\n \"event\": \"exception\",\n \"location\": \"OnUncaughtException\",\n \"filename\": \"report.20181221.005011.8974.001.json\",\n \"dumpEventTime\": \"2018-12-21T00:50:11Z\",\n \"dumpEventTimeStamp\": \"1545371411331\",\n \"processId\": 8974,\n \"commandLine\": [\n \"/home/nodeuser/project/node/out/Release/node\",\n \"--experimental-report\",\n \"--diagnostic-report-uncaught-exception\",\n \"/home/nodeuser/project/node/test/node-report/test-exception.js\",\n \"child\"\n ],\n \"nodejsVersion\": \"v12.0.0-pre\",\n \"glibcVersion\": \"2.17\",\n \"wordSize\": \"64 bit\",\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 \"arch\": \"x64\",\n \"platform\": \"linux\",\n \"release\": \"node\"\n },\n \"osVersion\": \"Linux 3.10.0-862.el7.x86_64 #1 SMP Wed Mar 21 18:14:51 EDT 2018\",\n \"glibc\": \"2.17\",\n \"machine\": \"Linux 3.10.0-862.el7.x86_64 #1 SMP Wed Mar 21 18:14:51 EDT 2018test_machine x86_64\"\n },\n \"javascriptStack\": {\n \"message\": \"Error: *** test-exception.js: throwing uncaught Error\",\n \"stack\": [\n \"at myException (/home/nodeuser/project/node/test/node-report/test-exception.js:9:11)\",\n \"at Object.<anonymous> (/home/nodeuser/project/node/test/node-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 \" [pc=0xa7ef87] [/home/nodeuser/project/node/out/Release/node]\",\n \" [pc=0xa81adb] report::TriggerNodeReport(v8::Isolate*, node::Environment*, char const*, char const*, std::string, v8::Local<v8::String>) [/home/nodeuser/project/node/out/Release/node]\",\n \" [pc=0xa834f2] report::OnUncaughtException(v8::FunctionCallbackInfo<v8::Value> const&) [/home/nodeuser/project/node/out/Release/node]\",\n \" [pc=0xbe6b78] [/home/nodeuser/project/node/out/Release/node]\",\n \" [pc=0xbe7596] v8::internal::Builtin_HandleApiCall(int, v8::internal::Object**, v8::internal::Isolate*) [/home/nodeuser/project/node/out/Release/node]\",\n \" [pc=0x1930cae] [/home/nodeuser/project/node/out/Release/node]\"\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\": \"68090592\",\n \"details\": \"\"\n },\n {\n \"type\": \"timer\",\n \"is_active\": false,\n \"is_referenced\": false,\n \"address\": \"140723513949920\",\n \"details\": \"repeat: 0, timeout expired: 18075165916 ms ago\"\n },\n {\n \"type\": \"check\",\n \"is_active\": true,\n \"is_referenced\": false,\n \"address\": \"140723513950072\",\n \"details\": \"\"\n },\n {\n \"type\": \"idle\",\n \"is_active\": false,\n \"is_referenced\": true,\n \"address\": \"140723513950192\",\n \"details\": \"\"\n },\n {\n \"type\": \"prepare\",\n \"is_active\": false,\n \"is_referenced\": false,\n \"address\": \"140723513950312\",\n \"details\": \"\"\n },\n {\n \"type\": \"check\",\n \"is_active\": false,\n \"is_referenced\": false,\n \"address\": \"140723513950432\",\n \"details\": \"\"\n },\n {\n \"type\": \"async\",\n \"is_active\": true,\n \"is_referenced\": false,\n \"address\": \"39353856\",\n \"details\": \"\"\n }\n ],\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 --experimental-report --diagnostic-report-uncaught-exception \\\n --diagnostic-report-on-signal --diagnostic-report-on-fatalerror app.js\n
\n--experimental-report
Enables the diagnostic report feature.\nIn the absence of this flag, use of all other related options will result in\nan error.
--diagnostic-report-uncaught-exception
Enables report to be generated on\nun-caught exceptions. Useful when inspecting JavaScript stack in conjunction\nwith native stack and other runtime environment data.
--diagnostic-report-on-signal
Enables report to be generated upon receiving\nthe specified (or predefined) signal to the running Node.js process. (See below\non how to modify the signal that triggers the report.) Default signal is SIGUSR2
.\nUseful when a report needs to be triggered from another program.\nApplication monitors may leverage this feature to collect report at regular\nintervals and plot rich set of internal runtime data to their views.
Signal based report generation is not supported in Windows.
\nUnder 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.
--diagnostic-report-on-fatalerror
Enables the report to be triggered on\nfatal errors (internal errors within the Node.js runtime, such as out of memory)\nthat leads to termination of the application. Useful to inspect various\ndiagnostic data elements such as heap, stack, event loop state, resource\nconsumption etc. to reason about the fatal error.
--diagnostic-report-directory
Location at which the report will be\ngenerated.
--diagnostic-report-filename
Name of the file to which the report will be\nwritten.
--diagnostic-report-signal
Sets or resets the signal for report generation\n(not supported on Windows). Default signal is SIGUSR2
.
--diagnostic-report-verbose
Flag that enables additional information to be\nprinted during report generation.
A report can also be triggered via an API call from a JavaScript application:
\nprocess.report.triggerReport();\n
\nThis function takes an optional additional argument filename
, which is\nthe name of a file into which the report is written.
process.report.triggerReport('./foo.json');\n
\nThis function takes an optional additional argument err
- an Error
object\nthat will be used as the context for the JavaScript stack printed in the report.\nWhen using report to handle errors in a callback or an exception handler, this\nallows the report to include the location of the original error as well\nas where it was handled.
try {\n process.chdir('/non-existent-path');\n} catch (err) {\n process.report.triggerReport(err);\n}\n// Any other code\n
\nIf both filename and error object are passed to triggerReport()
the\nerror object must be the second parameter.
try {\n process.chdir('/non-existent-path');\n} catch (err) {\n process.report.triggerReport(filename, err);\n}\n// Any other code\n
\nThe content of the diagnostic report can be returned as a JSON-compatible object\nvia an API call from a JavaScript application:
\nconst report = process.report.getReport();\nconsole.log(report);\n
\nThis function takes an optional additional argument err
- an Error
object\nthat will be used as the context for the JavaScript stack printed in the report.
const report = process.report.getReport(new Error('custom error'));\nconsole.log(report);\n
\nThe 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.
\nThe 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:
$ node\n> process.report.triggerReport();\nWriting Node.js report to file: report.20181126.091102.8480.001.json\nNode.js report completed\n>\n
\nWhen a report is triggered, 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 that influences the report generation\nconstraints are available using setDiagnosticReportOptions()
API.
process.report.setDiagnosticReportOptions({\n events: ['exception', 'fatalerror', 'signal'],\n signal: 'SIGUSR2',\n filename: 'myreport.json',\n path: '/home/nodeuser',\n verbose: true\n});\n
\nThe events
array contains one or more of the report triggering options.\nThe only valid entries are 'exception'
, 'fatalerror'
and 'signal'
.\nBy default, a report is not produced on any of these events.
signal
specifies the POSIX signal identifier that will be used\nto intercept external triggers for report generation. Defaults to\n'SIGUSR2'
.
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 such cases when standard streams are used, value in 'path'
is ignored.\nURLs are not supported. Defaults to a composite filename that contains\ntimestamp, PID and sequence number.
path
specifies the filesystem directory where the report will be written to.\nURLs are not supported. Defaults to the current working directory of the\nNode.js process.
verbose
specifies whether to print additional verbose messages\npertinent to the report generation. Defaults to false
.
// Trigger report only on uncaught exceptions.\nprocess.report.setDiagnosticReportOptions({ events: ['exception'] });\n\n// Trigger report for both internal errors as well as external signal.\nprocess.report.setDiagnosticReportOptions({ events: ['fatalerror', 'signal'] });\n\n// Change the default signal to `SIGQUIT` and enable it.\nprocess.report.setDiagnosticReportOptions(\n { events: ['signal'], signal: 'SIGQUIT' });\n
\nConfiguration on module initialization is also available via\nenvironment variables:
\nNODE_OPTIONS=\"--experimental-report --diagnostic-report-uncaught-exception \\\n --diagnostic-report-on-fatalerror --diagnostic-report-on-signal \\\n --diagnostic-report-signal=SIGUSR2 --diagnostic-report-filename=./report.json \\\n --diagnostic-report-directory=/home/nodeuser --diagnostic-report-verbose\"\n
\nSpecific API documentation can be found under\nprocess API documentation
section.