doc: document --trace-promises

doc/api/cli.md

@@ -3323,6 +3323,19 @@ added:
 Prints a stack trace whenever an environment is exited proactively,
 i.e. invoking `process.exit()`.
 
+### `--trace-promises`
+
+<!-- YAML
+added:
+ - v21.5.0
+ - v20.12.0
+-->
+
+Prints a stack trace to stderr whenever a promise is created or resolved. Each
+promise is given an identifier, and the identifier of the parent promise is
+also printed when the promise is derived from another one. Promise `before` and
+`after` hook events are not traced, to reduce the amount of output.
+
 ### `--trace-require-module=mode`
 
 <!-- YAML
@@ -3982,6 +3995,7 @@ one is included in the list below.
 * `--trace-event-file-pattern`
 * `--trace-events-enabled`
 * `--trace-exit`
+* `--trace-promises`
 * `--trace-require-module`
 * `--trace-sigint`
 * `--trace-sync-io`

doc/node.1

@@ -1608,6 +1608,12 @@ Enables the collection of trace event tracing information.
 Prints a stack trace whenever an environment is exited proactively,
 i.e. invoking \fBprocess.exit()\fR.
 .
+.It Fl -trace-promises
+Prints a stack trace to stderr whenever a promise is created or resolved. Each
+promise is given an identifier, and the identifier of the parent promise is
+also printed when the promise is derived from another one. Promise \fBbefore\fR and
+\fBafter\fR hook events are not traced, to reduce the amount of output.
+.
 .It Fl -trace-require-module Ns = Ns Ar mode
 Prints information about usage of Loading ECMAScript modules using \fBrequire()\fR.
 When \fBmode\fR is \fBall\fR, all usage is printed. When \fBmode\fR is \fBno-node-modules\fR, usage
@@ -2216,6 +2222,8 @@ one is included in the list below.
 .It
 \fB--trace-exit\fR
 .It
+\fB--trace-promises\fR
+.It
 \fB--trace-require-module\fR
 .It
 \fB--trace-sigint\fR

test/parallel/test-process-env-allowed-flags-are-documented.js

@@ -139,8 +139,6 @@ assert(undocumented.delete('--no-node-snapshot'));
 assert(undocumented.delete('--loader'));
 assert(undocumented.delete('--verify-base-objects'));
 assert(undocumented.delete('--no-verify-base-objects'));
-assert(undocumented.delete('--trace-promises'));
-assert(undocumented.delete('--no-trace-promises'));
 
 // Remove negated versions of the flags.
 for (const flag of undocumented) {