Skip to content

doc: --trace-promises is not documented in the CLI reference #2

Description

@tomass22

Affected URL(s)

https://nodejs.org/api/cli.html

Description of the problem

--trace-promises is implemented and shipped, but it is not documented anywhere
in the CLI reference.

  • Registered in src/node_options.cc with kAllowedInEnvvar, so it can also be
    set through NODE_OPTIONS.
  • Implemented in src/env.cc as Environment::TracePromises, installed as an
    isolate-wide promise hook in src/node.cc.
  • Shipped in v21.5.0 and backported to v20.12.0 (src: implement --trace-promises nodejs/node#50899).

It appears in neither doc/api/cli.md nor doc/node.1. When the flag was added,
it was instead placed in the "intentionally undocumented options" list in
test/parallel/test-process-env-allowed-flags-are-documented.js, which is what
keeps that test passing today:

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

Every sibling tracing flag is documented: --trace-env, --trace-uncaught,
--trace-warnings, --trace-exit, --trace-sync-io. The other entries in that
exemption list are either legacy no-ops (--experimental-fetch,
--napi-modules) or internal-only debugging switches
(--verify-base-objects, --debug-arraybuffer-allocations).
--trace-promises is neither, so this looks like an oversight rather than a
deliberate omission.

I would like to send a PR documenting it and removing the exemption.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions