From 4f38106ef56e2c425ea558c69de0ea7997464055 Mon Sep 17 00:00:00 2001 From: Vipin Menon Date: Wed, 5 Sep 2018 19:52:49 +0530 Subject: [PATCH] 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: https://github.com/nodejs/node/pull/22712 Reviewed-By: Anna Henningsen Reviewed-By: James M Snell Reviewed-By: Michael Dawson Reviewed-By: Vse Mozhet Byt --- doc/api/cli.md | 73 +++++++ doc/api/errors.md | 6 + doc/api/index.md | 1 + doc/api/process.md | 104 ++++++++++ doc/api/report.md | 490 +++++++++++++++++++++++++++++++++++++++++++++ doc/node.1 | 46 +++++ 6 files changed, 720 insertions(+) create mode 100644 doc/api/report.md diff --git a/doc/api/cli.md b/doc/api/cli.md index ccc86dedc1cf50..0ee4e94df006a0 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -75,6 +75,64 @@ $ node --completion-bash > node_bash_completion $ source node_bash_completion ``` +### `--diagnostic-report-directory=directory` + + +Location at which the report will be generated. + +### `--diagnostic-report-filename=filename` + + +Name of the file to which the report will be written. + +### `--diagnostic-report-on-fatalerror` + + +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` + + +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` + + +Sets or resets the signal for report generation (not supported on Windows). +Default signal is `SIGUSR2`. + +### `--diagnostic-report-uncaught-exception` + + +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` + + +Flag that enables additional information to be printed during report generation. + ### `--enable-fips` + +Enable experimental diagnostic report feature. + ### `--experimental-vm-modules` + +* `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]); + + +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]) + + +* `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])