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>
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>
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>
Joyee Cheung