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>
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>
Trivikram Kamat