diff --git a/configure b/configure index c9d598b799204b..3c3d4c96083b92 100755 --- a/configure +++ b/configure @@ -488,6 +488,11 @@ parser.add_option('--without-npm', dest='without_npm', help='do not install the bundled npm (package manager)') +parser.add_option('--without-node-report', + action='store_true', + dest='without_node_report', + help='build without node-report'), + parser.add_option('--without-perfctr', action='store_true', dest='without_perfctr', @@ -903,6 +908,7 @@ def configure_node(o): o['variables']['OS'] = 'android' o['variables']['node_prefix'] = options.prefix o['variables']['node_install_npm'] = b(not options.without_npm) + o['variables']['node_report'] = b(not options.without_node_report) o['default_configuration'] = 'Debug' if options.debug else 'Release' host_arch = host_arch_win() if os.name == 'nt' else host_arch_cc() diff --git a/doc/api/index.md b/doc/api/index.md index 5ba0da6a7fb5aa..7a22e263fb62be 100644 --- a/doc/api/index.md +++ b/doc/api/index.md @@ -36,6 +36,7 @@ * [Internationalization](intl.html) * [Modules](modules.html) * [Net](net.html) +* [Node Report](node_report.html) * [OS](os.html) * [Path](path.html) * [Performance Hooks](perf_hooks.html) diff --git a/doc/api/node_report.md b/doc/api/node_report.md new file mode 100644 index 00000000000000..7e8e7b3f732448 --- /dev/null +++ b/doc/api/node_report.md @@ -0,0 +1,116 @@ +# node-report + +Delivers a human-readable diagnostic summary, written to file +or retrieved as a text. + +The report is intended for development, test and production +use, to capture and preserve information for problem determination. +It includes JavaScript and native stack traces, heap statistics, +platform information and resource usage etc. With the report enabled, +reports can be triggered on unhandled exceptions, fatal errors, signals. + +Many capabilities are available as APIs too, for being consumed in-process. + +Iin-built node-report function is supported in Node.js versions 11.0.0 onwards. +For Node.js versions 8 and below, please use it's [npm counterpart][] instead. + +## Usage + +```bash +node --report-events fatalerror,signal,exception app.js +``` +A report will be triggered automatically on unhandled exceptions and fatal +error events (for example out of memory errors), and can also be triggered +by sending a USR2 signal to a Node.js process (not supported on Windows). + +A report can also be triggered via an API call from a JavaScript +application. + +```js +const util = require('util'); +util.triggerReport(); +``` +The content of a report can also be returned as a JavaScript string via an +API call from a JavaScript application. + +```js +const util = require('util'); +const report_str = util.getReport(); +console.log(report_str); +``` + +These APIs can be used without adding the automatic exception +and fatal error hooks and the signal handler. + +Content of the report consists of a header section containing the event +type, date, time, PID and Node version, sections containing JavaScript and +native stack traces, a section containing V8 heap information, a section +containing libuv handle information and an OS platform information section +showing CPU and memory usage and system limits. An example report can be +triggered using the Node.js REPL: + +```raw +$ node +> const util = require('util'); +> util.triggerReport(); +Writing Node.js report to file: node-report.20180820.091102.8480.001.txt +Node.js report completed +> +``` + +When a report is triggered, start and end messages are issued to stderr +and the filename of the report is returned to the caller. The default filename +includes the date, time, PID and a sequence number. Alternatively, a filename +can be specified as a parameter on the `triggerReport()` call. + +```js +require('util').triggerReport('myReportName'); +``` + +Both `triggerReport()` and `getReport()` can take an optional `Error` object +as a parameter. If an `Error` object is provided, the message and stack trace +from the object will be included in the report in the `JavaScript Exception +Details` section. +When using node-report to handle errors in a callback or an exception handler +this allows the report to include the location of the original error as well +as where it was handled. +If both a filename and `Error` object are passed to `triggerReport()` the +`Error` object should be the second parameter. + +```js +try { + process.chdir('/foo/foo'); +} catch (err) { + util.triggerReport(err); +} +// ... +``` + +## Configuration + +Additional configuration is available using the following APIs: + +```js +const util = require('util'); +util.setEvents('exception+fatalerror+signal'); +util.setSignal('SIGUSR2|SIGQUIT'); +util.setFileName('stdout|stderr|'); +util.setDirectory(''); +util.setVerbose('yes|no'); +``` + +Configuration on module initialization is also available via +environment variables: + +```bash +export NODEREPORT_EVENTS=exception+fatalerror+signal+apicall +export NODEREPORT_SIGNAL=SIGUSR2|SIGQUIT +export NODEREPORT_FILENAME=stdout|stderr| +export NODEREPORT_DIRECTORY= +export NODEREPORT_VERBOSE=yes|no +``` + +Detailed API documentation can be found under [`util`][] section. + +[npm counterpart]: https://www.npmjs.com/package/node-report +[`util`]: util.html diff --git a/doc/api/util.md b/doc/api/util.md index 2fadc6b9ef2ee7..fef9a6f5f367db 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -270,6 +270,26 @@ util.formatWithOptions({ colors: true }, 'See object %O', { foo: 42 }); // when printed to a terminal. ``` +## util.getNodeReport() + + +* Returns: {string} + +Returns the nore report as a string. + +Generates a human readable diagnostic summary. The report is intended for +development, test and production use, to capture and preserve information +for problem determination. It includes JavaScript and native stack traces, +heap statistics, platform information and resource usage etc. + +```js +const util = require('util'); +const report = util.getNodeReport(); +console.log(report); +``` + ## util.getSystemErrorName(err) + +* `events` {string} + +Runtime configuration of node report data capture. The string can be a comma- +separated list of one or more of: +`exception`: auto-generate a report on unhandled exceptions +`fatalerror`: auto-generate a report on unhandled internal fault +(such as out of memory errors or native assertions) +`signal`: auto-generate a report in response to a signal raised on the process. +This is convinient for collecting snapshot information of the running process at +custom program points. + +```js +const util = require('util'); +// trigger report only on uncaught exceptions +util.setReportEvents('exception'); + +// trigger for both internal error and external signal +util.setReportEvents('fatalerror+signal'); +``` + +## util.setReportSignal(signal) + + +* `signal` {string} + +Runtime modification to the node report data capture signal (default SIGUSR2). +Convinient when the execution environment already uses SIGUSR2 for other +purposes and wants Node to use another one for report generation purpose. + +```js +const util = require('util'); +util.setReportSignal('SIGQUIT'); +``` + +Multiple signals are allowed, in which case supply them as `OR` separated: + +```js +const util = require('util'); +util.setReportSignal('SIGUSR2|SIGQUIT'); +``` +This function does not work on Windows. + ## Class: util.TextDecoder + +* `filename` {string} The file to write into. **Default:** an empty string. +* Returns: {string} + +Returns the filename of the generated report. + +Triggers and produces the node report (a human readable snapshot of the internal +state of Node runtime), writes into a file at the location from where this Node +process was launched. + +```js +const util = require('util'); +util.triggerNodeReport(); +``` + +When a report is triggered, start and end messages are issued to stderr and the +filename of the report is returned to the caller. The default filename includes +the date, time, PID and a sequence number. Alternatively, a filename can be +specified as a parameter on the triggerNodeReport() call. + +```js +util.triggerNodeReport('myReportName'); +``` + ## util.types