Skip to content

Commit

Permalink
lib: replace --diagnostic-report-* with --report-*
Browse files Browse the repository at this point in the history
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: #27312
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
  • Loading branch information
joyeecheung committed Apr 22, 2019
1 parent 19e3e02 commit 94adfe9
Show file tree
Hide file tree
Showing 9 changed files with 154 additions and 124 deletions.
144 changes: 87 additions & 57 deletions doc/api/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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`
Expand Down
26 changes: 13 additions & 13 deletions doc/api/report.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"
],
Expand Down Expand Up @@ -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.
Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand Down
72 changes: 36 additions & 36 deletions doc/node.1
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
.
Expand Down
Loading

0 comments on commit 94adfe9

Please sign in to comment.