Skip to content

Commit

Permalink
doc: update stability of report features
Browse files Browse the repository at this point in the history
This commit updates the stability documentation for the report
feature. All diagnostic report APIs are now listed as stable,
with the exception of report-on-fatalerror, which still has a
few bugs to work out.

PR-URL: nodejs#32242
Fixes: nodejs#26293
Reviewed-By: Richard Lau <[email protected]>
Reviewed-By: David Carlier <[email protected]>
Reviewed-By: Gireesh Punathil <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Matteo Collina <[email protected]>
  • Loading branch information
cjihrig authored and targos committed Apr 25, 2020
1 parent 45c8c2d commit 5587d66
Show file tree
Hide file tree
Showing 3 changed files with 50 additions and 17 deletions.
17 changes: 17 additions & 0 deletions doc/api/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -618,6 +618,9 @@ warning will be written to stderr instead.
<!-- YAML
added: v11.8.0
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/32242
description: This option is no longer considered experimental.
- version: v12.0.0
pr-url: https://github.com/nodejs/node/pull/27312
description: Changed from `--diagnostic-report-directory` to
Expand All @@ -630,6 +633,9 @@ Location at which the report will be generated.
<!-- YAML
added: v11.8.0
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/32242
description: This option is no longer considered experimental.
- version: v12.0.0
pr-url: https://github.com/nodejs/node/pull/27312
description: changed from `--diagnostic-report-filename` to
Expand All @@ -648,6 +654,8 @@ changes:
`--report-on-fatalerror`
-->

> Stability: 1 - Experimental
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. Useful to inspect various diagnostic data elements such as heap,
Expand All @@ -658,6 +666,9 @@ error.
<!-- YAML
added: v11.8.0
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/32242
description: This option is no longer considered experimental.
- version: v12.0.0
pr-url: https://github.com/nodejs/node/pull/27312
description: changed from `--diagnostic-report-on-signal` to
Expand All @@ -672,6 +683,9 @@ specified through `--report-signal`.
<!-- YAML
added: v11.8.0
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/32242
description: This option is no longer considered experimental.
- version: v12.0.0
pr-url: https://github.com/nodejs/node/pull/27312
description: changed from `--diagnostic-report-signal` to
Expand All @@ -685,6 +699,9 @@ Default signal is `SIGUSR2`.
<!-- YAML
added: v11.8.0
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/32242
description: This option is no longer considered experimental.
- version: v12.0.0
pr-url: https://github.com/nodejs/node/pull/27312
description: changed from `--diagnostic-report-uncaught-exception` to
Expand Down
48 changes: 32 additions & 16 deletions doc/api/process.md
Original file line number Diff line number Diff line change
Expand Up @@ -1755,10 +1755,12 @@ relied upon to exist.
## `process.report`
<!-- YAML
added: v11.8.0
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/32242
description: This API is no longer considered experimental.
-->

> Stability: 1 - Experimental
* {Object}

`process.report` is an object whose methods are used to generate diagnostic
Expand All @@ -1768,10 +1770,12 @@ reports for the current process. Additional documentation is available in the
### `process.report.directory`
<!-- YAML
added: v11.12.0
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/32242
description: This API is no longer considered experimental.
-->

> Stability: 1 - Experimental
* {string}

Directory where the report is written. The default value is the empty string,
Expand All @@ -1785,10 +1789,12 @@ console.log(`Report directory is ${process.report.directory}`);
### `process.report.filename`
<!-- YAML
added: v11.12.0
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/32242
description: This API is no longer considered experimental.
-->

> Stability: 1 - Experimental
* {string}

Filename where the report is written. If set to the empty string, the output
Expand All @@ -1802,10 +1808,12 @@ console.log(`Report filename is ${process.report.filename}`);
### `process.report.getReport([err])`
<!-- YAML
added: v11.8.0
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/32242
description: This API is no longer considered experimental.
-->

> Stability: 1 - Experimental
* `err` {Error} A custom error used for reporting the JavaScript stack.
* Returns: {Object}

Expand Down Expand Up @@ -1843,10 +1851,12 @@ console.log(`Report on fatal error: ${process.report.reportOnFatalError}`);
### `process.report.reportOnSignal`
<!-- YAML
added: v11.12.0
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/32242
description: This API is no longer considered experimental.
-->

> Stability: 1 - Experimental
* {boolean}

If `true`, a diagnostic report is generated when the process receives the
Expand All @@ -1859,10 +1869,12 @@ console.log(`Report on signal: ${process.report.reportOnSignal}`);
### `process.report.reportOnUncaughtException`
<!-- YAML
added: v11.12.0
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/32242
description: This API is no longer considered experimental.
-->

> Stability: 1 - Experimental
* {boolean}

If `true`, a diagnostic report is generated on uncaught exception.
Expand All @@ -1874,10 +1886,12 @@ console.log(`Report on exception: ${process.report.reportOnUncaughtException}`);
### `process.report.signal`
<!-- YAML
added: v11.12.0
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/32242
description: This API is no longer considered experimental.
-->

> Stability: 1 - Experimental
* {string}

The signal used to trigger the creation of a diagnostic report. Defaults to
Expand All @@ -1890,10 +1904,12 @@ console.log(`Report signal: ${process.report.signal}`);
### `process.report.writeReport([filename][, err])`
<!-- YAML
added: v11.8.0
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/32242
description: This API is no longer considered experimental.
-->

> Stability: 1 - Experimental
* `filename` {string} Name of the file where the report is written. This
should be a relative path, that will be appended to the directory specified in
`process.report.directory`, or the current working directory of the Node.js
Expand Down
2 changes: 1 addition & 1 deletion doc/api/report.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
<!--introduced_in=v11.8.0-->
<!-- type=misc -->

> Stability: 1 - Experimental
> Stability: 2 - Stable
<!-- name=report -->

Expand Down

0 comments on commit 5587d66

Please sign in to comment.