Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

node-report: meld into core #22712

Merged
merged 3 commits into from
Jan 18, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions configure.py
Original file line number Diff line number Diff line change
Expand Up @@ -493,6 +493,11 @@
dest='without_npm',
help='do not install the bundled npm (package manager)')

parser.add_option('--without-report',
action='store_true',
dest='without_report',
help='build without report')

# Dummy option for backwards compatibility
parser.add_option('--with-snapshot',
action='store_true',
Expand Down Expand Up @@ -938,6 +943,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_report)
o['default_configuration'] = 'Debug' if options.debug else 'Release'

host_arch = host_arch_win() if os.name == 'nt' else host_arch_cc()
Expand Down
73 changes: 73 additions & 0 deletions doc/api/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -616,9 +681,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`
Expand Down
12 changes: 12 additions & 0 deletions doc/api/errors.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -2227,6 +2233,12 @@ size.
This `Error` is thrown when a read is attempted on a TTY `WriteStream`,
such as `process.stdout.on('data')`.

<a id="ERR_SYNTHETIC"></a>
vsemozhetbyt marked this conversation as resolved.
Show resolved Hide resolved
#### ERR_SYNTHETIC

An artifical error object used to capture call stack when diagnostic report
vsemozhetbyt marked this conversation as resolved.
Show resolved Hide resolved
is produced.


[`'uncaughtException'`]: process.html#process_event_uncaughtexception
[`--force-fips`]: cli.html#cli_force_fips
Expand Down
1 change: 1 addition & 0 deletions doc/api/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
104 changes: 104 additions & 0 deletions doc/api/process.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
vsemozhetbyt marked this conversation as resolved.
Show resolved Hide resolved
**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
Expand Down Expand Up @@ -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
Loading