doc: add node-report documentation

a separate section added for node-report at top level
main documentation added to doc/api/report.md
API documentation added to doc/api/process.md

PR-URL: #22712
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Michael Dawson <[email protected]>
Reviewed-By: Vse Mozhet Byt <[email protected]>

Author: vipinmenon

doc/api/cli.md

@@ -75,6 +75,64 @@ $ node --completion-bash > node_bash_completion
 $ source node_bash_completion
 ```
 
+### `--diagnostic-report-directory=directory`
+<!-- YAML
+added: REPLACEME
+-->
+
+Location at which the report will be generated.
+
+### `--diagnostic-report-filename=filename`
+<!-- YAML
+added: REPLACEME
+-->
+
+Name of the file to which the report will be written.
+
+### `--diagnostic-report-on-fatalerror`
+<!-- YAML
+added: REPLACEME
+-->
+
+Enables the report to be triggered on fatal errors (internal errors within
+the Node.js runtime such as out of memory) that lead to termination of the
+application, if `--experimental-report` is enabled. Useful to inspect various
+diagnostic data elements such as heap, stack, event loop state, resource
+consumption etc. to reason about the fatal error.
+
+### `--diagnostic-report-on-signal`
+<!-- YAML
+added: REPLACEME
+-->
+
+Enables report to be generated upon receiving the specified (or predefined)
+signal to the running Node.js process, if `--experimental-report` is enabled.
+The signal to trigger the report is specified through `--diagnostic-report-signal`.
+
+### `--diagnostic-report-signal=signal`
+<!-- YAML
+added: REPLACEME
+-->
+
+Sets or resets the signal for report generation (not supported on Windows).
+Default signal is `SIGUSR2`.
+
+### `--diagnostic-report-uncaught-exception`
+<!-- YAML
+added: REPLACEME
+-->
+
+Enables report to be generated on un-caught exceptions, if
+`--experimental-report` is enabled. Useful when inspecting JavaScript stack in
+conjunction with native stack and other runtime environment data.
+
+### `--diagnostic-report-verbose`
+<!-- YAML
+added: REPLACEME
+-->
+
+Flag that enables additional information to be printed during report generation.
+
 ### `--enable-fips`
 <!-- YAML
 added: v6.0.0
@@ -104,6 +162,13 @@ added: v10.0.0
 
 Enable experimental top-level `await` keyword support in REPL.
 
+### `--experimental-report`
+<!-- YAML
+added: REPLACEME
+-->
+
+Enable experimental diagnostic report feature.
+
 ### `--experimental-vm-modules`
 <!-- YAML
 added: v9.6.0
@@ -600,9 +665,17 @@ if they had been specified on the command line before the actual command line
 that is not allowed in the environment is used, such as `-p` or a script file.
 
 Node.js options that are allowed are:
+- `--diagnostic-report-directory`
+- `--diagnostic-report-filename`
+- `--diagnostic-report-on-fatalerror`
+- `--diagnostic-report-on-signal`
+- `--diagnostic-report-signal`
+- `--diagnostic-report-uncaught-exception`
+- `--diagnostic-report-verbose`
 - `--enable-fips`
 - `--experimental-modules`
 - `--experimental-repl-await`
+- `--experimental-report`
 - `--experimental-vm-modules`
 - `--force-fips`
 - `--icu-data-dir`

doc/api/errors.md

@@ -1689,6 +1689,12 @@ called.
 An attempt has been made to create a string longer than the maximum allowed
 length.
 
+<a id="ERR_SYNTHETIC"></a>
+#### ERR_SYNTHETIC
+
+An artificial error object used to capture call stack when diagnostic report
+is produced.
+
 <a id="ERR_SYSTEM_ERROR"></a>
 ### ERR_SYSTEM_ERROR
 

doc/api/index.md

@@ -45,6 +45,7 @@
 * [Query Strings](querystring.html)
 * [Readline](readline.html)
 * [REPL](repl.html)
+* [Report](report.html)
 * [Stream](stream.html)
 * [String Decoder](string_decoder.html)
 * [Timers](timers.html)

doc/api/process.md

@@ -1658,6 +1658,109 @@ In custom builds from non-release versions of the source tree, only the
 `name` property may be present. The additional properties should not be
 relied upon to exist.
 
+## process.report
+
+### process.report.getReport([err])
+<!-- YAML
+added: REPLACEME
+-->
+
+* `err` {Object}
+* Returns: {Object} Returns the diagnostics report as an `Object`.
+
+Generates a JSON-formatted diagnostic report summary of the running process.
+The report includes JavaScript and native stack traces, heap statistics,
+platform information, resource usage etc.
+
+```js
+const data = process.report.getReport();
+console.log(data);
+```
+
+Additional documentation on diagnostic report is available
+at [report documentation][].
+
+### process.report.setDiagnosticReportOptions([options]);
+<!-- YAML
+added: REPLACEME
+-->
+
+Set the runtime configuration of diagnostic report data capture. Upon invocation
+of this function, the runtime is reconfigured to generate report based on
+the new input.
+
+* `options` {Object}
+  * `events` {string[]}
+    * `signal`: generate a report in response to a signal raised on the process.
+    * `exception`: generate a report on unhandled exceptions.
+    * `fatalerror`: generate a report on internal fault
+      (such as out of memory errors or native assertions).
+  * `signal` {string} sets or resets the signal for report generation
+    (not supported on Windows). **Default:** `'SIGUSR2'`.
+  * `filename` {string} name of the file to which the report will be written.
+  * `path` {string} drectory at which the report will be generated.
+    **Default:** the current working directory of the Node.js process.
+  * `verbose` {boolean} flag that controls additional verbose information on
+    report generation. **Default:** `false`.
+
+```js
+// Trigger a report upon uncaught exceptions or fatal erros.
+process.report.setDiagnosticReportOptions(
+  { events: ['exception', 'fatalerror'] });
+
+// Change the default path and filename of the report.
+process.report.setDiagnosticReportOptions(
+  { filename: 'foo.json', path: '/home' });
+
+// Produce the report onto stdout, when generated. Special meaning is attached
+// to `stdout` and `stderr`. Usage of these will result in report being written
+// to the associated standard streams. URLs are not supported.
+process.report.setDiagnosticReportOptions(
+  { filename: 'stdout' });
+
+// Enable verbose option on report generation.
+process.report.setDiagnosticReportOptions(
+  { verbose: true });
+
+```
+
+Signal based report generation is not supported on Windows.
+
+Additional documentation on diagnostic report is available
+at [report documentation][].
+
+### process.report.triggerReport([filename][, err])
+<!-- YAML
+added: REPLACEME
+-->
+
+* `filename` {string} The file to write into. The `filename` should be
+a relative path, that will be appended to the directory specified by
+`process.report.setDiagnosticReportOptions`, or current working directory
+of the Node.js process, if unspecified.
+* `err`  {Object} A custom object which will be used for reporting
+JavsScript stack.
+
+* Returns: {string} Returns the filename of the generated report.
+
+If both `filename` and `err` object are passed to `triggerReport()` the
+`err` object must be the second parameter.
+
+Triggers and produces the report (a JSON-formatted file with the internal
+state of Node.js runtime) synchronously, and writes into a file.
+
+```js
+process.report.triggerReport();
+```
+
+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 and error
+object can be specified as parameters on the `triggerReport()` call.
+
+Additional documentation on diagnostic report is available
+at [report documentation][].
+
 ## process.send(message[, sendHandle[, options]][, callback])
 <!-- YAML
 added: v0.5.9
@@ -2172,3 +2275,4 @@ cases:
 [note on process I/O]: process.html#process_a_note_on_process_i_o
 [process_emit_warning]: #process_process_emitwarning_warning_type_code_ctor
 [process_warning]: #process_event_warning
+[report documentation]: report.html