Skip to content

doc: document --trace-promises - #65199

Open
tomass22 wants to merge 1 commit into
nodejs:mainfrom
tomass22:doc-trace-promises
Open

doc: document --trace-promises#65199
tomass22 wants to merge 1 commit into
nodejs:mainfrom
tomass22:doc-trace-promises

Conversation

@tomass22

Copy link
Copy Markdown

--trace-promises has been available since v21.5.0 (backported to v20.12.0 in
#50899) but has never been documented.

  • Registered in src/node_options.cc with kAllowedInEnvvar, so it is also
    usable through NODE_OPTIONS
  • Implemented in src/env.cc as Environment::TracePromises, installed as an
    isolate-wide promise hook in src/node.cc
  • Absent from both doc/api/cli.md and doc/node.1

When the flag landed, it was added to the "intentionally undocumented options"
list in test/parallel/test-process-env-allowed-flags-are-documented.js instead
of being documented:

assert(undocumented.delete('--trace-promises'));
assert(undocumented.delete('--no-trace-promises'));

I believe that was an oversight rather than a deliberate decision. The other
entries in that list fall into two groups:

  • legacy no-ops kept for compatibility — --experimental-fetch,
    --experimental-global-webcrypto, --experimental-report,
    --experimental-worker, --napi-modules, --es-module-specifier-resolution
  • internal-only debugging switches — --debug-arraybuffer-allocations,
    --verify-base-objects, --node-snapshot

--trace-promises is neither. It is a user-facing diagnostic flag in the same
family as --trace-env, --trace-uncaught and --trace-warnings, all of which
are documented.

This PR:

  • documents the flag in doc/api/cli.md, both as a ### section and in the
    NODE_OPTIONS allow-list
  • regenerates doc/node.1 with make node.1
  • removes the two exemptions from the test

No new test is needed. Removing the exemptions makes the existing
test-process-env-allowed-flags-are-documented test cover this flag — it fails
without the documentation change.

Refs: #50899

`--trace-promises` has been available since v21.5.0 but was never added
to the CLI documentation. Instead it was added to the list of
intentionally undocumented options in
test/parallel/test-process-env-allowed-flags-are-documented.js.

Unlike the other entries in that list, which are either legacy no-ops or
internal-only debugging switches, `--trace-promises` is a user-facing
diagnostic flag that is allowed in NODE_OPTIONS, and its siblings
`--trace-env`, `--trace-uncaught` and `--trace-warnings` are all
documented.

Document it in doc/api/cli.md, regenerate doc/node.1 accordingly, and
drop the two exemptions from the test.

Assisted-by: Claude Opus 5 (1M context)
Signed-off-by: tomass22 <dominanthat@gmail.com>
@nodejs-github-bot nodejs-github-bot added the needs-ci PRs that need a full CI run. label Aug 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-ci PRs that need a full CI run.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants