On a hot path, the probe can record every hit and require
filtering afterwards. This patch adds a per-probe `--cond <expr>`
option that allows limiting the hit to only when the expression
is truthy at the probe location. V8 evaluates it as the breakpoint's
native condition, so the target is not paused when it does not hold,
and a condition that throws is treated as false. Since in CDP,
a location can only carry one breakpoint per URL pattern,
probes sharing a location must share one condition (or none).
Conflicting conditions are rejected.
Example:
```js
// app.js
let total = 0;
for (let i = 0; i < 10; i++) {
total += i; // line 4
}
```
```
$ out/Release/node inspect --probe app.js:4 --expr 'total' \
--cond 'i % 3 === 0' app.js
```
```
Hit 1 at file:///path/to/app.js:3:3
total = 0
Hit 2 at file:///path/to/app.js:3:3
total = 3
Hit 3 at file:///path/to/app.js:3:3
total = 15
Hit 4 at file:///path/to/app.js:3:3
total = 36
Completed
```
Signed-off-by: Joyee Cheung <joyeec9h3@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/64328
Refs: https://github.com/nodejs/node/issues/63646
Reviewed-By: James M Snell <jasnell@gmail.com>
Wait for the initial pause render before completing debugger REPL
startup, but only when the initial pause is actually observed during
startup initialization.
Creating the wait promise before Runtime.runIfWaitingForDebugger() can
hang when the debug target exits or disconnects without producing an
initial pause event. It also assumes the inspector object always has
parsed CLI options, which is not true for tests that use a minimal mock
inspector.
Create the initial-render wait lazily from the Debugger.paused handler
while startup initialization is active. This preserves prompt ordering
for normal initial breaks without blocking startup when no initial pause
render occurs.
Signed-off-by: Kamat, Trivikram <16024985+trivikr@users.noreply.github.com>
Assisted-by: openai:gpt-5.5
PR-URL: https://github.com/nodejs/node/pull/63969
Refs: https://github.com/nodejs/node/actions/runs/27582782593/job/81546582775
Reviewed-By: Filip Skokan <panva.ip@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
This option provides a new way of terminating the probing by
specifying a limit for the per-probe hit evaluation. When any
probe reaches the limit, the session removes the V8 breakpoints
and finishes with a `completed` terminal event rather than waiting
for the target to exit or timeout. This would be useful when we
provide a way to attach to and probe a running process in the future.
Signed-off-by: Joyee Cheung <joyeec9h3@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/63704
Refs: https://github.com/nodejs/node/issues/63646
Reviewed-By: Jan Martin <jan.krems@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
On slow CI, the outer Debugger.resume can be picked up in the
same drain pass as the Debugger.evaluateOnCallFrame, while V8
still considers the context paused. In this case both resume
calls may succeed and the process can continue running from
the setInterval until the timeout. Accept both probe failure
and timeout as valid to accommodate this flakiness.
This patch also adds more debug logs to the probe mode to
show more information in case it flakes again in the CI
Signed-off-by: Joyee Cheung <joyeec9h3@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/63524
Fixes: https://github.com/nodejs/node/issues/63505
Reviewed-By: Gürgün Dayıoğlu <hey@gurgun.day>
Reviewed-By: Chemi Atlow <chemi@atlow.co.il>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
This addresses a few TODOs left from the initial implementation
around the error handling when the inspector session fails
mid-probe - for example because a probe expression terminates
the target, severs the inspector connection, or hangs the
evaluation. Before this patch, these failures would cause the
probe report to silently miss hits or hit the session timeout.
A consumer of these reports could not tell whether the
recorded hits were reliable or a partial trace cut short
by an inspector-side failure.
This patch surfaces those cases as a new `probe_failure` terminal
`error` event on the report, with best-effort attribution to the
implicated probe via `error.probe` and additional context on
`error.details`. Together with `probe_timeout`, it marks the
report as best-effort, and the probing process exits 1 in both
cases. `probe_target_exit` and clean `completed`/`miss` reports
continue to exit 0 because the recorded hits in those cases remain
ground truth, so tooling can use the exit code as a quick
trustworthiness signal. `error.message` now also contains
actionable recovery hints whereever possible.
The per-hit `error` is reshaped to `{ message, details? }`
so that the per-hit and terminal errors share a top-level shape.
Both fields are informative-only, only their top-level type is stable.
Signed-off-by: Joyee Cheung <joyeec9h3@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/63437
Refs: https://github.com/nodejs/node/pull/62713
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Jan Martin <jan.krems@gmail.com>
In probe mode, `--probe utils.js:10` can match multiple scripts
(e.g. `src/utils.js` and `lib/utils.js`) because the matcher uses
a path-separator-anchored URL suffix (similar to how e.g. gdb/lldb
behaves). Previously the report echoed only the user's request in
hit events, so a user seeing two hits at `utils.js:10` could not
tell which script each hit came from. In addition, previously
when the column was omitted we bound to 1 which was technically
different from how CDP binds omitted columns (to the first
executable column on the line).
This patch clarifies the semantics by tracking the scripts via
`Debugger.scriptParsed`, as recommended in the CDP docs, and
reports the actual execution location as `results[i].location`.
The same shape can be reused in the future for source maps or
additional events in attach mode.
This bumps the schema version because `target` is now
`{ suffix, line, column? }` instead of a positional array for
clarity. We picked `suffix` as the field name in case we
introduce other matching modes in the future. `column` is
omitted when the user did not supply one, and the actual
resolved column is reported in the hit event instead.
This patch also adds more tests for column-specific bindings,
multi-location resolution via require(cjs), and late script
binding via dynamic import(cjs) and require(esm).
Signed-off-by: Joyee Cheung <joyeec9h3@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/63286
Reviewed-By: Jan Martin <jan.krems@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
- Add `--help` / `-h` to `node inspect` covering both interactive and
non-interactive probe modes. The help text is printed when
`--help`/`-h` appears before any positional argument to avoid
hijacking `--help` passed to a child script.
- Improve the documentation of probe mode and add examples, explain
same-location probe coalescing, TDZ caveat for let/const bindings,
basename matching and exit code behavior. Also move it to a
section parallel to interactive mode. Remove recommendation of
evaluating structured expressions as that is prone to missing
info in JSON mode.
Drive-by: When probe mode exits due to invalid arguments, exit with
`kInvalidCommandLineArgument` (9) instead of `kGenericUserError` (1).
Signed-off-by: Joyee Cheung <joyeec9h3@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/63201
Reviewed-By: Jan Martin <jan.krems@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Aviv Keller <me@aviv.sh>
Add a non-interactive probe mode to `node inspect` for inspecting
runtime values in a run-to-completion application. This allows
users to perform printf-style debugging without having to modify
the application code and clean up afterwards, it also supports
structured output to be consumed by tools.
Probe mode launches the application, sets one or more source
breakpoints, evaluates one expression at each hit, and prints a
single text or JSON report when execution ends.
Interface:
node inspect [--json] [--preview] [--timeout=<ms>] [--port=<port>]
--probe <file>:<line>[:<col>] --expr <expr> ...
[--] <script> [args...]
Example:
```js
// cli.js
let maxRSS = 0;
for (let i = 0; i < 2; i++) {
const { rss } = process.memoryUsage();
maxRSS = Math.max(maxRSS, rss);
}
```
```
$ node inspect --probe cli.js:5 --expr 'rss' cli.js
Hit 1 at cli.js:5
rss = 54935552
Hit 2 at cli.js:5
rss = 55083008
Completed
```
(Prettified JSON to fit in commit message restrictions).
```js
$ node inspect --json --probe cli.js:5 --expr 'rss' cli.js
{"v":1,"probes":[{"expr":"rss","target":["cli.js",5]}],
"results":[
{"probe":0,"event":"hit","hit":1,
"result":{"type":"number","value":55443456,
"description":"55443456"}},
{"probe":0,"event":"hit","hit":2,
"result":{"type":"number","value":55574528,
"description":"55574528"}},
{"event":"completed"}]}
```
Signed-off-by: Joyee Cheung <joyeec9h3@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/62713
Reviewed-By: Jan Martin <jan.krems@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
It should remove both the error and the ready event listeners
attached when either of them fires, instead of removing only
the one whose corresponding event fires, otherwise the other
event listener will always get leaked.
PR-URL: https://github.com/nodejs/node/pull/60464
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
This patch removes special case in the internal binding loader
for natives, and implements it using the builtins internal
binding. Internally we do not actually need the natives binding,
so implement it as a legacy wrapper instead.
PR-URL: https://github.com/nodejs/node/pull/48186
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
- debugger: add string validation for watch(expr)
- debugger: add help document for watch(index)
- test: add test for watch(index) command
- doc: add information on unwatch(index) option
PR-URL: https://github.com/nodejs/node/pull/46947
Reviewed-By: Kohei Ueno <kohei.ueno119@gmail.com>
Add an ExitCode enum class and use it throughout the code base
instead of hard-coding the exit codes everywhere. At the moment,
the exit codes used in many places do not actually conform to
what the documentation describes. With the new enums (which
are also available to the JS land as constants in an internal
binding) we could migrate to a more consistent usage of the
codes, and eventually expose the constants to the user land
when they are stable enough.
PR-URL: https://github.com/nodejs/node/pull/44746
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Jacob Smith <jacob@frende.me>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Darshan Sen <raisinten@gmail.com>
By default, the debugger would query the specified inspector
sever port to see if it's available before starting the server,
and it would keep retrying until a timeout (previously 9999 ms)
is reached. This timeout seems to be longer than necessary. This
patch decreases the timeout to 3 seconds.
PR-URL: https://github.com/nodejs/node/pull/44359
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
Reviewed-By: Richard Lau <rlau@redhat.com>
The term "native module" dates back to some of the oldest code
in the code base. Within the context of Node.js core it usually
refers to modules that are native to Node.js (e.g. fs, http),
but it can cause confusion for people who don't work on this
part of the code base, as "native module" can also refer to
native addons - which is even the case in some of the API
docs and error messages.
This patch tries to make the usage of these terms more consistent.
Now within the context of Node.js core:
- JavaScript scripts that are built-in to Node.js are now referred
to as "built-in(s)". If they are available as modules,
they can also be referred to as "built-in module(s)".
- Dynamically-linked shared objects that are loaded into
the Node.js processes are referred to as "addons".
We will try to avoid using the term "native modules" because it could
be ambiguous.
Changes in this patch:
File names:
- node_native_module.h -> node_builtins.h,
- node_native_module.cc -> node_builtins.cc
C++ binding names:
- `native_module` -> `builtins`
`node::Environment`:
- `native_modules_without_cache` -> `builtins_without_cache`
- `native_modules_with_cache` -> `builtins_with_cache`
- `native_modules_in_snapshot` -> `builtins_in_cache`
- `native_module_require` -> `builtin_module_require`
`node::EnvSerializeInfo`:
- `native_modules` -> `builtins
`node::native_module::NativeModuleLoader`:
- `native_module` namespace -> `builtins` namespace
- `NativeModuleLoader` -> `BuiltinLoader`
- `NativeModuleRecordMap` -> `BuiltinSourceMap`
- `NativeModuleCacheMap` -> `BuiltinCodeCacheMap`
- `ModuleIds` -> `BuiltinIds`
- `ModuleCategories` -> `BuiltinCategories`
- `LoadBuiltinModuleSource` -> `LoadBuiltinSource`
`loader.js`:
- `NativeModule` -> `BuiltinModule` (the `NativeModule` name used in
`process.moduleLoadList` is kept for compatibility)
And other clarifications in the documentation and comments.
PR-URL: https://github.com/nodejs/node/pull/44135
Fixes: https://github.com/nodejs/node/issues/44036
Reviewed-By: Jacob Smith <jacob@frende.me>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
Reviewed-By: Richard Lau <rlau@redhat.com>
Reviewed-By: Jiawen Geng <technicalcute@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Mohammed Keyvanzadeh <mohammadkeyvanzade94@gmail.com>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Jan Krems <jan.krems@gmail.com>
Marco Ippolito