lib: replace --diagnostic-report-* with --report-*
In the code base the word `report` is almost only used to refer to the diagnostic report when it's a noun, and it's programmable interface `process.report()` it not prefixed, so `report` should be unambiguous enough to use without `diagnostic`. PR-URL: https://github.com/nodejs/node/pull/27312 Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
This commit is contained in:
Joyee Cheung
parent
19e3e02a2d
commit
94adfe9831
144
doc/api/cli.md
144
doc/api/cli.md
@ -106,57 +106,6 @@ should be written to. When used alone, it implies `--cpu-prof`.
|
||||
$ node --cpu-prof-path /tmp/test.cpuprofile index.js
|
||||
```
|
||||
|
||||
### `--diagnostic-report-directory=directory`
|
||||
<!-- YAML
|
||||
added: v11.8.0
|
||||
-->
|
||||
|
||||
Location at which the report will be generated.
|
||||
|
||||
### `--diagnostic-report-filename=filename`
|
||||
<!-- YAML
|
||||
added: v11.8.0
|
||||
-->
|
||||
|
||||
Name of the file to which the report will be written.
|
||||
|
||||
### `--diagnostic-report-on-fatalerror`
|
||||
<!-- YAML
|
||||
added: v11.8.0
|
||||
-->
|
||||
|
||||
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: v11.8.0
|
||||
-->
|
||||
|
||||
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: v11.8.0
|
||||
-->
|
||||
|
||||
Sets or resets the signal for report generation (not supported on Windows).
|
||||
Default signal is `SIGUSR2`.
|
||||
|
||||
### `--diagnostic-report-uncaught-exception`
|
||||
<!-- YAML
|
||||
added: v11.8.0
|
||||
-->
|
||||
|
||||
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.
|
||||
|
||||
### `--enable-fips`
|
||||
<!-- YAML
|
||||
added: v6.0.0
|
||||
@ -492,6 +441,87 @@ file will be created if it does not exist, and will be appended to if it does.
|
||||
If an error occurs while attempting to write the warning to the file, the
|
||||
warning will be written to stderr instead.
|
||||
|
||||
### `--report-directory=directory`
|
||||
<!-- YAML
|
||||
added: v11.8.0
|
||||
changes:
|
||||
- version: REPLACEME
|
||||
pr-url: https://github.com/nodejs/node/pull/27312
|
||||
description: Changed from `--diagnostic-report-directory` to
|
||||
`--report-directory`
|
||||
-->
|
||||
|
||||
Location at which the report will be generated.
|
||||
|
||||
### `--report-filename=filename`
|
||||
<!-- YAML
|
||||
added: v11.8.0
|
||||
changes:
|
||||
- version: REPLACEME
|
||||
pr-url: https://github.com/nodejs/node/pull/27312
|
||||
description: changed from `--diagnostic-report-filename` to
|
||||
`--report-filename`
|
||||
-->
|
||||
|
||||
Name of the file to which the report will be written.
|
||||
|
||||
### `--report-on-fatalerror`
|
||||
<!-- YAML
|
||||
added: v11.8.0
|
||||
changes:
|
||||
- version: REPLACEME
|
||||
pr-url: https://github.com/nodejs/node/pull/27312
|
||||
description: changed from `--diagnostic-report-on-fatalerror` to
|
||||
`--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.
|
||||
|
||||
### `--report-on-signal`
|
||||
<!-- YAML
|
||||
added: v11.8.0
|
||||
changes:
|
||||
- version: REPLACEME
|
||||
pr-url: https://github.com/nodejs/node/pull/27312
|
||||
description: changed from `--diagnostic-report-on-signal` to
|
||||
`--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 `--report-signal`.
|
||||
|
||||
### `--report-signal=signal`
|
||||
<!-- YAML
|
||||
added: v11.8.0
|
||||
changes:
|
||||
- version: REPLACEME
|
||||
pr-url: https://github.com/nodejs/node/pull/27312
|
||||
description: changed from `--diagnostic-report-signal` to
|
||||
`--report-signal`
|
||||
-->
|
||||
|
||||
Sets or resets the signal for report generation (not supported on Windows).
|
||||
Default signal is `SIGUSR2`.
|
||||
|
||||
### `--report-uncaught-exception`
|
||||
<!-- YAML
|
||||
added: v11.8.0
|
||||
changes:
|
||||
- version: REPLACEME
|
||||
pr-url: https://github.com/nodejs/node/pull/27312
|
||||
description: changed from `--diagnostic-report-uncaught-exception` to
|
||||
`--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.
|
||||
|
||||
### `--throw-deprecation`
|
||||
<!-- YAML
|
||||
added: v0.11.14
|
||||
@ -813,12 +843,12 @@ In case an option value happens to contain a space (for example a path listed in
|
||||
```
|
||||
|
||||
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`
|
||||
- `--report-directory`
|
||||
- `--report-filename`
|
||||
- `--report-on-fatalerror`
|
||||
- `--report-on-signal`
|
||||
- `--report-signal`
|
||||
- `--report-uncaught-exception`
|
||||
- `--enable-fips`
|
||||
- `--experimental-modules`
|
||||
- `--experimental-repl-await`
|
||||
|
||||
@ -32,7 +32,7 @@ is provided below for reference.
|
||||
"commandLine": [
|
||||
"/home/nodeuser/project/node/out/Release/node",
|
||||
"--experimental-report",
|
||||
"--diagnostic-report-uncaught-exception",
|
||||
"--report-uncaught-exception",
|
||||
"/home/nodeuser/project/node/test/report/test-exception.js",
|
||||
"child"
|
||||
],
|
||||
@ -361,19 +361,19 @@ is provided below for reference.
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
node --experimental-report --diagnostic-report-uncaught-exception \
|
||||
--diagnostic-report-on-signal --diagnostic-report-on-fatalerror app.js
|
||||
node --experimental-report --report-uncaught-exception \
|
||||
--report-on-signal --report-on-fatalerror app.js
|
||||
```
|
||||
|
||||
* `--experimental-report` Enables the diagnostic report feature.
|
||||
In the absence of this flag, use of all other related options will result in
|
||||
an error.
|
||||
|
||||
* `--diagnostic-report-uncaught-exception` Enables report to be generated on
|
||||
* `--report-uncaught-exception` Enables report to be generated on
|
||||
un-caught exceptions. Useful when inspecting JavaScript stack in conjunction
|
||||
with native stack and other runtime environment data.
|
||||
|
||||
* `--diagnostic-report-on-signal` Enables report to be generated upon receiving
|
||||
* `--report-on-signal` Enables report to be generated upon receiving
|
||||
the specified (or predefined) signal to the running Node.js process. (See below
|
||||
on how to modify the signal that triggers the report.) Default signal is `SIGUSR2`.
|
||||
Useful when a report needs to be triggered from another program.
|
||||
@ -387,19 +387,19 @@ signal. However, if `SIGUSR2` is already used for other purposes, then this
|
||||
flag helps to change the signal for report generation and preserve the original
|
||||
meaning of `SIGUSR2` for the said purposes.
|
||||
|
||||
* `--diagnostic-report-on-fatalerror` Enables the report to be triggered on
|
||||
* `--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 leads to termination of the application. 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-directory` Location at which the report will be
|
||||
* `--report-directory` Location at which the report will be
|
||||
generated.
|
||||
|
||||
* `--diagnostic-report-filename` Name of the file to which the report will be
|
||||
* `--report-filename` Name of the file to which the report will be
|
||||
written.
|
||||
|
||||
* `--diagnostic-report-signal` Sets or resets the signal for report generation
|
||||
* `--report-signal` Sets or resets the signal for report generation
|
||||
(not supported on Windows). Default signal is `SIGUSR2`.
|
||||
|
||||
A report can also be triggered via an API call from a JavaScript application:
|
||||
@ -534,10 +534,10 @@ Configuration on module initialization is also available via
|
||||
environment variables:
|
||||
|
||||
```bash
|
||||
NODE_OPTIONS="--experimental-report --diagnostic-report-uncaught-exception \
|
||||
--diagnostic-report-on-fatalerror --diagnostic-report-on-signal \
|
||||
--diagnostic-report-signal=SIGUSR2 --diagnostic-report-filename=./report.json \
|
||||
--diagnostic-report-directory=/home/nodeuser"
|
||||
NODE_OPTIONS="--experimental-report --report-uncaught-exception \
|
||||
--report-on-fatalerror --report-on-signal \
|
||||
--report-signal=SIGUSR2 --report-filename=./report.json \
|
||||
--report-directory=/home/nodeuser"
|
||||
```
|
||||
|
||||
Specific API documentation can be found under
|
||||
|
||||
72
doc/node.1
72
doc/node.1
@ -90,42 +90,6 @@ Path the V8 CPU profile generated with
|
||||
will be written to. When used alone, it implies
|
||||
.Fl -cpu-prof
|
||||
.
|
||||
.It Fl -diagnostic-report-directory
|
||||
Location at which the
|
||||
.Sy diagnostic report
|
||||
will be generated.
|
||||
.
|
||||
.It Fl -diagnostic-report-filename
|
||||
Name of the file to which the
|
||||
.Sy diagnostic report
|
||||
will be written.
|
||||
.
|
||||
.It Fl -diagnostic-report-on-fatalerror
|
||||
Enables the
|
||||
.Sy diagnostic report
|
||||
to be triggered on fatal errors (internal errors within the Node.js runtime such as out of memory) that leads to termination of the application, if
|
||||
.Sy --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.
|
||||
.
|
||||
.It Fl -diagnostic-report-on-signal
|
||||
Enables
|
||||
.Sy diagnostic report
|
||||
to be generated upon receiving the specified (or predefined) signal to the running Node.js process, if
|
||||
.Sy --experimental-report
|
||||
is enabled. Default signal is SIGUSR2.
|
||||
.
|
||||
.It Fl -diagnostic-report-signal
|
||||
Sets or resets the signal for
|
||||
.Sy diagnostic report
|
||||
generation (not supported on Windows). Default signal is SIGUSR2.
|
||||
.
|
||||
.It Fl -diagnostic-report-uncaught-exception
|
||||
Enables
|
||||
.Sy diagnostic report
|
||||
to be generated on un-caught exceptions, if
|
||||
.Sy --experimental-report
|
||||
is enabled. Useful when inspecting JavaScript stack in conjunction with native stack and other runtime environment data.
|
||||
.
|
||||
.It Fl -enable-fips
|
||||
Enable FIPS-compliant crypto at startup.
|
||||
Requires Node.js to be built with
|
||||
@ -250,6 +214,42 @@ Write process warnings to the given
|
||||
.Ar file
|
||||
instead of printing to stderr.
|
||||
.
|
||||
.It Fl -report-directory
|
||||
Location at which the
|
||||
.Sy diagnostic report
|
||||
will be generated.
|
||||
.
|
||||
.It Fl -report-filename
|
||||
Name of the file to which the
|
||||
.Sy diagnostic report
|
||||
will be written.
|
||||
.
|
||||
.It Fl -report-on-fatalerror
|
||||
Enables the
|
||||
.Sy diagnostic report
|
||||
to be triggered on fatal errors (internal errors within the Node.js runtime such as out of memory) that leads to termination of the application, if
|
||||
.Sy --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.
|
||||
.
|
||||
.It Fl -report-on-signal
|
||||
Enables
|
||||
.Sy diagnostic report
|
||||
to be generated upon receiving the specified (or predefined) signal to the running Node.js process, if
|
||||
.Sy --experimental-report
|
||||
is enabled. Default signal is SIGUSR2.
|
||||
.
|
||||
.It Fl -report-signal
|
||||
Sets or resets the signal for
|
||||
.Sy diagnostic report
|
||||
generation (not supported on Windows). Default signal is SIGUSR2.
|
||||
.
|
||||
.It Fl -report-uncaught-exception
|
||||
Enables
|
||||
.Sy diagnostic report
|
||||
to be generated on un-caught exceptions, if
|
||||
.Sy --experimental-report
|
||||
is enabled. Useful when inspecting JavaScript stack in conjunction with native stack and other runtime environment data.
|
||||
.
|
||||
.It Fl -throw-deprecation
|
||||
Throw errors for deprecations.
|
||||
.
|
||||
|
||||
@ -69,34 +69,34 @@ void PerIsolateOptions::CheckOptions(std::vector<std::string>* errors) {
|
||||
}
|
||||
|
||||
if (!report_directory.empty()) {
|
||||
errors->push_back("--diagnostic-report-directory option is valid only when "
|
||||
errors->push_back("--report-directory option is valid only when "
|
||||
"--experimental-report is set");
|
||||
}
|
||||
|
||||
if (!report_filename.empty()) {
|
||||
errors->push_back("--diagnostic-report-filename option is valid only when "
|
||||
errors->push_back("--report-filename option is valid only when "
|
||||
"--experimental-report is set");
|
||||
}
|
||||
|
||||
if (!report_signal.empty()) {
|
||||
errors->push_back("--diagnostic-report-signal option is valid only when "
|
||||
errors->push_back("--report-signal option is valid only when "
|
||||
"--experimental-report is set");
|
||||
}
|
||||
|
||||
if (report_on_fatalerror) {
|
||||
errors->push_back(
|
||||
"--diagnostic-report-on-fatalerror option is valid only when "
|
||||
"--report-on-fatalerror option is valid only when "
|
||||
"--experimental-report is set");
|
||||
}
|
||||
|
||||
if (report_on_signal) {
|
||||
errors->push_back("--diagnostic-report-on-signal option is valid only when "
|
||||
errors->push_back("--report-on-signal option is valid only when "
|
||||
"--experimental-report is set");
|
||||
}
|
||||
|
||||
if (report_uncaught_exception) {
|
||||
errors->push_back(
|
||||
"--diagnostic-report-uncaught-exception option is valid only when "
|
||||
"--report-uncaught-exception option is valid only when "
|
||||
"--experimental-report is set");
|
||||
}
|
||||
#endif // NODE_REPORT
|
||||
@ -457,30 +457,30 @@ PerIsolateOptionsParser::PerIsolateOptionsParser(
|
||||
AddOption("--stack-trace-limit", "", V8Option{}, kAllowedInEnvironment);
|
||||
|
||||
#ifdef NODE_REPORT
|
||||
AddOption("--diagnostic-report-uncaught-exception",
|
||||
AddOption("--report-uncaught-exception",
|
||||
"generate diagnostic report on uncaught exceptions",
|
||||
&PerIsolateOptions::report_uncaught_exception,
|
||||
kAllowedInEnvironment);
|
||||
AddOption("--diagnostic-report-on-signal",
|
||||
AddOption("--report-on-signal",
|
||||
"generate diagnostic report upon receiving signals",
|
||||
&PerIsolateOptions::report_on_signal,
|
||||
kAllowedInEnvironment);
|
||||
AddOption("--diagnostic-report-on-fatalerror",
|
||||
AddOption("--report-on-fatalerror",
|
||||
"generate diagnostic report on fatal (internal) errors",
|
||||
&PerIsolateOptions::report_on_fatalerror,
|
||||
kAllowedInEnvironment);
|
||||
AddOption("--diagnostic-report-signal",
|
||||
AddOption("--report-signal",
|
||||
"causes diagnostic report to be produced on provided signal,"
|
||||
" unsupported in Windows. (default: SIGUSR2)",
|
||||
&PerIsolateOptions::report_signal,
|
||||
kAllowedInEnvironment);
|
||||
Implies("--diagnostic-report-signal", "--diagnostic-report-on-signal");
|
||||
AddOption("--diagnostic-report-filename",
|
||||
Implies("--report-signal", "--report-on-signal");
|
||||
AddOption("--report-filename",
|
||||
"define custom report file name."
|
||||
" (default: YYYYMMDD.HHMMSS.PID.SEQUENCE#.txt)",
|
||||
&PerIsolateOptions::report_filename,
|
||||
kAllowedInEnvironment);
|
||||
AddOption("--diagnostic-report-directory",
|
||||
AddOption("--report-directory",
|
||||
"define custom report pathname."
|
||||
" (default: current working directory of Node.js process)",
|
||||
&PerIsolateOptions::report_directory,
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
// Flags: --experimental-report --diagnostic-report-on-fatalerror --diagnostic-report-on-signal --diagnostic-report-uncaught-exception
|
||||
// Flags: --experimental-report --report-on-fatalerror --report-on-signal --report-uncaught-exception
|
||||
'use strict';
|
||||
const common = require('../common');
|
||||
common.skipIfReportDisabled();
|
||||
|
||||
@ -23,7 +23,7 @@ if (process.argv[2] === 'child') {
|
||||
tmpdir.refresh();
|
||||
const spawn = require('child_process').spawn;
|
||||
const args = ['--experimental-report',
|
||||
'--diagnostic-report-on-fatalerror',
|
||||
'--report-on-fatalerror',
|
||||
'--max-old-space-size=20',
|
||||
__filename,
|
||||
'child'];
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
// Flags: --experimental-report --diagnostic-report-on-signal
|
||||
// Flags: --experimental-report --report-on-signal
|
||||
'use strict';
|
||||
// Test producing a report via signal.
|
||||
const common = require('../common');
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
// Flags: --experimental-report --diagnostic-report-uncaught-exception
|
||||
// Flags: --experimental-report --report-uncaught-exception
|
||||
'use strict';
|
||||
// Test producing a report on uncaught exception.
|
||||
const common = require('../common');
|
||||
|
||||
@ -111,7 +111,7 @@ function validate() {
|
||||
// Test the case where the report file cannot be opened.
|
||||
const reportDir = path.join(tmpdir.path, 'does', 'not', 'exist');
|
||||
const args = ['--experimental-report',
|
||||
`--diagnostic-report-directory=${reportDir}`,
|
||||
`--report-directory=${reportDir}`,
|
||||
'-e',
|
||||
'process.report.writeReport()'];
|
||||
const child = spawnSync(process.execPath, args, { cwd: tmpdir.path });
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user