node-report: merge into core

Make node-report part of core runtime, to satisfy its tier1 status
on diagnostic tooling.

No new functionalities have been added, changes that are required for
melding it as a built-in capability has been affected on the module
version of node-report (https://github.com/nodejs/node-report)

Refs: nodejs#19661
Refs: nodejs#18760
Refs: nodejs/node-report#103

Author: gireeshpunathil

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()

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)

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|<filename>');
+util.setDirectory('<full path>');
+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|<filename>
+export NODEREPORT_DIRECTORY=<full path>
+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

doc/api/util.md

@@ -270,6 +270,26 @@ util.formatWithOptions({ colors: true }, 'See object %O', { foo: 42 });
 // when printed to a terminal.
 ```
 
+## util.getNodeReport()
+<!-- YAML
+added: v11.0.0
+-->
+
+* 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)
 <!-- YAML
 added: v9.7.0
@@ -755,6 +775,55 @@ added: v8.0.0
 * {symbol} that can be used to declare custom promisified variants of functions,
 see [Custom promisified functions][].
 
+## util.setReportEvents(events)
+<!-- YAML
+added: v11.0.0
+-->
+
+* `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)
+<!-- YAML
+added: v11.0.0
+-->
+
+* `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
 <!-- YAML
 added: v8.3.0
@@ -919,6 +988,34 @@ encoded bytes.
 
 The encoding supported by the `TextEncoder` instance. Always set to `'utf-8'`.
 
+## util.triggerNodeReport([filename])
+<!-- YAML
+added: v11.0.0
+-->
+
+* `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
 <!-- YAML
 added: v10.0.0

lib/util.js

@@ -1540,3 +1540,28 @@ module.exports = exports = {
                   'util.puts is deprecated. Use console.log instead.',
                   'DEP0027')
 };
+
+const {
+  triggerNodeReport,
+  getNodeReport,
+  setReportEvents,
+  setReportSignal,
+  setReportFileName,
+  setReportDirectory,
+  setReportverbose,
+} = process.binding('util');
+
+if (triggerNodeReport !== undefined)
+  exports.triggerNodeReport = triggerNodeReport;
+if (getNodeReport !== undefined)
+  exports.getNodeReport = getNodeReport;
+if (setReportEvents !== undefined)
+  exports.setReportEvents = setReportEvents;
+if (setReportSignal !== undefined)
+  exports.setReportSignal = setReportSignal;
+if (setReportFileName !== undefined)
+  exports.setReportFileName = setReportFileName;
+if (setReportDirectory !== undefined)
+  exports.setReportDirectory = setReportDirectory;
+if (setReportverbose !== undefined)
+  exports.setReportverbose = setReportverbose;

node.gyp

@@ -626,6 +626,33 @@
             'src/tls_wrap.h'
           ],
         }],
+      [ 'node_report=="true"', {
+        'sources': [
+          'src/node_report.cc',
+          'src/node_report_module.cc',
+          'src/node_report_utils.cc',
+        ],  
+        'defines': [
+          'NODE_REPORT',
+          'NODEREPORT_VERSION="1.0.0"',
+        ],  
+        'conditions': [
+          ['OS=="win"', {
+            'libraries': [
+              'dbghelp.lib',
+              'Netapi32.lib',
+              'PsApi.lib',
+              'Ws2_32.lib',
+            ],  
+            'dll_files': [
+              'dbghelp.dll',
+              'Netapi32.dll',
+              'PsApi.dll',
+              'Ws2_32.dll',
+            ],  
+          }], 
+        ],  
+      }], 
       ],
     },
     {