inspector: add --cond to node inspect probe mode

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: #64328
Refs: #63646
Reviewed-By: James M Snell <jasnell@gmail.com>

Author: joyeecheung

doc/api/debugger.md

@@ -236,6 +236,10 @@ debug>
 added:
  - v24.16.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/64328
+ description: Add per-probe `--cond <expr>` option to only record a hit when the
+ condition is truthy at the probe location.
  - version: v24.19.0
  pr-url: https://github.com/nodejs/node/pull/63704
  description: Add per-probe `--max-hit <n>` option to limit evaluated hits and finish
@@ -268,8 +272,8 @@ printf-style debugging without having to modify the application code and
 clean up afterwards. It also supports structured JSON output for tool use.
 
 ```console
-$ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
- [--probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>] ...]
+$ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>]
+ [--probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>] ...]
  [--json] [--preview] [--timeout=<ms>] [--port=<port>]
  [--] [<node-option> ...] <script> [<script-args> ...]
 ```
@@ -282,6 +286,9 @@ $ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
 *`--expr <expr>`: JavaScript expression to evaluate whenever execution reaches
  the location specified by the preceding `--probe`.
  Must immediately follow the `--probe` it belongs to.
+*`--cond <expr>`: An optional condition for the probe location. The probe only
+ records a hit when `<expr>` is truthy at the location. A condition that throws
+ is treated as false.
 *`--max-hit <n>`: An optional per-probe limit on the number of times the probe
  can be hit. When not specified, there's no hit limit. When any probe reaches
  its hit limit, the probing process will detach and report the results. The process
@@ -297,14 +304,17 @@ $ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
  will listen. Defaults to `0`, which requests a random port.
 *`--` is optional unless the child needs its own Node.js flags.
 
-Additional rules about the `--probe` and `--expr` arguments:
+Additional rules about the composition of the options:
 
 *`--probe <file>:<line>[:<col>]` and `--expr <expr>` are strict pairs. Each
 `--probe` must be followed immediately by exactly one `--expr`.
-*`--max-hit <n>` is an optional per-probe option that applies to the most recent
-`--probe`/`--expr` pair. It may not appear before the first `--probe` or
- between a `--probe` and its matching `--expr`, and may be given at most once
- per probe.
+*`--cond <expr>` and `--max-hit <n>` are optional modifiers written _after_ the
+`--probe`/`--expr` pair they apply to, each at most once per pair. They may not
+ appear before the first `--probe` or between a `--probe` and its matching
+`--expr`.
+*`--max-hit` scopes to the `--probe`/`--expr` pair it follows, so pairs
+ sharing a location may set different limits. `--cond` scopes to the whole
+ location, probes sharing a location must share one condition (or none).
 *`--timeout`, `--json`, `--preview`, and `--port` are global probe options
  for the whole probe session. They may appear before or between probe pairs,
  but not between a `--probe` and its matching `--expr`.
@@ -379,6 +389,7 @@ $ node inspect --json --probe cli.js:5 --expr 'rss' cli.js
 "suffix": "cli.js",
 "line": 5
  }
+// `condition` is present only when the probe was given a --cond expression.
 // `maxHit` is present only when the probe was given a --max-hit limit.
  }
  ],
@@ -480,6 +491,10 @@ When multiple `--probe`/`--expr` pairs share the same `--probe`, the
 expressions will be evaluated on the same pause in the order they appear
 on the command line.
 
+For each location, there can only be at most one `--cond` (or none).
+Multiple `--probe`/`--expr` pairs with conflicting conditions
+at the same location will be rejected at launch time.
+
 ```js
 // app.js
 constx= { x:42 }; // line 2
@@ -563,6 +578,37 @@ that only matches the intended file:
 $ node inspect --probe src/utils.js:10 --expr 'x' main.js # matches only src/utils.js
 ```
 
+### Probe examples
+
+#### Probing a variable conditionally
+
+```js
+// app.js
+let total =0;
+for (let i =0; i <10; i++) {
+ total += i; // line 4
+}
+```
+
+```console
+$ out/Release/node inspect --probe app.js:4 --expr 'total' \
+ --cond 'i % 3 === 0' app.js
+```
+
+```text
+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
+```
+
+<!-- TODO(joyeecheung): add more examples for different options -->
+
 ## Advanced usage
 
 ### V8 inspector integration for Node.js

lib/internal/debugger/inspect.js

@@ -268,6 +268,7 @@ function parseInteractiveArgs(args) {
 
 constkInspectArgOptions={
 '__proto__': null,
+'cond': {type: 'string'},
 'expr': {type: 'string'},
 'help': {type: 'boolean',short: 'h'},
 'json': {type: 'boolean'},

lib/internal/debugger/inspect_helpers.js

@@ -69,8 +69,8 @@ function writeInspectUsageAndExit(invokedAs, message, exitCode) {
 }
 out.write(`Usage: ${invokedAs} [--port=<port>] [<node-option> ...]
  [<script> [<script-args>] | <host>:<port> | -p <pid>]
-${invokedAs} --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
- [--probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>] ...]
+${invokedAs} --probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>]
+ [--probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>] ...]
  [--json] [--preview] [--timeout=<ms>] [--port=<port>]
  [--] [<node-option> ...] <script> [<script-args> ...]
 
@@ -109,6 +109,9 @@ Options:
  preceding --probe each time execution reaches it.
  Avoid probing let/const-bound variables at their
  declaration site or a ReferenceError may be thrown.
+ --cond <expr> Optional condition for the probe location. The probe only
+ records a hit when <expr> is truthy at the location. A
+ condition that throws is treated as false.
  --max-hit <n> Per-probe limit on evaluated hits. When not specified,
  there's no hit limit. When any probe reaches its hit LIMIT,
  the probing process will detach and report the results.
@@ -121,6 +124,9 @@ Options:
 Semantics:
 * Multiple --probe/--expr pairs are allowed. Same-location --probes share
  a pause and scope, their --exprs are evaluated in command-line order.
+* --max-hit scopes to one --probe/--expr pair, so same-location pairs may set
+ different limits. --cond scopes to the location, probes sharing a location
+ must all share one condition (or none).
 * --probe utils.js:<line>[:<col>] matches every loaded utils.js. Pass a
  fuller path e.g. src/utils.js to narrow the match.
 * Use -- before any Node.js flags intended for the child process.

lib/internal/debugger/inspect_probe.js

@@ -21,6 +21,7 @@ const {
  StringPrototypeIncludes,
  StringPrototypeSlice,
  StringPrototypeStartsWith,
+ StringPrototypeTrim,
  Symbol,
 }=primordials;
 
@@ -87,6 +88,8 @@ const kInspectPortRegex = /^--inspect-port=(\d+)$/;
  * @typedef {object} Probe
  * @property {string} expr Expression to evaluate on hit.
  * @property {ProbeTarget} target User's original --probe request shape.
+ * @property {string} [condition] Condition from --cond. V8 only breaks when it is truthy.
+ * Scoped to the location, so probes sharing a location all carry the same value.
  * @property {number} maxHit Per-probe hit limit from --max-hit. Infinity when unlimited.
  * @property {number} hits Count of hits observed.
  */
@@ -130,6 +133,12 @@ function formatTargetText(target) {
 returncolumn===undefined ? `${suffix}:${line}` : `${suffix}:${line}:${column}`;
 }
 
+// Identity of a probe location. Probes sharing a key share one V8 breakpoint,
+// so this must stay in sync between condition validation and breakpoint setup.
+functionlocationKey(target){
+return`${target.suffix}\n${target.line}\n${target.column??''}`;
+}
+
 functionformatPendingProbeLocations(probes,pending){
 constseen=newSafeSet();
 for(constprobeIndexofpending){
@@ -391,6 +400,22 @@ function parseProbeTokens(tokens, args) {
 probe.maxHit=parseUnsignedInteger(token.value,'max-hit');
 break;
 }
+case'cond': {
+if(probes.length===0){
+thrownewERR_DEBUGGER_STARTUP_ERROR('Unexpected --cond before --probe');
+}
+// A blank condition does not act as a real predicate in V8 (an empty
+// string always breaks), so reject it rather than silently mislead.
+if(token.value===undefined||StringPrototypeTrim(token.value)===''){
+thrownewERR_DEBUGGER_STARTUP_ERROR(`Missing value for ${token.rawName}`);
+}
+constprobe=probes[probes.length-1];
+if(probe.condition!==undefined){
+thrownewERR_DEBUGGER_STARTUP_ERROR('A --probe can have at most one --cond');
+}
+probe.condition=token.value;
+break;
+}
 default:
 if(probes.length>0){
 thrownewERR_DEBUGGER_STARTUP_ERROR(
@@ -410,6 +435,24 @@ function parseProbeTokens(tokens, args) {
 'Probe mode requires at least one --probe <loc> --expr <expr> group');
 }
 
+// V8 allows only one breakpoint per location, so probes sharing a location
+// cannot carry different conditions.
+constconditionByLocation=newSafeMap();
+for(const{ target, condition }ofprobes){
+constkey=locationKey(target);
+// All probes at the same location must share one condition. We split the
+// existence check since if one probe does not have a condition (= undefined),
+// then all probes at the location must also omit it.
+if(conditionByLocation.has(key)){
+if(conditionByLocation.get(key)!==condition){
+thrownewERR_DEBUGGER_STARTUP_ERROR(
+`Probes at ${formatTargetText(target)} must use the same --cond (or none)`);
+}
+}else{
+conditionByLocation.set(key,condition);
+}
+}
+
 constchildArgv=ArrayPrototypeSlice(args,childStartIndex);
 if(childArgv.length===0){
 thrownewERR_DEBUGGER_STARTUP_ERROR('Probe mode requires a child script');
@@ -479,8 +522,8 @@ class ProbeInspectorSession {
 this.resolveCompletion=resolve;
 /** @type {Probe[]} */
 this.probes=ArrayPrototypeMap(options.probes,
-({ expr, target, maxHit })=>
-({ expr, target,maxHit: maxHit??Infinity,hits: 0}));
+({ expr, target, maxHit, condition})=>
+({ expr, target,condition,maxHit: maxHit??Infinity,hits: 0}));
 this.onChildOutput=FunctionPrototypeBind(this.onChildOutput,this);
 this.onChildExit=FunctionPrototypeBind(this.onChildExit,this);
 this.onClientClose=FunctionPrototypeBind(this.onClientClose,this);
@@ -887,17 +930,19 @@ class ProbeInspectorSession {
 constuniqueTargets=newSafeMap();
 
 for(letprobeIndex=0;probeIndex<this.probes.length;probeIndex++){
-const{ target }=this.probes[probeIndex];
-constkey=`${target.suffix}\n${target.line}\n${target.column??''}`;
+const{ target, condition }=this.probes[probeIndex];
+// Probes at the same location share one V8 breakpoint. parseProbeTokens has
+// already ensured they carry the same condition.
+constkey=locationKey(target);
 letentry=uniqueTargets.get(key);
 if(entry===undefined){
-entry={ target,probeIndices: []};
+entry={ target,condition,probeIndices: []};
 uniqueTargets.set(key,entry);
 }
 ArrayPrototypePush(entry.probeIndices,probeIndex);
 }
 
-for(const{ target, probeIndices }ofuniqueTargets.values()){
+for(const{ target,condition,probeIndices }ofuniqueTargets.values()){
 // On Windows, normalize backslashes to forward slashes so the regex matches
 // V8 script URLs which always use forward slashes.
 constnormalizedFile=process.platform==='win32' ?
@@ -918,6 +963,9 @@ class ProbeInspectorSession {
 // the inspector bind to the first executable column.
 params.columnNumber=target.column-1;
 }
+if(condition!==undefined){
+params.condition=condition;
+}
 
 constresult=awaitthis.callCdp('Debugger.setBreakpointByUrl',params);
 debug('breakpoint set: id=%s urlRegex=%s locations=%j',
@@ -943,9 +991,10 @@ class ProbeInspectorSession {
 code: exitCode,
 report: {
 v: kProbeVersion,
-probes: ArrayPrototypeMap(this.probes,({ expr, target, maxHit })=>{
-// Omit an unlimited maxHit, as Infinity would serialize to null in JSON.
+probes: ArrayPrototypeMap(this.probes,({ expr, target, maxHit, condition })=>{
 constprobe={ expr, target };
+if(condition!==undefined){probe.condition=condition;}
+// Omit an unlimited maxHit, as Infinity would serialize to null in JSON.
 if(maxHit!==Infinity){probe.maxHit=maxHit;}
 returnprobe;
 }),

test/parallel/test-debugger-probe-cond-invalid.js

@@ -0,0 +1,40 @@
+// This tests that probe mode rejects malformed --cond usage.
+'use strict';
+
+constcommon=require('../common');
+common.skipIfInspectorDisabled();
+
+constfixtures=require('../common/fixtures');
+const{ assertProbeCliError }=require('../common/debugger-probe');
+
+constcwd=fixtures.path('debugger');
+
+assertProbeCliError(
+['--cond','x','--probe','probe.js:12','--expr','finalValue','probe.js'],
+/Unexpected--condbefore--probe/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--cond','x','--expr','finalValue','probe.js'],
+/Each--probemustbefollowedimmediatelyby--expr/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond','x','--cond','y','probe.js'],
+/A--probecanhaveatmostone--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond',' ','probe.js'],
+/Missingvaluefor--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond'],
+/Missingvaluefor--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','a','--cond','x',
+'--probe','probe.js:12','--expr','b','--cond','y','probe.js'],
+/Probesatprobe\.js:12mustusethesame--cond\(ornone\)/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','a','--cond','x',
+'--probe','probe.js:12','--expr','b','probe.js'],
+/Probesatprobe\.js:12mustusethesame--cond\(ornone\)/,{ cwd });

test/parallel/test-debugger-probe-cond-max-hit.js

@@ -0,0 +1,47 @@
+// This tests that --cond and --max-hit work together.
+'use strict';
+
+constcommon=require('../common');
+common.skipIfInspectorDisabled();
+
+constfixtures=require('../common/fixtures');
+const{ spawnSyncAndAssert }=require('../common/child_process');
+const{ assertProbeJson }=require('../common/debugger-probe');
+
+constcwd=fixtures.path('debugger');
+constprobeUrl=fixtures.fileURL('debugger','probe-max-hit.js').href;
+
+// --max-hit written before --cond. The condition still filters index !== 1, so
+// the only recorded hit carries value 1 rather than the loop's first iteration.
+spawnSyncAndAssert(process.execPath,[
+'inspect',
+'--json',
+'--probe','probe-max-hit.js:5',
+'--expr','index',
+'--max-hit','5',
+'--cond','index === 1',
+'probe-max-hit.js',
+],{ cwd },{
+stdout(output){
+assertProbeJson(output,{
+v: 2,
+probes: [{
+expr: 'index',
+condition: 'index === 1',
+maxHit: 5,
+target: {suffix: 'probe-max-hit.js',line: 5},
+}],
+results: [
+{
+probe: 0,
+event: 'hit',
+hit: 1,
+location: {url: probeUrl,line: 5,column: 3},
+result: {type: 'number',value: 1,description: '1'},
+},
+{event: 'completed'},
+],
+});
+},
+trim: true,
+});

doc/api/debugger.md

@@ -236,6 +236,10 @@ debug>
 added:
  - v24.16.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/64328
+ description: Add per-probe `--cond <expr>` option to only record a hit when the
+ condition is truthy at the probe location.
  - version: v24.19.0
  pr-url: https://github.com/nodejs/node/pull/63704
  description: Add per-probe `--max-hit <n>` option to limit evaluated hits and finish
@@ -268,8 +272,8 @@ printf-style debugging without having to modify the application code and
 clean up afterwards. It also supports structured JSON output for tool use.
 
 ```console
-$ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
- [--probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>] ...]
+$ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>]
+ [--probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>] ...]
  [--json] [--preview] [--timeout=<ms>] [--port=<port>]
  [--] [<node-option> ...] <script> [<script-args> ...]
 ```
@@ -282,6 +286,9 @@ $ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
 *`--expr <expr>`: JavaScript expression to evaluate whenever execution reaches
  the location specified by the preceding `--probe`.
  Must immediately follow the `--probe` it belongs to.
+*`--cond <expr>`: An optional condition for the probe location. The probe only
+ records a hit when `<expr>` is truthy at the location. A condition that throws
+ is treated as false.
 *`--max-hit <n>`: An optional per-probe limit on the number of times the probe
  can be hit. When not specified, there's no hit limit. When any probe reaches
  its hit limit, the probing process will detach and report the results. The process
@@ -297,14 +304,17 @@ $ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
  will listen. Defaults to `0`, which requests a random port.
 *`--` is optional unless the child needs its own Node.js flags.
 
-Additional rules about the `--probe` and `--expr` arguments:
+Additional rules about the composition of the options:
 
 *`--probe <file>:<line>[:<col>]` and `--expr <expr>` are strict pairs. Each
 `--probe` must be followed immediately by exactly one `--expr`.
-*`--max-hit <n>` is an optional per-probe option that applies to the most recent
-`--probe`/`--expr` pair. It may not appear before the first `--probe` or
- between a `--probe` and its matching `--expr`, and may be given at most once
- per probe.
+*`--cond <expr>` and `--max-hit <n>` are optional modifiers written _after_ the
+`--probe`/`--expr` pair they apply to, each at most once per pair. They may not
+ appear before the first `--probe` or between a `--probe` and its matching
+`--expr`.
+*`--max-hit` scopes to the `--probe`/`--expr` pair it follows, so pairs
+ sharing a location may set different limits. `--cond` scopes to the whole
+ location, probes sharing a location must share one condition (or none).
 *`--timeout`, `--json`, `--preview`, and `--port` are global probe options
  for the whole probe session. They may appear before or between probe pairs,
  but not between a `--probe` and its matching `--expr`.
@@ -379,6 +389,7 @@ $ node inspect --json --probe cli.js:5 --expr 'rss' cli.js
 "suffix": "cli.js",
 "line": 5
  }
+// `condition` is present only when the probe was given a --cond expression.
 // `maxHit` is present only when the probe was given a --max-hit limit.
  }
  ],
@@ -480,6 +491,10 @@ When multiple `--probe`/`--expr` pairs share the same `--probe`, the
 expressions will be evaluated on the same pause in the order they appear
 on the command line.
 
+For each location, there can only be at most one `--cond` (or none).
+Multiple `--probe`/`--expr` pairs with conflicting conditions
+at the same location will be rejected at launch time.
+
 ```js
 // app.js
 constx= { x:42 }; // line 2
@@ -563,6 +578,37 @@ that only matches the intended file:
 $ node inspect --probe src/utils.js:10 --expr 'x' main.js # matches only src/utils.js
 ```
 
+### Probe examples
+
+#### Probing a variable conditionally
+
+```js
+// app.js
+let total =0;
+for (let i =0; i <10; i++) {
+ total += i; // line 4
+}
+```
+
+```console
+$ out/Release/node inspect --probe app.js:4 --expr 'total' \
+ --cond 'i % 3 === 0' app.js
+```
+
+```text
+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
+```
+
+<!-- TODO(joyeecheung): add more examples for different options -->
+
 ## Advanced usage
 
 ### V8 inspector integration for Node.js

lib/internal/debugger/inspect.js

@@ -268,6 +268,7 @@ function parseInteractiveArgs(args) {
 
 constkInspectArgOptions={
 '__proto__': null,
+'cond': {type: 'string'},
 'expr': {type: 'string'},
 'help': {type: 'boolean',short: 'h'},
 'json': {type: 'boolean'},

lib/internal/debugger/inspect_helpers.js

@@ -69,8 +69,8 @@ function writeInspectUsageAndExit(invokedAs, message, exitCode) {
 }
 out.write(`Usage: ${invokedAs} [--port=<port>] [<node-option> ...]
  [<script> [<script-args>] | <host>:<port> | -p <pid>]
-${invokedAs} --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
- [--probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>] ...]
+${invokedAs} --probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>]
+ [--probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>] ...]
  [--json] [--preview] [--timeout=<ms>] [--port=<port>]
  [--] [<node-option> ...] <script> [<script-args> ...]
 
@@ -109,6 +109,9 @@ Options:
  preceding --probe each time execution reaches it.
  Avoid probing let/const-bound variables at their
  declaration site or a ReferenceError may be thrown.
+ --cond <expr> Optional condition for the probe location. The probe only
+ records a hit when <expr> is truthy at the location. A
+ condition that throws is treated as false.
  --max-hit <n> Per-probe limit on evaluated hits. When not specified,
  there's no hit limit. When any probe reaches its hit LIMIT,
  the probing process will detach and report the results.
@@ -121,6 +124,9 @@ Options:
 Semantics:
 * Multiple --probe/--expr pairs are allowed. Same-location --probes share
  a pause and scope, their --exprs are evaluated in command-line order.
+* --max-hit scopes to one --probe/--expr pair, so same-location pairs may set
+ different limits. --cond scopes to the location, probes sharing a location
+ must all share one condition (or none).
 * --probe utils.js:<line>[:<col>] matches every loaded utils.js. Pass a
  fuller path e.g. src/utils.js to narrow the match.
 * Use -- before any Node.js flags intended for the child process.

lib/internal/debugger/inspect_probe.js

@@ -21,6 +21,7 @@ const {
  StringPrototypeIncludes,
  StringPrototypeSlice,
  StringPrototypeStartsWith,
+ StringPrototypeTrim,
  Symbol,
 }=primordials;
 
@@ -87,6 +88,8 @@ const kInspectPortRegex = /^--inspect-port=(\d+)$/;
  * @typedef {object} Probe
  * @property {string} expr Expression to evaluate on hit.
  * @property {ProbeTarget} target User's original --probe request shape.
+ * @property {string} [condition] Condition from --cond. V8 only breaks when it is truthy.
+ * Scoped to the location, so probes sharing a location all carry the same value.
  * @property {number} maxHit Per-probe hit limit from --max-hit. Infinity when unlimited.
  * @property {number} hits Count of hits observed.
  */
@@ -130,6 +133,12 @@ function formatTargetText(target) {
 returncolumn===undefined ? `${suffix}:${line}` : `${suffix}:${line}:${column}`;
 }
 
+// Identity of a probe location. Probes sharing a key share one V8 breakpoint,
+// so this must stay in sync between condition validation and breakpoint setup.
+functionlocationKey(target){
+return`${target.suffix}\n${target.line}\n${target.column??''}`;
+}
+
 functionformatPendingProbeLocations(probes,pending){
 constseen=newSafeSet();
 for(constprobeIndexofpending){
@@ -391,6 +400,22 @@ function parseProbeTokens(tokens, args) {
 probe.maxHit=parseUnsignedInteger(token.value,'max-hit');
 break;
 }
+case'cond': {
+if(probes.length===0){
+thrownewERR_DEBUGGER_STARTUP_ERROR('Unexpected --cond before --probe');
+}
+// A blank condition does not act as a real predicate in V8 (an empty
+// string always breaks), so reject it rather than silently mislead.
+if(token.value===undefined||StringPrototypeTrim(token.value)===''){
+thrownewERR_DEBUGGER_STARTUP_ERROR(`Missing value for ${token.rawName}`);
+}
+constprobe=probes[probes.length-1];
+if(probe.condition!==undefined){
+thrownewERR_DEBUGGER_STARTUP_ERROR('A --probe can have at most one --cond');
+}
+probe.condition=token.value;
+break;
+}
 default:
 if(probes.length>0){
 thrownewERR_DEBUGGER_STARTUP_ERROR(
@@ -410,6 +435,24 @@ function parseProbeTokens(tokens, args) {
 'Probe mode requires at least one --probe <loc> --expr <expr> group');
 }
 
+// V8 allows only one breakpoint per location, so probes sharing a location
+// cannot carry different conditions.
+constconditionByLocation=newSafeMap();
+for(const{ target, condition }ofprobes){
+constkey=locationKey(target);
+// All probes at the same location must share one condition. We split the
+// existence check since if one probe does not have a condition (= undefined),
+// then all probes at the location must also omit it.
+if(conditionByLocation.has(key)){
+if(conditionByLocation.get(key)!==condition){
+thrownewERR_DEBUGGER_STARTUP_ERROR(
+`Probes at ${formatTargetText(target)} must use the same --cond (or none)`);
+}
+}else{
+conditionByLocation.set(key,condition);
+}
+}
+
 constchildArgv=ArrayPrototypeSlice(args,childStartIndex);
 if(childArgv.length===0){
 thrownewERR_DEBUGGER_STARTUP_ERROR('Probe mode requires a child script');
@@ -479,8 +522,8 @@ class ProbeInspectorSession {
 this.resolveCompletion=resolve;
 /** @type {Probe[]} */
 this.probes=ArrayPrototypeMap(options.probes,
-({ expr, target, maxHit })=>
-({ expr, target,maxHit: maxHit??Infinity,hits: 0}));
+({ expr, target, maxHit, condition})=>
+({ expr, target,condition,maxHit: maxHit??Infinity,hits: 0}));
 this.onChildOutput=FunctionPrototypeBind(this.onChildOutput,this);
 this.onChildExit=FunctionPrototypeBind(this.onChildExit,this);
 this.onClientClose=FunctionPrototypeBind(this.onClientClose,this);
@@ -887,17 +930,19 @@ class ProbeInspectorSession {
 constuniqueTargets=newSafeMap();
 
 for(letprobeIndex=0;probeIndex<this.probes.length;probeIndex++){
-const{ target }=this.probes[probeIndex];
-constkey=`${target.suffix}\n${target.line}\n${target.column??''}`;
+const{ target, condition }=this.probes[probeIndex];
+// Probes at the same location share one V8 breakpoint. parseProbeTokens has
+// already ensured they carry the same condition.
+constkey=locationKey(target);
 letentry=uniqueTargets.get(key);
 if(entry===undefined){
-entry={ target,probeIndices: []};
+entry={ target,condition,probeIndices: []};
 uniqueTargets.set(key,entry);
 }
 ArrayPrototypePush(entry.probeIndices,probeIndex);
 }
 
-for(const{ target, probeIndices }ofuniqueTargets.values()){
+for(const{ target,condition,probeIndices }ofuniqueTargets.values()){
 // On Windows, normalize backslashes to forward slashes so the regex matches
 // V8 script URLs which always use forward slashes.
 constnormalizedFile=process.platform==='win32' ?
@@ -918,6 +963,9 @@ class ProbeInspectorSession {
 // the inspector bind to the first executable column.
 params.columnNumber=target.column-1;
 }
+if(condition!==undefined){
+params.condition=condition;
+}
 
 constresult=awaitthis.callCdp('Debugger.setBreakpointByUrl',params);
 debug('breakpoint set: id=%s urlRegex=%s locations=%j',
@@ -943,9 +991,10 @@ class ProbeInspectorSession {
 code: exitCode,
 report: {
 v: kProbeVersion,
-probes: ArrayPrototypeMap(this.probes,({ expr, target, maxHit })=>{
-// Omit an unlimited maxHit, as Infinity would serialize to null in JSON.
+probes: ArrayPrototypeMap(this.probes,({ expr, target, maxHit, condition })=>{
 constprobe={ expr, target };
+if(condition!==undefined){probe.condition=condition;}
+// Omit an unlimited maxHit, as Infinity would serialize to null in JSON.
 if(maxHit!==Infinity){probe.maxHit=maxHit;}
 returnprobe;
 }),

test/parallel/test-debugger-probe-cond-invalid.js

@@ -0,0 +1,40 @@
+// This tests that probe mode rejects malformed --cond usage.
+'use strict';
+
+constcommon=require('../common');
+common.skipIfInspectorDisabled();
+
+constfixtures=require('../common/fixtures');
+const{ assertProbeCliError }=require('../common/debugger-probe');
+
+constcwd=fixtures.path('debugger');
+
+assertProbeCliError(
+['--cond','x','--probe','probe.js:12','--expr','finalValue','probe.js'],
+/Unexpected--condbefore--probe/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--cond','x','--expr','finalValue','probe.js'],
+/Each--probemustbefollowedimmediatelyby--expr/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond','x','--cond','y','probe.js'],
+/A--probecanhaveatmostone--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond',' ','probe.js'],
+/Missingvaluefor--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond'],
+/Missingvaluefor--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','a','--cond','x',
+'--probe','probe.js:12','--expr','b','--cond','y','probe.js'],
+/Probesatprobe\.js:12mustusethesame--cond\(ornone\)/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','a','--cond','x',
+'--probe','probe.js:12','--expr','b','probe.js'],
+/Probesatprobe\.js:12mustusethesame--cond\(ornone\)/,{ cwd });

test/parallel/test-debugger-probe-cond-max-hit.js

@@ -0,0 +1,47 @@
+// This tests that --cond and --max-hit work together.
+'use strict';
+
+constcommon=require('../common');
+common.skipIfInspectorDisabled();
+
+constfixtures=require('../common/fixtures');
+const{ spawnSyncAndAssert }=require('../common/child_process');
+const{ assertProbeJson }=require('../common/debugger-probe');
+
+constcwd=fixtures.path('debugger');
+constprobeUrl=fixtures.fileURL('debugger','probe-max-hit.js').href;
+
+// --max-hit written before --cond. The condition still filters index !== 1, so
+// the only recorded hit carries value 1 rather than the loop's first iteration.
+spawnSyncAndAssert(process.execPath,[
+'inspect',
+'--json',
+'--probe','probe-max-hit.js:5',
+'--expr','index',
+'--max-hit','5',
+'--cond','index === 1',
+'probe-max-hit.js',
+],{ cwd },{
+stdout(output){
+assertProbeJson(output,{
+v: 2,
+probes: [{
+expr: 'index',
+condition: 'index === 1',
+maxHit: 5,
+target: {suffix: 'probe-max-hit.js',line: 5},
+}],
+results: [
+{
+probe: 0,
+event: 'hit',
+hit: 1,
+location: {url: probeUrl,line: 5,column: 3},
+result: {type: 'number',value: 1,description: '1'},
+},
+{event: 'completed'},
+],
+});
+},
+trim: true,
+});

doc/api/debugger.md

@@ -236,6 +236,10 @@ debug>
 added:
  - v24.16.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/64328
+ description: Add per-probe `--cond <expr>` option to only record a hit when the
+ condition is truthy at the probe location.
  - version: v24.19.0
  pr-url: https://github.com/nodejs/node/pull/63704
  description: Add per-probe `--max-hit <n>` option to limit evaluated hits and finish
@@ -268,8 +272,8 @@ printf-style debugging without having to modify the application code and
 clean up afterwards. It also supports structured JSON output for tool use.
 
 ```console
-$ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
- [--probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>] ...]
+$ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>]
+ [--probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>] ...]
  [--json] [--preview] [--timeout=<ms>] [--port=<port>]
  [--] [<node-option> ...] <script> [<script-args> ...]
 ```
@@ -282,6 +286,9 @@ $ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
 *`--expr <expr>`: JavaScript expression to evaluate whenever execution reaches
  the location specified by the preceding `--probe`.
  Must immediately follow the `--probe` it belongs to.
+*`--cond <expr>`: An optional condition for the probe location. The probe only
+ records a hit when `<expr>` is truthy at the location. A condition that throws
+ is treated as false.
 *`--max-hit <n>`: An optional per-probe limit on the number of times the probe
  can be hit. When not specified, there's no hit limit. When any probe reaches
  its hit limit, the probing process will detach and report the results. The process
@@ -297,14 +304,17 @@ $ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
  will listen. Defaults to `0`, which requests a random port.
 *`--` is optional unless the child needs its own Node.js flags.
 
-Additional rules about the `--probe` and `--expr` arguments:
+Additional rules about the composition of the options:
 
 *`--probe <file>:<line>[:<col>]` and `--expr <expr>` are strict pairs. Each
 `--probe` must be followed immediately by exactly one `--expr`.
-*`--max-hit <n>` is an optional per-probe option that applies to the most recent
-`--probe`/`--expr` pair. It may not appear before the first `--probe` or
- between a `--probe` and its matching `--expr`, and may be given at most once
- per probe.
+*`--cond <expr>` and `--max-hit <n>` are optional modifiers written _after_ the
+`--probe`/`--expr` pair they apply to, each at most once per pair. They may not
+ appear before the first `--probe` or between a `--probe` and its matching
+`--expr`.
+*`--max-hit` scopes to the `--probe`/`--expr` pair it follows, so pairs
+ sharing a location may set different limits. `--cond` scopes to the whole
+ location, probes sharing a location must share one condition (or none).
 *`--timeout`, `--json`, `--preview`, and `--port` are global probe options
  for the whole probe session. They may appear before or between probe pairs,
  but not between a `--probe` and its matching `--expr`.
@@ -379,6 +389,7 @@ $ node inspect --json --probe cli.js:5 --expr 'rss' cli.js
 "suffix": "cli.js",
 "line": 5
  }
+// `condition` is present only when the probe was given a --cond expression.
 // `maxHit` is present only when the probe was given a --max-hit limit.
  }
  ],
@@ -480,6 +491,10 @@ When multiple `--probe`/`--expr` pairs share the same `--probe`, the
 expressions will be evaluated on the same pause in the order they appear
 on the command line.
 
+For each location, there can only be at most one `--cond` (or none).
+Multiple `--probe`/`--expr` pairs with conflicting conditions
+at the same location will be rejected at launch time.
+
 ```js
 // app.js
 constx= { x:42 }; // line 2
@@ -563,6 +578,37 @@ that only matches the intended file:
 $ node inspect --probe src/utils.js:10 --expr 'x' main.js # matches only src/utils.js
 ```
 
+### Probe examples
+
+#### Probing a variable conditionally
+
+```js
+// app.js
+let total =0;
+for (let i =0; i <10; i++) {
+ total += i; // line 4
+}
+```
+
+```console
+$ out/Release/node inspect --probe app.js:4 --expr 'total' \
+ --cond 'i % 3 === 0' app.js
+```
+
+```text
+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
+```
+
+<!-- TODO(joyeecheung): add more examples for different options -->
+
 ## Advanced usage
 
 ### V8 inspector integration for Node.js

lib/internal/debugger/inspect.js

@@ -268,6 +268,7 @@ function parseInteractiveArgs(args) {
 
 constkInspectArgOptions={
 '__proto__': null,
+'cond': {type: 'string'},
 'expr': {type: 'string'},
 'help': {type: 'boolean',short: 'h'},
 'json': {type: 'boolean'},

lib/internal/debugger/inspect_helpers.js

@@ -69,8 +69,8 @@ function writeInspectUsageAndExit(invokedAs, message, exitCode) {
 }
 out.write(`Usage: ${invokedAs} [--port=<port>] [<node-option> ...]
  [<script> [<script-args>] | <host>:<port> | -p <pid>]
-${invokedAs} --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
- [--probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>] ...]
+${invokedAs} --probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>]
+ [--probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>] ...]
  [--json] [--preview] [--timeout=<ms>] [--port=<port>]
  [--] [<node-option> ...] <script> [<script-args> ...]
 
@@ -109,6 +109,9 @@ Options:
  preceding --probe each time execution reaches it.
  Avoid probing let/const-bound variables at their
  declaration site or a ReferenceError may be thrown.
+ --cond <expr> Optional condition for the probe location. The probe only
+ records a hit when <expr> is truthy at the location. A
+ condition that throws is treated as false.
  --max-hit <n> Per-probe limit on evaluated hits. When not specified,
  there's no hit limit. When any probe reaches its hit LIMIT,
  the probing process will detach and report the results.
@@ -121,6 +124,9 @@ Options:
 Semantics:
 * Multiple --probe/--expr pairs are allowed. Same-location --probes share
  a pause and scope, their --exprs are evaluated in command-line order.
+* --max-hit scopes to one --probe/--expr pair, so same-location pairs may set
+ different limits. --cond scopes to the location, probes sharing a location
+ must all share one condition (or none).
 * --probe utils.js:<line>[:<col>] matches every loaded utils.js. Pass a
  fuller path e.g. src/utils.js to narrow the match.
 * Use -- before any Node.js flags intended for the child process.

lib/internal/debugger/inspect_probe.js

@@ -21,6 +21,7 @@ const {
  StringPrototypeIncludes,
  StringPrototypeSlice,
  StringPrototypeStartsWith,
+ StringPrototypeTrim,
  Symbol,
 }=primordials;
 
@@ -87,6 +88,8 @@ const kInspectPortRegex = /^--inspect-port=(\d+)$/;
  * @typedef {object} Probe
  * @property {string} expr Expression to evaluate on hit.
  * @property {ProbeTarget} target User's original --probe request shape.
+ * @property {string} [condition] Condition from --cond. V8 only breaks when it is truthy.
+ * Scoped to the location, so probes sharing a location all carry the same value.
  * @property {number} maxHit Per-probe hit limit from --max-hit. Infinity when unlimited.
  * @property {number} hits Count of hits observed.
  */
@@ -130,6 +133,12 @@ function formatTargetText(target) {
 returncolumn===undefined ? `${suffix}:${line}` : `${suffix}:${line}:${column}`;
 }
 
+// Identity of a probe location. Probes sharing a key share one V8 breakpoint,
+// so this must stay in sync between condition validation and breakpoint setup.
+functionlocationKey(target){
+return`${target.suffix}\n${target.line}\n${target.column??''}`;
+}
+
 functionformatPendingProbeLocations(probes,pending){
 constseen=newSafeSet();
 for(constprobeIndexofpending){
@@ -391,6 +400,22 @@ function parseProbeTokens(tokens, args) {
 probe.maxHit=parseUnsignedInteger(token.value,'max-hit');
 break;
 }
+case'cond': {
+if(probes.length===0){
+thrownewERR_DEBUGGER_STARTUP_ERROR('Unexpected --cond before --probe');
+}
+// A blank condition does not act as a real predicate in V8 (an empty
+// string always breaks), so reject it rather than silently mislead.
+if(token.value===undefined||StringPrototypeTrim(token.value)===''){
+thrownewERR_DEBUGGER_STARTUP_ERROR(`Missing value for ${token.rawName}`);
+}
+constprobe=probes[probes.length-1];
+if(probe.condition!==undefined){
+thrownewERR_DEBUGGER_STARTUP_ERROR('A --probe can have at most one --cond');
+}
+probe.condition=token.value;
+break;
+}
 default:
 if(probes.length>0){
 thrownewERR_DEBUGGER_STARTUP_ERROR(
@@ -410,6 +435,24 @@ function parseProbeTokens(tokens, args) {
 'Probe mode requires at least one --probe <loc> --expr <expr> group');
 }
 
+// V8 allows only one breakpoint per location, so probes sharing a location
+// cannot carry different conditions.
+constconditionByLocation=newSafeMap();
+for(const{ target, condition }ofprobes){
+constkey=locationKey(target);
+// All probes at the same location must share one condition. We split the
+// existence check since if one probe does not have a condition (= undefined),
+// then all probes at the location must also omit it.
+if(conditionByLocation.has(key)){
+if(conditionByLocation.get(key)!==condition){
+thrownewERR_DEBUGGER_STARTUP_ERROR(
+`Probes at ${formatTargetText(target)} must use the same --cond (or none)`);
+}
+}else{
+conditionByLocation.set(key,condition);
+}
+}
+
 constchildArgv=ArrayPrototypeSlice(args,childStartIndex);
 if(childArgv.length===0){
 thrownewERR_DEBUGGER_STARTUP_ERROR('Probe mode requires a child script');
@@ -479,8 +522,8 @@ class ProbeInspectorSession {
 this.resolveCompletion=resolve;
 /** @type {Probe[]} */
 this.probes=ArrayPrototypeMap(options.probes,
-({ expr, target, maxHit })=>
-({ expr, target,maxHit: maxHit??Infinity,hits: 0}));
+({ expr, target, maxHit, condition})=>
+({ expr, target,condition,maxHit: maxHit??Infinity,hits: 0}));
 this.onChildOutput=FunctionPrototypeBind(this.onChildOutput,this);
 this.onChildExit=FunctionPrototypeBind(this.onChildExit,this);
 this.onClientClose=FunctionPrototypeBind(this.onClientClose,this);
@@ -887,17 +930,19 @@ class ProbeInspectorSession {
 constuniqueTargets=newSafeMap();
 
 for(letprobeIndex=0;probeIndex<this.probes.length;probeIndex++){
-const{ target }=this.probes[probeIndex];
-constkey=`${target.suffix}\n${target.line}\n${target.column??''}`;
+const{ target, condition }=this.probes[probeIndex];
+// Probes at the same location share one V8 breakpoint. parseProbeTokens has
+// already ensured they carry the same condition.
+constkey=locationKey(target);
 letentry=uniqueTargets.get(key);
 if(entry===undefined){
-entry={ target,probeIndices: []};
+entry={ target,condition,probeIndices: []};
 uniqueTargets.set(key,entry);
 }
 ArrayPrototypePush(entry.probeIndices,probeIndex);
 }
 
-for(const{ target, probeIndices }ofuniqueTargets.values()){
+for(const{ target,condition,probeIndices }ofuniqueTargets.values()){
 // On Windows, normalize backslashes to forward slashes so the regex matches
 // V8 script URLs which always use forward slashes.
 constnormalizedFile=process.platform==='win32' ?
@@ -918,6 +963,9 @@ class ProbeInspectorSession {
 // the inspector bind to the first executable column.
 params.columnNumber=target.column-1;
 }
+if(condition!==undefined){
+params.condition=condition;
+}
 
 constresult=awaitthis.callCdp('Debugger.setBreakpointByUrl',params);
 debug('breakpoint set: id=%s urlRegex=%s locations=%j',
@@ -943,9 +991,10 @@ class ProbeInspectorSession {
 code: exitCode,
 report: {
 v: kProbeVersion,
-probes: ArrayPrototypeMap(this.probes,({ expr, target, maxHit })=>{
-// Omit an unlimited maxHit, as Infinity would serialize to null in JSON.
+probes: ArrayPrototypeMap(this.probes,({ expr, target, maxHit, condition })=>{
 constprobe={ expr, target };
+if(condition!==undefined){probe.condition=condition;}
+// Omit an unlimited maxHit, as Infinity would serialize to null in JSON.
 if(maxHit!==Infinity){probe.maxHit=maxHit;}
 returnprobe;
 }),

test/parallel/test-debugger-probe-cond-invalid.js

@@ -0,0 +1,40 @@
+// This tests that probe mode rejects malformed --cond usage.
+'use strict';
+
+constcommon=require('../common');
+common.skipIfInspectorDisabled();
+
+constfixtures=require('../common/fixtures');
+const{ assertProbeCliError }=require('../common/debugger-probe');
+
+constcwd=fixtures.path('debugger');
+
+assertProbeCliError(
+['--cond','x','--probe','probe.js:12','--expr','finalValue','probe.js'],
+/Unexpected--condbefore--probe/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--cond','x','--expr','finalValue','probe.js'],
+/Each--probemustbefollowedimmediatelyby--expr/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond','x','--cond','y','probe.js'],
+/A--probecanhaveatmostone--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond',' ','probe.js'],
+/Missingvaluefor--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond'],
+/Missingvaluefor--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','a','--cond','x',
+'--probe','probe.js:12','--expr','b','--cond','y','probe.js'],
+/Probesatprobe\.js:12mustusethesame--cond\(ornone\)/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','a','--cond','x',
+'--probe','probe.js:12','--expr','b','probe.js'],
+/Probesatprobe\.js:12mustusethesame--cond\(ornone\)/,{ cwd });

test/parallel/test-debugger-probe-cond-max-hit.js

@@ -0,0 +1,47 @@
+// This tests that --cond and --max-hit work together.
+'use strict';
+
+constcommon=require('../common');
+common.skipIfInspectorDisabled();
+
+constfixtures=require('../common/fixtures');
+const{ spawnSyncAndAssert }=require('../common/child_process');
+const{ assertProbeJson }=require('../common/debugger-probe');
+
+constcwd=fixtures.path('debugger');
+constprobeUrl=fixtures.fileURL('debugger','probe-max-hit.js').href;
+
+// --max-hit written before --cond. The condition still filters index !== 1, so
+// the only recorded hit carries value 1 rather than the loop's first iteration.
+spawnSyncAndAssert(process.execPath,[
+'inspect',
+'--json',
+'--probe','probe-max-hit.js:5',
+'--expr','index',
+'--max-hit','5',
+'--cond','index === 1',
+'probe-max-hit.js',
+],{ cwd },{
+stdout(output){
+assertProbeJson(output,{
+v: 2,
+probes: [{
+expr: 'index',
+condition: 'index === 1',
+maxHit: 5,
+target: {suffix: 'probe-max-hit.js',line: 5},
+}],
+results: [
+{
+probe: 0,
+event: 'hit',
+hit: 1,
+location: {url: probeUrl,line: 5,column: 3},
+result: {type: 'number',value: 1,description: '1'},
+},
+{event: 'completed'},
+],
+});
+},
+trim: true,
+});

doc/api/debugger.md

@@ -236,6 +236,10 @@ debug>
 added:
  - v24.16.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/64328
+ description: Add per-probe `--cond <expr>` option to only record a hit when the
+ condition is truthy at the probe location.
  - version: v24.19.0
  pr-url: https://github.com/nodejs/node/pull/63704
  description: Add per-probe `--max-hit <n>` option to limit evaluated hits and finish
@@ -268,8 +272,8 @@ printf-style debugging without having to modify the application code and
 clean up afterwards. It also supports structured JSON output for tool use.
 
 ```console
-$ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
- [--probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>] ...]
+$ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>]
+ [--probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>] ...]
  [--json] [--preview] [--timeout=<ms>] [--port=<port>]
  [--] [<node-option> ...] <script> [<script-args> ...]
 ```
@@ -282,6 +286,9 @@ $ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
 *`--expr <expr>`: JavaScript expression to evaluate whenever execution reaches
  the location specified by the preceding `--probe`.
  Must immediately follow the `--probe` it belongs to.
+*`--cond <expr>`: An optional condition for the probe location. The probe only
+ records a hit when `<expr>` is truthy at the location. A condition that throws
+ is treated as false.
 *`--max-hit <n>`: An optional per-probe limit on the number of times the probe
  can be hit. When not specified, there's no hit limit. When any probe reaches
  its hit limit, the probing process will detach and report the results. The process
@@ -297,14 +304,17 @@ $ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
  will listen. Defaults to `0`, which requests a random port.
 *`--` is optional unless the child needs its own Node.js flags.
 
-Additional rules about the `--probe` and `--expr` arguments:
+Additional rules about the composition of the options:
 
 *`--probe <file>:<line>[:<col>]` and `--expr <expr>` are strict pairs. Each
 `--probe` must be followed immediately by exactly one `--expr`.
-*`--max-hit <n>` is an optional per-probe option that applies to the most recent
-`--probe`/`--expr` pair. It may not appear before the first `--probe` or
- between a `--probe` and its matching `--expr`, and may be given at most once
- per probe.
+*`--cond <expr>` and `--max-hit <n>` are optional modifiers written _after_ the
+`--probe`/`--expr` pair they apply to, each at most once per pair. They may not
+ appear before the first `--probe` or between a `--probe` and its matching
+`--expr`.
+*`--max-hit` scopes to the `--probe`/`--expr` pair it follows, so pairs
+ sharing a location may set different limits. `--cond` scopes to the whole
+ location, probes sharing a location must share one condition (or none).
 *`--timeout`, `--json`, `--preview`, and `--port` are global probe options
  for the whole probe session. They may appear before or between probe pairs,
  but not between a `--probe` and its matching `--expr`.
@@ -379,6 +389,7 @@ $ node inspect --json --probe cli.js:5 --expr 'rss' cli.js
 "suffix": "cli.js",
 "line": 5
  }
+// `condition` is present only when the probe was given a --cond expression.
 // `maxHit` is present only when the probe was given a --max-hit limit.
  }
  ],
@@ -480,6 +491,10 @@ When multiple `--probe`/`--expr` pairs share the same `--probe`, the
 expressions will be evaluated on the same pause in the order they appear
 on the command line.
 
+For each location, there can only be at most one `--cond` (or none).
+Multiple `--probe`/`--expr` pairs with conflicting conditions
+at the same location will be rejected at launch time.
+
 ```js
 // app.js
 constx= { x:42 }; // line 2
@@ -563,6 +578,37 @@ that only matches the intended file:
 $ node inspect --probe src/utils.js:10 --expr 'x' main.js # matches only src/utils.js
 ```
 
+### Probe examples
+
+#### Probing a variable conditionally
+
+```js
+// app.js
+let total =0;
+for (let i =0; i <10; i++) {
+ total += i; // line 4
+}
+```
+
+```console
+$ out/Release/node inspect --probe app.js:4 --expr 'total' \
+ --cond 'i % 3 === 0' app.js
+```
+
+```text
+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
+```
+
+<!-- TODO(joyeecheung): add more examples for different options -->
+
 ## Advanced usage
 
 ### V8 inspector integration for Node.js

lib/internal/debugger/inspect.js

@@ -268,6 +268,7 @@ function parseInteractiveArgs(args) {
 
 constkInspectArgOptions={
 '__proto__': null,
+'cond': {type: 'string'},
 'expr': {type: 'string'},
 'help': {type: 'boolean',short: 'h'},
 'json': {type: 'boolean'},

lib/internal/debugger/inspect_helpers.js

@@ -69,8 +69,8 @@ function writeInspectUsageAndExit(invokedAs, message, exitCode) {
 }
 out.write(`Usage: ${invokedAs} [--port=<port>] [<node-option> ...]
  [<script> [<script-args>] | <host>:<port> | -p <pid>]
-${invokedAs} --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
- [--probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>] ...]
+${invokedAs} --probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>]
+ [--probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>] ...]
  [--json] [--preview] [--timeout=<ms>] [--port=<port>]
  [--] [<node-option> ...] <script> [<script-args> ...]
 
@@ -109,6 +109,9 @@ Options:
  preceding --probe each time execution reaches it.
  Avoid probing let/const-bound variables at their
  declaration site or a ReferenceError may be thrown.
+ --cond <expr> Optional condition for the probe location. The probe only
+ records a hit when <expr> is truthy at the location. A
+ condition that throws is treated as false.
  --max-hit <n> Per-probe limit on evaluated hits. When not specified,
  there's no hit limit. When any probe reaches its hit LIMIT,
  the probing process will detach and report the results.
@@ -121,6 +124,9 @@ Options:
 Semantics:
 * Multiple --probe/--expr pairs are allowed. Same-location --probes share
  a pause and scope, their --exprs are evaluated in command-line order.
+* --max-hit scopes to one --probe/--expr pair, so same-location pairs may set
+ different limits. --cond scopes to the location, probes sharing a location
+ must all share one condition (or none).
 * --probe utils.js:<line>[:<col>] matches every loaded utils.js. Pass a
  fuller path e.g. src/utils.js to narrow the match.
 * Use -- before any Node.js flags intended for the child process.

lib/internal/debugger/inspect_probe.js

@@ -21,6 +21,7 @@ const {
  StringPrototypeIncludes,
  StringPrototypeSlice,
  StringPrototypeStartsWith,
+ StringPrototypeTrim,
  Symbol,
 }=primordials;
 
@@ -87,6 +88,8 @@ const kInspectPortRegex = /^--inspect-port=(\d+)$/;
  * @typedef {object} Probe
  * @property {string} expr Expression to evaluate on hit.
  * @property {ProbeTarget} target User's original --probe request shape.
+ * @property {string} [condition] Condition from --cond. V8 only breaks when it is truthy.
+ * Scoped to the location, so probes sharing a location all carry the same value.
  * @property {number} maxHit Per-probe hit limit from --max-hit. Infinity when unlimited.
  * @property {number} hits Count of hits observed.
  */
@@ -130,6 +133,12 @@ function formatTargetText(target) {
 returncolumn===undefined ? `${suffix}:${line}` : `${suffix}:${line}:${column}`;
 }
 
+// Identity of a probe location. Probes sharing a key share one V8 breakpoint,
+// so this must stay in sync between condition validation and breakpoint setup.
+functionlocationKey(target){
+return`${target.suffix}\n${target.line}\n${target.column??''}`;
+}
+
 functionformatPendingProbeLocations(probes,pending){
 constseen=newSafeSet();
 for(constprobeIndexofpending){
@@ -391,6 +400,22 @@ function parseProbeTokens(tokens, args) {
 probe.maxHit=parseUnsignedInteger(token.value,'max-hit');
 break;
 }
+case'cond': {
+if(probes.length===0){
+thrownewERR_DEBUGGER_STARTUP_ERROR('Unexpected --cond before --probe');
+}
+// A blank condition does not act as a real predicate in V8 (an empty
+// string always breaks), so reject it rather than silently mislead.
+if(token.value===undefined||StringPrototypeTrim(token.value)===''){
+thrownewERR_DEBUGGER_STARTUP_ERROR(`Missing value for ${token.rawName}`);
+}
+constprobe=probes[probes.length-1];
+if(probe.condition!==undefined){
+thrownewERR_DEBUGGER_STARTUP_ERROR('A --probe can have at most one --cond');
+}
+probe.condition=token.value;
+break;
+}
 default:
 if(probes.length>0){
 thrownewERR_DEBUGGER_STARTUP_ERROR(
@@ -410,6 +435,24 @@ function parseProbeTokens(tokens, args) {
 'Probe mode requires at least one --probe <loc> --expr <expr> group');
 }
 
+// V8 allows only one breakpoint per location, so probes sharing a location
+// cannot carry different conditions.
+constconditionByLocation=newSafeMap();
+for(const{ target, condition }ofprobes){
+constkey=locationKey(target);
+// All probes at the same location must share one condition. We split the
+// existence check since if one probe does not have a condition (= undefined),
+// then all probes at the location must also omit it.
+if(conditionByLocation.has(key)){
+if(conditionByLocation.get(key)!==condition){
+thrownewERR_DEBUGGER_STARTUP_ERROR(
+`Probes at ${formatTargetText(target)} must use the same --cond (or none)`);
+}
+}else{
+conditionByLocation.set(key,condition);
+}
+}
+
 constchildArgv=ArrayPrototypeSlice(args,childStartIndex);
 if(childArgv.length===0){
 thrownewERR_DEBUGGER_STARTUP_ERROR('Probe mode requires a child script');
@@ -479,8 +522,8 @@ class ProbeInspectorSession {
 this.resolveCompletion=resolve;
 /** @type {Probe[]} */
 this.probes=ArrayPrototypeMap(options.probes,
-({ expr, target, maxHit })=>
-({ expr, target,maxHit: maxHit??Infinity,hits: 0}));
+({ expr, target, maxHit, condition})=>
+({ expr, target,condition,maxHit: maxHit??Infinity,hits: 0}));
 this.onChildOutput=FunctionPrototypeBind(this.onChildOutput,this);
 this.onChildExit=FunctionPrototypeBind(this.onChildExit,this);
 this.onClientClose=FunctionPrototypeBind(this.onClientClose,this);
@@ -887,17 +930,19 @@ class ProbeInspectorSession {
 constuniqueTargets=newSafeMap();
 
 for(letprobeIndex=0;probeIndex<this.probes.length;probeIndex++){
-const{ target }=this.probes[probeIndex];
-constkey=`${target.suffix}\n${target.line}\n${target.column??''}`;
+const{ target, condition }=this.probes[probeIndex];
+// Probes at the same location share one V8 breakpoint. parseProbeTokens has
+// already ensured they carry the same condition.
+constkey=locationKey(target);
 letentry=uniqueTargets.get(key);
 if(entry===undefined){
-entry={ target,probeIndices: []};
+entry={ target,condition,probeIndices: []};
 uniqueTargets.set(key,entry);
 }
 ArrayPrototypePush(entry.probeIndices,probeIndex);
 }
 
-for(const{ target, probeIndices }ofuniqueTargets.values()){
+for(const{ target,condition,probeIndices }ofuniqueTargets.values()){
 // On Windows, normalize backslashes to forward slashes so the regex matches
 // V8 script URLs which always use forward slashes.
 constnormalizedFile=process.platform==='win32' ?
@@ -918,6 +963,9 @@ class ProbeInspectorSession {
 // the inspector bind to the first executable column.
 params.columnNumber=target.column-1;
 }
+if(condition!==undefined){
+params.condition=condition;
+}
 
 constresult=awaitthis.callCdp('Debugger.setBreakpointByUrl',params);
 debug('breakpoint set: id=%s urlRegex=%s locations=%j',
@@ -943,9 +991,10 @@ class ProbeInspectorSession {
 code: exitCode,
 report: {
 v: kProbeVersion,
-probes: ArrayPrototypeMap(this.probes,({ expr, target, maxHit })=>{
-// Omit an unlimited maxHit, as Infinity would serialize to null in JSON.
+probes: ArrayPrototypeMap(this.probes,({ expr, target, maxHit, condition })=>{
 constprobe={ expr, target };
+if(condition!==undefined){probe.condition=condition;}
+// Omit an unlimited maxHit, as Infinity would serialize to null in JSON.
 if(maxHit!==Infinity){probe.maxHit=maxHit;}
 returnprobe;
 }),

test/parallel/test-debugger-probe-cond-invalid.js

@@ -0,0 +1,40 @@
+// This tests that probe mode rejects malformed --cond usage.
+'use strict';
+
+constcommon=require('../common');
+common.skipIfInspectorDisabled();
+
+constfixtures=require('../common/fixtures');
+const{ assertProbeCliError }=require('../common/debugger-probe');
+
+constcwd=fixtures.path('debugger');
+
+assertProbeCliError(
+['--cond','x','--probe','probe.js:12','--expr','finalValue','probe.js'],
+/Unexpected--condbefore--probe/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--cond','x','--expr','finalValue','probe.js'],
+/Each--probemustbefollowedimmediatelyby--expr/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond','x','--cond','y','probe.js'],
+/A--probecanhaveatmostone--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond',' ','probe.js'],
+/Missingvaluefor--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond'],
+/Missingvaluefor--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','a','--cond','x',
+'--probe','probe.js:12','--expr','b','--cond','y','probe.js'],
+/Probesatprobe\.js:12mustusethesame--cond\(ornone\)/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','a','--cond','x',
+'--probe','probe.js:12','--expr','b','probe.js'],
+/Probesatprobe\.js:12mustusethesame--cond\(ornone\)/,{ cwd });

test/parallel/test-debugger-probe-cond-max-hit.js

@@ -0,0 +1,47 @@
+// This tests that --cond and --max-hit work together.
+'use strict';
+
+constcommon=require('../common');
+common.skipIfInspectorDisabled();
+
+constfixtures=require('../common/fixtures');
+const{ spawnSyncAndAssert }=require('../common/child_process');
+const{ assertProbeJson }=require('../common/debugger-probe');
+
+constcwd=fixtures.path('debugger');
+constprobeUrl=fixtures.fileURL('debugger','probe-max-hit.js').href;
+
+// --max-hit written before --cond. The condition still filters index !== 1, so
+// the only recorded hit carries value 1 rather than the loop's first iteration.
+spawnSyncAndAssert(process.execPath,[
+'inspect',
+'--json',
+'--probe','probe-max-hit.js:5',
+'--expr','index',
+'--max-hit','5',
+'--cond','index === 1',
+'probe-max-hit.js',
+],{ cwd },{
+stdout(output){
+assertProbeJson(output,{
+v: 2,
+probes: [{
+expr: 'index',
+condition: 'index === 1',
+maxHit: 5,
+target: {suffix: 'probe-max-hit.js',line: 5},
+}],
+results: [
+{
+probe: 0,
+event: 'hit',
+hit: 1,
+location: {url: probeUrl,line: 5,column: 3},
+result: {type: 'number',value: 1,description: '1'},
+},
+{event: 'completed'},
+],
+});
+},
+trim: true,
+});

doc/api/debugger.md

@@ -236,6 +236,10 @@ debug>
 added:
  - v24.16.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/64328
+ description: Add per-probe `--cond <expr>` option to only record a hit when the
+ condition is truthy at the probe location.
  - version: v24.19.0
  pr-url: https://github.com/nodejs/node/pull/63704
  description: Add per-probe `--max-hit <n>` option to limit evaluated hits and finish
@@ -268,8 +272,8 @@ printf-style debugging without having to modify the application code and
 clean up afterwards. It also supports structured JSON output for tool use.
 
 ```console
-$ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
- [--probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>] ...]
+$ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>]
+ [--probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>] ...]
  [--json] [--preview] [--timeout=<ms>] [--port=<port>]
  [--] [<node-option> ...] <script> [<script-args> ...]
 ```
@@ -282,6 +286,9 @@ $ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
 *`--expr <expr>`: JavaScript expression to evaluate whenever execution reaches
  the location specified by the preceding `--probe`.
  Must immediately follow the `--probe` it belongs to.
+*`--cond <expr>`: An optional condition for the probe location. The probe only
+ records a hit when `<expr>` is truthy at the location. A condition that throws
+ is treated as false.
 *`--max-hit <n>`: An optional per-probe limit on the number of times the probe
  can be hit. When not specified, there's no hit limit. When any probe reaches
  its hit limit, the probing process will detach and report the results. The process
@@ -297,14 +304,17 @@ $ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
  will listen. Defaults to `0`, which requests a random port.
 *`--` is optional unless the child needs its own Node.js flags.
 
-Additional rules about the `--probe` and `--expr` arguments:
+Additional rules about the composition of the options:
 
 *`--probe <file>:<line>[:<col>]` and `--expr <expr>` are strict pairs. Each
 `--probe` must be followed immediately by exactly one `--expr`.
-*`--max-hit <n>` is an optional per-probe option that applies to the most recent
-`--probe`/`--expr` pair. It may not appear before the first `--probe` or
- between a `--probe` and its matching `--expr`, and may be given at most once
- per probe.
+*`--cond <expr>` and `--max-hit <n>` are optional modifiers written _after_ the
+`--probe`/`--expr` pair they apply to, each at most once per pair. They may not
+ appear before the first `--probe` or between a `--probe` and its matching
+`--expr`.
+*`--max-hit` scopes to the `--probe`/`--expr` pair it follows, so pairs
+ sharing a location may set different limits. `--cond` scopes to the whole
+ location, probes sharing a location must share one condition (or none).
 *`--timeout`, `--json`, `--preview`, and `--port` are global probe options
  for the whole probe session. They may appear before or between probe pairs,
  but not between a `--probe` and its matching `--expr`.
@@ -379,6 +389,7 @@ $ node inspect --json --probe cli.js:5 --expr 'rss' cli.js
 "suffix": "cli.js",
 "line": 5
  }
+// `condition` is present only when the probe was given a --cond expression.
 // `maxHit` is present only when the probe was given a --max-hit limit.
  }
  ],
@@ -480,6 +491,10 @@ When multiple `--probe`/`--expr` pairs share the same `--probe`, the
 expressions will be evaluated on the same pause in the order they appear
 on the command line.
 
+For each location, there can only be at most one `--cond` (or none).
+Multiple `--probe`/`--expr` pairs with conflicting conditions
+at the same location will be rejected at launch time.
+
 ```js
 // app.js
 constx= { x:42 }; // line 2
@@ -563,6 +578,37 @@ that only matches the intended file:
 $ node inspect --probe src/utils.js:10 --expr 'x' main.js # matches only src/utils.js
 ```
 
+### Probe examples
+
+#### Probing a variable conditionally
+
+```js
+// app.js
+let total =0;
+for (let i =0; i <10; i++) {
+ total += i; // line 4
+}
+```
+
+```console
+$ out/Release/node inspect --probe app.js:4 --expr 'total' \
+ --cond 'i % 3 === 0' app.js
+```
+
+```text
+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
+```
+
+<!-- TODO(joyeecheung): add more examples for different options -->
+
 ## Advanced usage
 
 ### V8 inspector integration for Node.js

lib/internal/debugger/inspect.js

@@ -268,6 +268,7 @@ function parseInteractiveArgs(args) {
 
 constkInspectArgOptions={
 '__proto__': null,
+'cond': {type: 'string'},
 'expr': {type: 'string'},
 'help': {type: 'boolean',short: 'h'},
 'json': {type: 'boolean'},

lib/internal/debugger/inspect_helpers.js

@@ -69,8 +69,8 @@ function writeInspectUsageAndExit(invokedAs, message, exitCode) {
 }
 out.write(`Usage: ${invokedAs} [--port=<port>] [<node-option> ...]
  [<script> [<script-args>] | <host>:<port> | -p <pid>]
-${invokedAs} --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
- [--probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>] ...]
+${invokedAs} --probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>]
+ [--probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>] ...]
  [--json] [--preview] [--timeout=<ms>] [--port=<port>]
  [--] [<node-option> ...] <script> [<script-args> ...]
 
@@ -109,6 +109,9 @@ Options:
  preceding --probe each time execution reaches it.
  Avoid probing let/const-bound variables at their
  declaration site or a ReferenceError may be thrown.
+ --cond <expr> Optional condition for the probe location. The probe only
+ records a hit when <expr> is truthy at the location. A
+ condition that throws is treated as false.
  --max-hit <n> Per-probe limit on evaluated hits. When not specified,
  there's no hit limit. When any probe reaches its hit LIMIT,
  the probing process will detach and report the results.
@@ -121,6 +124,9 @@ Options:
 Semantics:
 * Multiple --probe/--expr pairs are allowed. Same-location --probes share
  a pause and scope, their --exprs are evaluated in command-line order.
+* --max-hit scopes to one --probe/--expr pair, so same-location pairs may set
+ different limits. --cond scopes to the location, probes sharing a location
+ must all share one condition (or none).
 * --probe utils.js:<line>[:<col>] matches every loaded utils.js. Pass a
  fuller path e.g. src/utils.js to narrow the match.
 * Use -- before any Node.js flags intended for the child process.

lib/internal/debugger/inspect_probe.js

@@ -21,6 +21,7 @@ const {
  StringPrototypeIncludes,
  StringPrototypeSlice,
  StringPrototypeStartsWith,
+ StringPrototypeTrim,
  Symbol,
 }=primordials;
 
@@ -87,6 +88,8 @@ const kInspectPortRegex = /^--inspect-port=(\d+)$/;
  * @typedef {object} Probe
  * @property {string} expr Expression to evaluate on hit.
  * @property {ProbeTarget} target User's original --probe request shape.
+ * @property {string} [condition] Condition from --cond. V8 only breaks when it is truthy.
+ * Scoped to the location, so probes sharing a location all carry the same value.
  * @property {number} maxHit Per-probe hit limit from --max-hit. Infinity when unlimited.
  * @property {number} hits Count of hits observed.
  */
@@ -130,6 +133,12 @@ function formatTargetText(target) {
 returncolumn===undefined ? `${suffix}:${line}` : `${suffix}:${line}:${column}`;
 }
 
+// Identity of a probe location. Probes sharing a key share one V8 breakpoint,
+// so this must stay in sync between condition validation and breakpoint setup.
+functionlocationKey(target){
+return`${target.suffix}\n${target.line}\n${target.column??''}`;
+}
+
 functionformatPendingProbeLocations(probes,pending){
 constseen=newSafeSet();
 for(constprobeIndexofpending){
@@ -391,6 +400,22 @@ function parseProbeTokens(tokens, args) {
 probe.maxHit=parseUnsignedInteger(token.value,'max-hit');
 break;
 }
+case'cond': {
+if(probes.length===0){
+thrownewERR_DEBUGGER_STARTUP_ERROR('Unexpected --cond before --probe');
+}
+// A blank condition does not act as a real predicate in V8 (an empty
+// string always breaks), so reject it rather than silently mislead.
+if(token.value===undefined||StringPrototypeTrim(token.value)===''){
+thrownewERR_DEBUGGER_STARTUP_ERROR(`Missing value for ${token.rawName}`);
+}
+constprobe=probes[probes.length-1];
+if(probe.condition!==undefined){
+thrownewERR_DEBUGGER_STARTUP_ERROR('A --probe can have at most one --cond');
+}
+probe.condition=token.value;
+break;
+}
 default:
 if(probes.length>0){
 thrownewERR_DEBUGGER_STARTUP_ERROR(
@@ -410,6 +435,24 @@ function parseProbeTokens(tokens, args) {
 'Probe mode requires at least one --probe <loc> --expr <expr> group');
 }
 
+// V8 allows only one breakpoint per location, so probes sharing a location
+// cannot carry different conditions.
+constconditionByLocation=newSafeMap();
+for(const{ target, condition }ofprobes){
+constkey=locationKey(target);
+// All probes at the same location must share one condition. We split the
+// existence check since if one probe does not have a condition (= undefined),
+// then all probes at the location must also omit it.
+if(conditionByLocation.has(key)){
+if(conditionByLocation.get(key)!==condition){
+thrownewERR_DEBUGGER_STARTUP_ERROR(
+`Probes at ${formatTargetText(target)} must use the same --cond (or none)`);
+}
+}else{
+conditionByLocation.set(key,condition);
+}
+}
+
 constchildArgv=ArrayPrototypeSlice(args,childStartIndex);
 if(childArgv.length===0){
 thrownewERR_DEBUGGER_STARTUP_ERROR('Probe mode requires a child script');
@@ -479,8 +522,8 @@ class ProbeInspectorSession {
 this.resolveCompletion=resolve;
 /** @type {Probe[]} */
 this.probes=ArrayPrototypeMap(options.probes,
-({ expr, target, maxHit })=>
-({ expr, target,maxHit: maxHit??Infinity,hits: 0}));
+({ expr, target, maxHit, condition})=>
+({ expr, target,condition,maxHit: maxHit??Infinity,hits: 0}));
 this.onChildOutput=FunctionPrototypeBind(this.onChildOutput,this);
 this.onChildExit=FunctionPrototypeBind(this.onChildExit,this);
 this.onClientClose=FunctionPrototypeBind(this.onClientClose,this);
@@ -887,17 +930,19 @@ class ProbeInspectorSession {
 constuniqueTargets=newSafeMap();
 
 for(letprobeIndex=0;probeIndex<this.probes.length;probeIndex++){
-const{ target }=this.probes[probeIndex];
-constkey=`${target.suffix}\n${target.line}\n${target.column??''}`;
+const{ target, condition }=this.probes[probeIndex];
+// Probes at the same location share one V8 breakpoint. parseProbeTokens has
+// already ensured they carry the same condition.
+constkey=locationKey(target);
 letentry=uniqueTargets.get(key);
 if(entry===undefined){
-entry={ target,probeIndices: []};
+entry={ target,condition,probeIndices: []};
 uniqueTargets.set(key,entry);
 }
 ArrayPrototypePush(entry.probeIndices,probeIndex);
 }
 
-for(const{ target, probeIndices }ofuniqueTargets.values()){
+for(const{ target,condition,probeIndices }ofuniqueTargets.values()){
 // On Windows, normalize backslashes to forward slashes so the regex matches
 // V8 script URLs which always use forward slashes.
 constnormalizedFile=process.platform==='win32' ?
@@ -918,6 +963,9 @@ class ProbeInspectorSession {
 // the inspector bind to the first executable column.
 params.columnNumber=target.column-1;
 }
+if(condition!==undefined){
+params.condition=condition;
+}
 
 constresult=awaitthis.callCdp('Debugger.setBreakpointByUrl',params);
 debug('breakpoint set: id=%s urlRegex=%s locations=%j',
@@ -943,9 +991,10 @@ class ProbeInspectorSession {
 code: exitCode,
 report: {
 v: kProbeVersion,
-probes: ArrayPrototypeMap(this.probes,({ expr, target, maxHit })=>{
-// Omit an unlimited maxHit, as Infinity would serialize to null in JSON.
+probes: ArrayPrototypeMap(this.probes,({ expr, target, maxHit, condition })=>{
 constprobe={ expr, target };
+if(condition!==undefined){probe.condition=condition;}
+// Omit an unlimited maxHit, as Infinity would serialize to null in JSON.
 if(maxHit!==Infinity){probe.maxHit=maxHit;}
 returnprobe;
 }),

test/parallel/test-debugger-probe-cond-invalid.js

@@ -0,0 +1,40 @@
+// This tests that probe mode rejects malformed --cond usage.
+'use strict';
+
+constcommon=require('../common');
+common.skipIfInspectorDisabled();
+
+constfixtures=require('../common/fixtures');
+const{ assertProbeCliError }=require('../common/debugger-probe');
+
+constcwd=fixtures.path('debugger');
+
+assertProbeCliError(
+['--cond','x','--probe','probe.js:12','--expr','finalValue','probe.js'],
+/Unexpected--condbefore--probe/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--cond','x','--expr','finalValue','probe.js'],
+/Each--probemustbefollowedimmediatelyby--expr/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond','x','--cond','y','probe.js'],
+/A--probecanhaveatmostone--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond',' ','probe.js'],
+/Missingvaluefor--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond'],
+/Missingvaluefor--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','a','--cond','x',
+'--probe','probe.js:12','--expr','b','--cond','y','probe.js'],
+/Probesatprobe\.js:12mustusethesame--cond\(ornone\)/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','a','--cond','x',
+'--probe','probe.js:12','--expr','b','probe.js'],
+/Probesatprobe\.js:12mustusethesame--cond\(ornone\)/,{ cwd });

test/parallel/test-debugger-probe-cond-max-hit.js

@@ -0,0 +1,47 @@
+// This tests that --cond and --max-hit work together.
+'use strict';
+
+constcommon=require('../common');
+common.skipIfInspectorDisabled();
+
+constfixtures=require('../common/fixtures');
+const{ spawnSyncAndAssert }=require('../common/child_process');
+const{ assertProbeJson }=require('../common/debugger-probe');
+
+constcwd=fixtures.path('debugger');
+constprobeUrl=fixtures.fileURL('debugger','probe-max-hit.js').href;
+
+// --max-hit written before --cond. The condition still filters index !== 1, so
+// the only recorded hit carries value 1 rather than the loop's first iteration.
+spawnSyncAndAssert(process.execPath,[
+'inspect',
+'--json',
+'--probe','probe-max-hit.js:5',
+'--expr','index',
+'--max-hit','5',
+'--cond','index === 1',
+'probe-max-hit.js',
+],{ cwd },{
+stdout(output){
+assertProbeJson(output,{
+v: 2,
+probes: [{
+expr: 'index',
+condition: 'index === 1',
+maxHit: 5,
+target: {suffix: 'probe-max-hit.js',line: 5},
+}],
+results: [
+{
+probe: 0,
+event: 'hit',
+hit: 1,
+location: {url: probeUrl,line: 5,column: 3},
+result: {type: 'number',value: 1,description: '1'},
+},
+{event: 'completed'},
+],
+});
+},
+trim: true,
+});

doc/api/debugger.md

@@ -236,6 +236,10 @@ debug>
 added:
  - v24.16.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/64328
+ description: Add per-probe `--cond <expr>` option to only record a hit when the
+ condition is truthy at the probe location.
  - version: v24.19.0
  pr-url: https://github.com/nodejs/node/pull/63704
  description: Add per-probe `--max-hit <n>` option to limit evaluated hits and finish
@@ -268,8 +272,8 @@ printf-style debugging without having to modify the application code and
 clean up afterwards. It also supports structured JSON output for tool use.
 
 ```console
-$ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
- [--probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>] ...]
+$ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>]
+ [--probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>] ...]
  [--json] [--preview] [--timeout=<ms>] [--port=<port>]
  [--] [<node-option> ...] <script> [<script-args> ...]
 ```
@@ -282,6 +286,9 @@ $ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
 *`--expr <expr>`: JavaScript expression to evaluate whenever execution reaches
  the location specified by the preceding `--probe`.
  Must immediately follow the `--probe` it belongs to.
+*`--cond <expr>`: An optional condition for the probe location. The probe only
+ records a hit when `<expr>` is truthy at the location. A condition that throws
+ is treated as false.
 *`--max-hit <n>`: An optional per-probe limit on the number of times the probe
  can be hit. When not specified, there's no hit limit. When any probe reaches
  its hit limit, the probing process will detach and report the results. The process
@@ -297,14 +304,17 @@ $ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
  will listen. Defaults to `0`, which requests a random port.
 *`--` is optional unless the child needs its own Node.js flags.
 
-Additional rules about the `--probe` and `--expr` arguments:
+Additional rules about the composition of the options:
 
 *`--probe <file>:<line>[:<col>]` and `--expr <expr>` are strict pairs. Each
 `--probe` must be followed immediately by exactly one `--expr`.
-*`--max-hit <n>` is an optional per-probe option that applies to the most recent
-`--probe`/`--expr` pair. It may not appear before the first `--probe` or
- between a `--probe` and its matching `--expr`, and may be given at most once
- per probe.
+*`--cond <expr>` and `--max-hit <n>` are optional modifiers written _after_ the
+`--probe`/`--expr` pair they apply to, each at most once per pair. They may not
+ appear before the first `--probe` or between a `--probe` and its matching
+`--expr`.
+*`--max-hit` scopes to the `--probe`/`--expr` pair it follows, so pairs
+ sharing a location may set different limits. `--cond` scopes to the whole
+ location, probes sharing a location must share one condition (or none).
 *`--timeout`, `--json`, `--preview`, and `--port` are global probe options
  for the whole probe session. They may appear before or between probe pairs,
  but not between a `--probe` and its matching `--expr`.
@@ -379,6 +389,7 @@ $ node inspect --json --probe cli.js:5 --expr 'rss' cli.js
 "suffix": "cli.js",
 "line": 5
  }
+// `condition` is present only when the probe was given a --cond expression.
 // `maxHit` is present only when the probe was given a --max-hit limit.
  }
  ],
@@ -480,6 +491,10 @@ When multiple `--probe`/`--expr` pairs share the same `--probe`, the
 expressions will be evaluated on the same pause in the order they appear
 on the command line.
 
+For each location, there can only be at most one `--cond` (or none).
+Multiple `--probe`/`--expr` pairs with conflicting conditions
+at the same location will be rejected at launch time.
+
 ```js
 // app.js
 constx= { x:42 }; // line 2
@@ -563,6 +578,37 @@ that only matches the intended file:
 $ node inspect --probe src/utils.js:10 --expr 'x' main.js # matches only src/utils.js
 ```
 
+### Probe examples
+
+#### Probing a variable conditionally
+
+```js
+// app.js
+let total =0;
+for (let i =0; i <10; i++) {
+ total += i; // line 4
+}
+```
+
+```console
+$ out/Release/node inspect --probe app.js:4 --expr 'total' \
+ --cond 'i % 3 === 0' app.js
+```
+
+```text
+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
+```
+
+<!-- TODO(joyeecheung): add more examples for different options -->
+
 ## Advanced usage
 
 ### V8 inspector integration for Node.js

lib/internal/debugger/inspect.js

@@ -268,6 +268,7 @@ function parseInteractiveArgs(args) {
 
 constkInspectArgOptions={
 '__proto__': null,
+'cond': {type: 'string'},
 'expr': {type: 'string'},
 'help': {type: 'boolean',short: 'h'},
 'json': {type: 'boolean'},

lib/internal/debugger/inspect_helpers.js

@@ -69,8 +69,8 @@ function writeInspectUsageAndExit(invokedAs, message, exitCode) {
 }
 out.write(`Usage: ${invokedAs} [--port=<port>] [<node-option> ...]
  [<script> [<script-args>] | <host>:<port> | -p <pid>]
-${invokedAs} --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
- [--probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>] ...]
+${invokedAs} --probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>]
+ [--probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>] ...]
  [--json] [--preview] [--timeout=<ms>] [--port=<port>]
  [--] [<node-option> ...] <script> [<script-args> ...]
 
@@ -109,6 +109,9 @@ Options:
  preceding --probe each time execution reaches it.
  Avoid probing let/const-bound variables at their
  declaration site or a ReferenceError may be thrown.
+ --cond <expr> Optional condition for the probe location. The probe only
+ records a hit when <expr> is truthy at the location. A
+ condition that throws is treated as false.
  --max-hit <n> Per-probe limit on evaluated hits. When not specified,
  there's no hit limit. When any probe reaches its hit LIMIT,
  the probing process will detach and report the results.
@@ -121,6 +124,9 @@ Options:
 Semantics:
 * Multiple --probe/--expr pairs are allowed. Same-location --probes share
  a pause and scope, their --exprs are evaluated in command-line order.
+* --max-hit scopes to one --probe/--expr pair, so same-location pairs may set
+ different limits. --cond scopes to the location, probes sharing a location
+ must all share one condition (or none).
 * --probe utils.js:<line>[:<col>] matches every loaded utils.js. Pass a
  fuller path e.g. src/utils.js to narrow the match.
 * Use -- before any Node.js flags intended for the child process.

lib/internal/debugger/inspect_probe.js

@@ -21,6 +21,7 @@ const {
  StringPrototypeIncludes,
  StringPrototypeSlice,
  StringPrototypeStartsWith,
+ StringPrototypeTrim,
  Symbol,
 }=primordials;
 
@@ -87,6 +88,8 @@ const kInspectPortRegex = /^--inspect-port=(\d+)$/;
  * @typedef {object} Probe
  * @property {string} expr Expression to evaluate on hit.
  * @property {ProbeTarget} target User's original --probe request shape.
+ * @property {string} [condition] Condition from --cond. V8 only breaks when it is truthy.
+ * Scoped to the location, so probes sharing a location all carry the same value.
  * @property {number} maxHit Per-probe hit limit from --max-hit. Infinity when unlimited.
  * @property {number} hits Count of hits observed.
  */
@@ -130,6 +133,12 @@ function formatTargetText(target) {
 returncolumn===undefined ? `${suffix}:${line}` : `${suffix}:${line}:${column}`;
 }
 
+// Identity of a probe location. Probes sharing a key share one V8 breakpoint,
+// so this must stay in sync between condition validation and breakpoint setup.
+functionlocationKey(target){
+return`${target.suffix}\n${target.line}\n${target.column??''}`;
+}
+
 functionformatPendingProbeLocations(probes,pending){
 constseen=newSafeSet();
 for(constprobeIndexofpending){
@@ -391,6 +400,22 @@ function parseProbeTokens(tokens, args) {
 probe.maxHit=parseUnsignedInteger(token.value,'max-hit');
 break;
 }
+case'cond': {
+if(probes.length===0){
+thrownewERR_DEBUGGER_STARTUP_ERROR('Unexpected --cond before --probe');
+}
+// A blank condition does not act as a real predicate in V8 (an empty
+// string always breaks), so reject it rather than silently mislead.
+if(token.value===undefined||StringPrototypeTrim(token.value)===''){
+thrownewERR_DEBUGGER_STARTUP_ERROR(`Missing value for ${token.rawName}`);
+}
+constprobe=probes[probes.length-1];
+if(probe.condition!==undefined){
+thrownewERR_DEBUGGER_STARTUP_ERROR('A --probe can have at most one --cond');
+}
+probe.condition=token.value;
+break;
+}
 default:
 if(probes.length>0){
 thrownewERR_DEBUGGER_STARTUP_ERROR(
@@ -410,6 +435,24 @@ function parseProbeTokens(tokens, args) {
 'Probe mode requires at least one --probe <loc> --expr <expr> group');
 }
 
+// V8 allows only one breakpoint per location, so probes sharing a location
+// cannot carry different conditions.
+constconditionByLocation=newSafeMap();
+for(const{ target, condition }ofprobes){
+constkey=locationKey(target);
+// All probes at the same location must share one condition. We split the
+// existence check since if one probe does not have a condition (= undefined),
+// then all probes at the location must also omit it.
+if(conditionByLocation.has(key)){
+if(conditionByLocation.get(key)!==condition){
+thrownewERR_DEBUGGER_STARTUP_ERROR(
+`Probes at ${formatTargetText(target)} must use the same --cond (or none)`);
+}
+}else{
+conditionByLocation.set(key,condition);
+}
+}
+
 constchildArgv=ArrayPrototypeSlice(args,childStartIndex);
 if(childArgv.length===0){
 thrownewERR_DEBUGGER_STARTUP_ERROR('Probe mode requires a child script');
@@ -479,8 +522,8 @@ class ProbeInspectorSession {
 this.resolveCompletion=resolve;
 /** @type {Probe[]} */
 this.probes=ArrayPrototypeMap(options.probes,
-({ expr, target, maxHit })=>
-({ expr, target,maxHit: maxHit??Infinity,hits: 0}));
+({ expr, target, maxHit, condition})=>
+({ expr, target,condition,maxHit: maxHit??Infinity,hits: 0}));
 this.onChildOutput=FunctionPrototypeBind(this.onChildOutput,this);
 this.onChildExit=FunctionPrototypeBind(this.onChildExit,this);
 this.onClientClose=FunctionPrototypeBind(this.onClientClose,this);
@@ -887,17 +930,19 @@ class ProbeInspectorSession {
 constuniqueTargets=newSafeMap();
 
 for(letprobeIndex=0;probeIndex<this.probes.length;probeIndex++){
-const{ target }=this.probes[probeIndex];
-constkey=`${target.suffix}\n${target.line}\n${target.column??''}`;
+const{ target, condition }=this.probes[probeIndex];
+// Probes at the same location share one V8 breakpoint. parseProbeTokens has
+// already ensured they carry the same condition.
+constkey=locationKey(target);
 letentry=uniqueTargets.get(key);
 if(entry===undefined){
-entry={ target,probeIndices: []};
+entry={ target,condition,probeIndices: []};
 uniqueTargets.set(key,entry);
 }
 ArrayPrototypePush(entry.probeIndices,probeIndex);
 }
 
-for(const{ target, probeIndices }ofuniqueTargets.values()){
+for(const{ target,condition,probeIndices }ofuniqueTargets.values()){
 // On Windows, normalize backslashes to forward slashes so the regex matches
 // V8 script URLs which always use forward slashes.
 constnormalizedFile=process.platform==='win32' ?
@@ -918,6 +963,9 @@ class ProbeInspectorSession {
 // the inspector bind to the first executable column.
 params.columnNumber=target.column-1;
 }
+if(condition!==undefined){
+params.condition=condition;
+}
 
 constresult=awaitthis.callCdp('Debugger.setBreakpointByUrl',params);
 debug('breakpoint set: id=%s urlRegex=%s locations=%j',
@@ -943,9 +991,10 @@ class ProbeInspectorSession {
 code: exitCode,
 report: {
 v: kProbeVersion,
-probes: ArrayPrototypeMap(this.probes,({ expr, target, maxHit })=>{
-// Omit an unlimited maxHit, as Infinity would serialize to null in JSON.
+probes: ArrayPrototypeMap(this.probes,({ expr, target, maxHit, condition })=>{
 constprobe={ expr, target };
+if(condition!==undefined){probe.condition=condition;}
+// Omit an unlimited maxHit, as Infinity would serialize to null in JSON.
 if(maxHit!==Infinity){probe.maxHit=maxHit;}
 returnprobe;
 }),

test/parallel/test-debugger-probe-cond-invalid.js

@@ -0,0 +1,40 @@
+// This tests that probe mode rejects malformed --cond usage.
+'use strict';
+
+constcommon=require('../common');
+common.skipIfInspectorDisabled();
+
+constfixtures=require('../common/fixtures');
+const{ assertProbeCliError }=require('../common/debugger-probe');
+
+constcwd=fixtures.path('debugger');
+
+assertProbeCliError(
+['--cond','x','--probe','probe.js:12','--expr','finalValue','probe.js'],
+/Unexpected--condbefore--probe/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--cond','x','--expr','finalValue','probe.js'],
+/Each--probemustbefollowedimmediatelyby--expr/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond','x','--cond','y','probe.js'],
+/A--probecanhaveatmostone--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond',' ','probe.js'],
+/Missingvaluefor--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond'],
+/Missingvaluefor--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','a','--cond','x',
+'--probe','probe.js:12','--expr','b','--cond','y','probe.js'],
+/Probesatprobe\.js:12mustusethesame--cond\(ornone\)/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','a','--cond','x',
+'--probe','probe.js:12','--expr','b','probe.js'],
+/Probesatprobe\.js:12mustusethesame--cond\(ornone\)/,{ cwd });

test/parallel/test-debugger-probe-cond-max-hit.js

@@ -0,0 +1,47 @@
+// This tests that --cond and --max-hit work together.
+'use strict';
+
+constcommon=require('../common');
+common.skipIfInspectorDisabled();
+
+constfixtures=require('../common/fixtures');
+const{ spawnSyncAndAssert }=require('../common/child_process');
+const{ assertProbeJson }=require('../common/debugger-probe');
+
+constcwd=fixtures.path('debugger');
+constprobeUrl=fixtures.fileURL('debugger','probe-max-hit.js').href;
+
+// --max-hit written before --cond. The condition still filters index !== 1, so
+// the only recorded hit carries value 1 rather than the loop's first iteration.
+spawnSyncAndAssert(process.execPath,[
+'inspect',
+'--json',
+'--probe','probe-max-hit.js:5',
+'--expr','index',
+'--max-hit','5',
+'--cond','index === 1',
+'probe-max-hit.js',
+],{ cwd },{
+stdout(output){
+assertProbeJson(output,{
+v: 2,
+probes: [{
+expr: 'index',
+condition: 'index === 1',
+maxHit: 5,
+target: {suffix: 'probe-max-hit.js',line: 5},
+}],
+results: [
+{
+probe: 0,
+event: 'hit',
+hit: 1,
+location: {url: probeUrl,line: 5,column: 3},
+result: {type: 'number',value: 1,description: '1'},
+},
+{event: 'completed'},
+],
+});
+},
+trim: true,
+});

doc/api/debugger.md

@@ -236,6 +236,10 @@ debug>
 added:
  - v24.16.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/64328
+ description: Add per-probe `--cond <expr>` option to only record a hit when the
+ condition is truthy at the probe location.
  - version: v24.19.0
  pr-url: https://github.com/nodejs/node/pull/63704
  description: Add per-probe `--max-hit <n>` option to limit evaluated hits and finish
@@ -268,8 +272,8 @@ printf-style debugging without having to modify the application code and
 clean up afterwards. It also supports structured JSON output for tool use.
 
 ```console
-$ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
- [--probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>] ...]
+$ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>]
+ [--probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>] ...]
  [--json] [--preview] [--timeout=<ms>] [--port=<port>]
  [--] [<node-option> ...] <script> [<script-args> ...]
 ```
@@ -282,6 +286,9 @@ $ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
 *`--expr <expr>`: JavaScript expression to evaluate whenever execution reaches
  the location specified by the preceding `--probe`.
  Must immediately follow the `--probe` it belongs to.
+*`--cond <expr>`: An optional condition for the probe location. The probe only
+ records a hit when `<expr>` is truthy at the location. A condition that throws
+ is treated as false.
 *`--max-hit <n>`: An optional per-probe limit on the number of times the probe
  can be hit. When not specified, there's no hit limit. When any probe reaches
  its hit limit, the probing process will detach and report the results. The process
@@ -297,14 +304,17 @@ $ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
  will listen. Defaults to `0`, which requests a random port.
 *`--` is optional unless the child needs its own Node.js flags.
 
-Additional rules about the `--probe` and `--expr` arguments:
+Additional rules about the composition of the options:
 
 *`--probe <file>:<line>[:<col>]` and `--expr <expr>` are strict pairs. Each
 `--probe` must be followed immediately by exactly one `--expr`.
-*`--max-hit <n>` is an optional per-probe option that applies to the most recent
-`--probe`/`--expr` pair. It may not appear before the first `--probe` or
- between a `--probe` and its matching `--expr`, and may be given at most once
- per probe.
+*`--cond <expr>` and `--max-hit <n>` are optional modifiers written _after_ the
+`--probe`/`--expr` pair they apply to, each at most once per pair. They may not
+ appear before the first `--probe` or between a `--probe` and its matching
+`--expr`.
+*`--max-hit` scopes to the `--probe`/`--expr` pair it follows, so pairs
+ sharing a location may set different limits. `--cond` scopes to the whole
+ location, probes sharing a location must share one condition (or none).
 *`--timeout`, `--json`, `--preview`, and `--port` are global probe options
  for the whole probe session. They may appear before or between probe pairs,
  but not between a `--probe` and its matching `--expr`.
@@ -379,6 +389,7 @@ $ node inspect --json --probe cli.js:5 --expr 'rss' cli.js
 "suffix": "cli.js",
 "line": 5
  }
+// `condition` is present only when the probe was given a --cond expression.
 // `maxHit` is present only when the probe was given a --max-hit limit.
  }
  ],
@@ -480,6 +491,10 @@ When multiple `--probe`/`--expr` pairs share the same `--probe`, the
 expressions will be evaluated on the same pause in the order they appear
 on the command line.
 
+For each location, there can only be at most one `--cond` (or none).
+Multiple `--probe`/`--expr` pairs with conflicting conditions
+at the same location will be rejected at launch time.
+
 ```js
 // app.js
 constx= { x:42 }; // line 2
@@ -563,6 +578,37 @@ that only matches the intended file:
 $ node inspect --probe src/utils.js:10 --expr 'x' main.js # matches only src/utils.js
 ```
 
+### Probe examples
+
+#### Probing a variable conditionally
+
+```js
+// app.js
+let total =0;
+for (let i =0; i <10; i++) {
+ total += i; // line 4
+}
+```
+
+```console
+$ out/Release/node inspect --probe app.js:4 --expr 'total' \
+ --cond 'i % 3 === 0' app.js
+```
+
+```text
+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
+```
+
+<!-- TODO(joyeecheung): add more examples for different options -->
+
 ## Advanced usage
 
 ### V8 inspector integration for Node.js

lib/internal/debugger/inspect.js

@@ -268,6 +268,7 @@ function parseInteractiveArgs(args) {
 
 constkInspectArgOptions={
 '__proto__': null,
+'cond': {type: 'string'},
 'expr': {type: 'string'},
 'help': {type: 'boolean',short: 'h'},
 'json': {type: 'boolean'},

lib/internal/debugger/inspect_helpers.js

@@ -69,8 +69,8 @@ function writeInspectUsageAndExit(invokedAs, message, exitCode) {
 }
 out.write(`Usage: ${invokedAs} [--port=<port>] [<node-option> ...]
  [<script> [<script-args>] | <host>:<port> | -p <pid>]
-${invokedAs} --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
- [--probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>] ...]
+${invokedAs} --probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>]
+ [--probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>] ...]
  [--json] [--preview] [--timeout=<ms>] [--port=<port>]
  [--] [<node-option> ...] <script> [<script-args> ...]
 
@@ -109,6 +109,9 @@ Options:
  preceding --probe each time execution reaches it.
  Avoid probing let/const-bound variables at their
  declaration site or a ReferenceError may be thrown.
+ --cond <expr> Optional condition for the probe location. The probe only
+ records a hit when <expr> is truthy at the location. A
+ condition that throws is treated as false.
  --max-hit <n> Per-probe limit on evaluated hits. When not specified,
  there's no hit limit. When any probe reaches its hit LIMIT,
  the probing process will detach and report the results.
@@ -121,6 +124,9 @@ Options:
 Semantics:
 * Multiple --probe/--expr pairs are allowed. Same-location --probes share
  a pause and scope, their --exprs are evaluated in command-line order.
+* --max-hit scopes to one --probe/--expr pair, so same-location pairs may set
+ different limits. --cond scopes to the location, probes sharing a location
+ must all share one condition (or none).
 * --probe utils.js:<line>[:<col>] matches every loaded utils.js. Pass a
  fuller path e.g. src/utils.js to narrow the match.
 * Use -- before any Node.js flags intended for the child process.

lib/internal/debugger/inspect_probe.js

@@ -21,6 +21,7 @@ const {
  StringPrototypeIncludes,
  StringPrototypeSlice,
  StringPrototypeStartsWith,
+ StringPrototypeTrim,
  Symbol,
 }=primordials;
 
@@ -87,6 +88,8 @@ const kInspectPortRegex = /^--inspect-port=(\d+)$/;
  * @typedef {object} Probe
  * @property {string} expr Expression to evaluate on hit.
  * @property {ProbeTarget} target User's original --probe request shape.
+ * @property {string} [condition] Condition from --cond. V8 only breaks when it is truthy.
+ * Scoped to the location, so probes sharing a location all carry the same value.
  * @property {number} maxHit Per-probe hit limit from --max-hit. Infinity when unlimited.
  * @property {number} hits Count of hits observed.
  */
@@ -130,6 +133,12 @@ function formatTargetText(target) {
 returncolumn===undefined ? `${suffix}:${line}` : `${suffix}:${line}:${column}`;
 }
 
+// Identity of a probe location. Probes sharing a key share one V8 breakpoint,
+// so this must stay in sync between condition validation and breakpoint setup.
+functionlocationKey(target){
+return`${target.suffix}\n${target.line}\n${target.column??''}`;
+}
+
 functionformatPendingProbeLocations(probes,pending){
 constseen=newSafeSet();
 for(constprobeIndexofpending){
@@ -391,6 +400,22 @@ function parseProbeTokens(tokens, args) {
 probe.maxHit=parseUnsignedInteger(token.value,'max-hit');
 break;
 }
+case'cond': {
+if(probes.length===0){
+thrownewERR_DEBUGGER_STARTUP_ERROR('Unexpected --cond before --probe');
+}
+// A blank condition does not act as a real predicate in V8 (an empty
+// string always breaks), so reject it rather than silently mislead.
+if(token.value===undefined||StringPrototypeTrim(token.value)===''){
+thrownewERR_DEBUGGER_STARTUP_ERROR(`Missing value for ${token.rawName}`);
+}
+constprobe=probes[probes.length-1];
+if(probe.condition!==undefined){
+thrownewERR_DEBUGGER_STARTUP_ERROR('A --probe can have at most one --cond');
+}
+probe.condition=token.value;
+break;
+}
 default:
 if(probes.length>0){
 thrownewERR_DEBUGGER_STARTUP_ERROR(
@@ -410,6 +435,24 @@ function parseProbeTokens(tokens, args) {
 'Probe mode requires at least one --probe <loc> --expr <expr> group');
 }
 
+// V8 allows only one breakpoint per location, so probes sharing a location
+// cannot carry different conditions.
+constconditionByLocation=newSafeMap();
+for(const{ target, condition }ofprobes){
+constkey=locationKey(target);
+// All probes at the same location must share one condition. We split the
+// existence check since if one probe does not have a condition (= undefined),
+// then all probes at the location must also omit it.
+if(conditionByLocation.has(key)){
+if(conditionByLocation.get(key)!==condition){
+thrownewERR_DEBUGGER_STARTUP_ERROR(
+`Probes at ${formatTargetText(target)} must use the same --cond (or none)`);
+}
+}else{
+conditionByLocation.set(key,condition);
+}
+}
+
 constchildArgv=ArrayPrototypeSlice(args,childStartIndex);
 if(childArgv.length===0){
 thrownewERR_DEBUGGER_STARTUP_ERROR('Probe mode requires a child script');
@@ -479,8 +522,8 @@ class ProbeInspectorSession {
 this.resolveCompletion=resolve;
 /** @type {Probe[]} */
 this.probes=ArrayPrototypeMap(options.probes,
-({ expr, target, maxHit })=>
-({ expr, target,maxHit: maxHit??Infinity,hits: 0}));
+({ expr, target, maxHit, condition})=>
+({ expr, target,condition,maxHit: maxHit??Infinity,hits: 0}));
 this.onChildOutput=FunctionPrototypeBind(this.onChildOutput,this);
 this.onChildExit=FunctionPrototypeBind(this.onChildExit,this);
 this.onClientClose=FunctionPrototypeBind(this.onClientClose,this);
@@ -887,17 +930,19 @@ class ProbeInspectorSession {
 constuniqueTargets=newSafeMap();
 
 for(letprobeIndex=0;probeIndex<this.probes.length;probeIndex++){
-const{ target }=this.probes[probeIndex];
-constkey=`${target.suffix}\n${target.line}\n${target.column??''}`;
+const{ target, condition }=this.probes[probeIndex];
+// Probes at the same location share one V8 breakpoint. parseProbeTokens has
+// already ensured they carry the same condition.
+constkey=locationKey(target);
 letentry=uniqueTargets.get(key);
 if(entry===undefined){
-entry={ target,probeIndices: []};
+entry={ target,condition,probeIndices: []};
 uniqueTargets.set(key,entry);
 }
 ArrayPrototypePush(entry.probeIndices,probeIndex);
 }
 
-for(const{ target, probeIndices }ofuniqueTargets.values()){
+for(const{ target,condition,probeIndices }ofuniqueTargets.values()){
 // On Windows, normalize backslashes to forward slashes so the regex matches
 // V8 script URLs which always use forward slashes.
 constnormalizedFile=process.platform==='win32' ?
@@ -918,6 +963,9 @@ class ProbeInspectorSession {
 // the inspector bind to the first executable column.
 params.columnNumber=target.column-1;
 }
+if(condition!==undefined){
+params.condition=condition;
+}
 
 constresult=awaitthis.callCdp('Debugger.setBreakpointByUrl',params);
 debug('breakpoint set: id=%s urlRegex=%s locations=%j',
@@ -943,9 +991,10 @@ class ProbeInspectorSession {
 code: exitCode,
 report: {
 v: kProbeVersion,
-probes: ArrayPrototypeMap(this.probes,({ expr, target, maxHit })=>{
-// Omit an unlimited maxHit, as Infinity would serialize to null in JSON.
+probes: ArrayPrototypeMap(this.probes,({ expr, target, maxHit, condition })=>{
 constprobe={ expr, target };
+if(condition!==undefined){probe.condition=condition;}
+// Omit an unlimited maxHit, as Infinity would serialize to null in JSON.
 if(maxHit!==Infinity){probe.maxHit=maxHit;}
 returnprobe;
 }),

test/parallel/test-debugger-probe-cond-invalid.js

@@ -0,0 +1,40 @@
+// This tests that probe mode rejects malformed --cond usage.
+'use strict';
+
+constcommon=require('../common');
+common.skipIfInspectorDisabled();
+
+constfixtures=require('../common/fixtures');
+const{ assertProbeCliError }=require('../common/debugger-probe');
+
+constcwd=fixtures.path('debugger');
+
+assertProbeCliError(
+['--cond','x','--probe','probe.js:12','--expr','finalValue','probe.js'],
+/Unexpected--condbefore--probe/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--cond','x','--expr','finalValue','probe.js'],
+/Each--probemustbefollowedimmediatelyby--expr/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond','x','--cond','y','probe.js'],
+/A--probecanhaveatmostone--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond',' ','probe.js'],
+/Missingvaluefor--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond'],
+/Missingvaluefor--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','a','--cond','x',
+'--probe','probe.js:12','--expr','b','--cond','y','probe.js'],
+/Probesatprobe\.js:12mustusethesame--cond\(ornone\)/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','a','--cond','x',
+'--probe','probe.js:12','--expr','b','probe.js'],
+/Probesatprobe\.js:12mustusethesame--cond\(ornone\)/,{ cwd });

test/parallel/test-debugger-probe-cond-max-hit.js

@@ -0,0 +1,47 @@
+// This tests that --cond and --max-hit work together.
+'use strict';
+
+constcommon=require('../common');
+common.skipIfInspectorDisabled();
+
+constfixtures=require('../common/fixtures');
+const{ spawnSyncAndAssert }=require('../common/child_process');
+const{ assertProbeJson }=require('../common/debugger-probe');
+
+constcwd=fixtures.path('debugger');
+constprobeUrl=fixtures.fileURL('debugger','probe-max-hit.js').href;
+
+// --max-hit written before --cond. The condition still filters index !== 1, so
+// the only recorded hit carries value 1 rather than the loop's first iteration.
+spawnSyncAndAssert(process.execPath,[
+'inspect',
+'--json',
+'--probe','probe-max-hit.js:5',
+'--expr','index',
+'--max-hit','5',
+'--cond','index === 1',
+'probe-max-hit.js',
+],{ cwd },{
+stdout(output){
+assertProbeJson(output,{
+v: 2,
+probes: [{
+expr: 'index',
+condition: 'index === 1',
+maxHit: 5,
+target: {suffix: 'probe-max-hit.js',line: 5},
+}],
+results: [
+{
+probe: 0,
+event: 'hit',
+hit: 1,
+location: {url: probeUrl,line: 5,column: 3},
+result: {type: 'number',value: 1,description: '1'},
+},
+{event: 'completed'},
+],
+});
+},
+trim: true,
+});

doc/api/debugger.md

@@ -236,6 +236,10 @@ debug>
 added:
  - v24.16.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/64328
+ description: Add per-probe `--cond <expr>` option to only record a hit when the
+ condition is truthy at the probe location.
  - version: v24.19.0
  pr-url: https://github.com/nodejs/node/pull/63704
  description: Add per-probe `--max-hit <n>` option to limit evaluated hits and finish
@@ -268,8 +272,8 @@ printf-style debugging without having to modify the application code and
 clean up afterwards. It also supports structured JSON output for tool use.
 
 ```console
-$ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
- [--probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>] ...]
+$ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>]
+ [--probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>] ...]
  [--json] [--preview] [--timeout=<ms>] [--port=<port>]
  [--] [<node-option> ...] <script> [<script-args> ...]
 ```
@@ -282,6 +286,9 @@ $ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
 *`--expr <expr>`: JavaScript expression to evaluate whenever execution reaches
  the location specified by the preceding `--probe`.
  Must immediately follow the `--probe` it belongs to.
+*`--cond <expr>`: An optional condition for the probe location. The probe only
+ records a hit when `<expr>` is truthy at the location. A condition that throws
+ is treated as false.
 *`--max-hit <n>`: An optional per-probe limit on the number of times the probe
  can be hit. When not specified, there's no hit limit. When any probe reaches
  its hit limit, the probing process will detach and report the results. The process
@@ -297,14 +304,17 @@ $ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
  will listen. Defaults to `0`, which requests a random port.
 *`--` is optional unless the child needs its own Node.js flags.
 
-Additional rules about the `--probe` and `--expr` arguments:
+Additional rules about the composition of the options:
 
 *`--probe <file>:<line>[:<col>]` and `--expr <expr>` are strict pairs. Each
 `--probe` must be followed immediately by exactly one `--expr`.
-*`--max-hit <n>` is an optional per-probe option that applies to the most recent
-`--probe`/`--expr` pair. It may not appear before the first `--probe` or
- between a `--probe` and its matching `--expr`, and may be given at most once
- per probe.
+*`--cond <expr>` and `--max-hit <n>` are optional modifiers written _after_ the
+`--probe`/`--expr` pair they apply to, each at most once per pair. They may not
+ appear before the first `--probe` or between a `--probe` and its matching
+`--expr`.
+*`--max-hit` scopes to the `--probe`/`--expr` pair it follows, so pairs
+ sharing a location may set different limits. `--cond` scopes to the whole
+ location, probes sharing a location must share one condition (or none).
 *`--timeout`, `--json`, `--preview`, and `--port` are global probe options
  for the whole probe session. They may appear before or between probe pairs,
  but not between a `--probe` and its matching `--expr`.
@@ -379,6 +389,7 @@ $ node inspect --json --probe cli.js:5 --expr 'rss' cli.js
 "suffix": "cli.js",
 "line": 5
  }
+// `condition` is present only when the probe was given a --cond expression.
 // `maxHit` is present only when the probe was given a --max-hit limit.
  }
  ],
@@ -480,6 +491,10 @@ When multiple `--probe`/`--expr` pairs share the same `--probe`, the
 expressions will be evaluated on the same pause in the order they appear
 on the command line.
 
+For each location, there can only be at most one `--cond` (or none).
+Multiple `--probe`/`--expr` pairs with conflicting conditions
+at the same location will be rejected at launch time.
+
 ```js
 // app.js
 constx= { x:42 }; // line 2
@@ -563,6 +578,37 @@ that only matches the intended file:
 $ node inspect --probe src/utils.js:10 --expr 'x' main.js # matches only src/utils.js
 ```
 
+### Probe examples
+
+#### Probing a variable conditionally
+
+```js
+// app.js
+let total =0;
+for (let i =0; i <10; i++) {
+ total += i; // line 4
+}
+```
+
+```console
+$ out/Release/node inspect --probe app.js:4 --expr 'total' \
+ --cond 'i % 3 === 0' app.js
+```
+
+```text
+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
+```
+
+<!-- TODO(joyeecheung): add more examples for different options -->
+
 ## Advanced usage
 
 ### V8 inspector integration for Node.js

lib/internal/debugger/inspect.js

@@ -268,6 +268,7 @@ function parseInteractiveArgs(args) {
 
 constkInspectArgOptions={
 '__proto__': null,
+'cond': {type: 'string'},
 'expr': {type: 'string'},
 'help': {type: 'boolean',short: 'h'},
 'json': {type: 'boolean'},

lib/internal/debugger/inspect_helpers.js

@@ -69,8 +69,8 @@ function writeInspectUsageAndExit(invokedAs, message, exitCode) {
 }
 out.write(`Usage: ${invokedAs} [--port=<port>] [<node-option> ...]
  [<script> [<script-args>] | <host>:<port> | -p <pid>]
-${invokedAs} --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
- [--probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>] ...]
+${invokedAs} --probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>]
+ [--probe <file>:<line>[:<col>] --expr <expr> [--cond <expr>] [--max-hit <n>] ...]
  [--json] [--preview] [--timeout=<ms>] [--port=<port>]
  [--] [<node-option> ...] <script> [<script-args> ...]
 
@@ -109,6 +109,9 @@ Options:
  preceding --probe each time execution reaches it.
  Avoid probing let/const-bound variables at their
  declaration site or a ReferenceError may be thrown.
+ --cond <expr> Optional condition for the probe location. The probe only
+ records a hit when <expr> is truthy at the location. A
+ condition that throws is treated as false.
  --max-hit <n> Per-probe limit on evaluated hits. When not specified,
  there's no hit limit. When any probe reaches its hit LIMIT,
  the probing process will detach and report the results.
@@ -121,6 +124,9 @@ Options:
 Semantics:
 * Multiple --probe/--expr pairs are allowed. Same-location --probes share
  a pause and scope, their --exprs are evaluated in command-line order.
+* --max-hit scopes to one --probe/--expr pair, so same-location pairs may set
+ different limits. --cond scopes to the location, probes sharing a location
+ must all share one condition (or none).
 * --probe utils.js:<line>[:<col>] matches every loaded utils.js. Pass a
  fuller path e.g. src/utils.js to narrow the match.
 * Use -- before any Node.js flags intended for the child process.

lib/internal/debugger/inspect_probe.js

@@ -21,6 +21,7 @@ const {
  StringPrototypeIncludes,
  StringPrototypeSlice,
  StringPrototypeStartsWith,
+ StringPrototypeTrim,
  Symbol,
 }=primordials;
 
@@ -87,6 +88,8 @@ const kInspectPortRegex = /^--inspect-port=(\d+)$/;
  * @typedef {object} Probe
  * @property {string} expr Expression to evaluate on hit.
  * @property {ProbeTarget} target User's original --probe request shape.
+ * @property {string} [condition] Condition from --cond. V8 only breaks when it is truthy.
+ * Scoped to the location, so probes sharing a location all carry the same value.
  * @property {number} maxHit Per-probe hit limit from --max-hit. Infinity when unlimited.
  * @property {number} hits Count of hits observed.
  */
@@ -130,6 +133,12 @@ function formatTargetText(target) {
 returncolumn===undefined ? `${suffix}:${line}` : `${suffix}:${line}:${column}`;
 }
 
+// Identity of a probe location. Probes sharing a key share one V8 breakpoint,
+// so this must stay in sync between condition validation and breakpoint setup.
+functionlocationKey(target){
+return`${target.suffix}\n${target.line}\n${target.column??''}`;
+}
+
 functionformatPendingProbeLocations(probes,pending){
 constseen=newSafeSet();
 for(constprobeIndexofpending){
@@ -391,6 +400,22 @@ function parseProbeTokens(tokens, args) {
 probe.maxHit=parseUnsignedInteger(token.value,'max-hit');
 break;
 }
+case'cond': {
+if(probes.length===0){
+thrownewERR_DEBUGGER_STARTUP_ERROR('Unexpected --cond before --probe');
+}
+// A blank condition does not act as a real predicate in V8 (an empty
+// string always breaks), so reject it rather than silently mislead.
+if(token.value===undefined||StringPrototypeTrim(token.value)===''){
+thrownewERR_DEBUGGER_STARTUP_ERROR(`Missing value for ${token.rawName}`);
+}
+constprobe=probes[probes.length-1];
+if(probe.condition!==undefined){
+thrownewERR_DEBUGGER_STARTUP_ERROR('A --probe can have at most one --cond');
+}
+probe.condition=token.value;
+break;
+}
 default:
 if(probes.length>0){
 thrownewERR_DEBUGGER_STARTUP_ERROR(
@@ -410,6 +435,24 @@ function parseProbeTokens(tokens, args) {
 'Probe mode requires at least one --probe <loc> --expr <expr> group');
 }
 
+// V8 allows only one breakpoint per location, so probes sharing a location
+// cannot carry different conditions.
+constconditionByLocation=newSafeMap();
+for(const{ target, condition }ofprobes){
+constkey=locationKey(target);
+// All probes at the same location must share one condition. We split the
+// existence check since if one probe does not have a condition (= undefined),
+// then all probes at the location must also omit it.
+if(conditionByLocation.has(key)){
+if(conditionByLocation.get(key)!==condition){
+thrownewERR_DEBUGGER_STARTUP_ERROR(
+`Probes at ${formatTargetText(target)} must use the same --cond (or none)`);
+}
+}else{
+conditionByLocation.set(key,condition);
+}
+}
+
 constchildArgv=ArrayPrototypeSlice(args,childStartIndex);
 if(childArgv.length===0){
 thrownewERR_DEBUGGER_STARTUP_ERROR('Probe mode requires a child script');
@@ -479,8 +522,8 @@ class ProbeInspectorSession {
 this.resolveCompletion=resolve;
 /** @type {Probe[]} */
 this.probes=ArrayPrototypeMap(options.probes,
-({ expr, target, maxHit })=>
-({ expr, target,maxHit: maxHit??Infinity,hits: 0}));
+({ expr, target, maxHit, condition})=>
+({ expr, target,condition,maxHit: maxHit??Infinity,hits: 0}));
 this.onChildOutput=FunctionPrototypeBind(this.onChildOutput,this);
 this.onChildExit=FunctionPrototypeBind(this.onChildExit,this);
 this.onClientClose=FunctionPrototypeBind(this.onClientClose,this);
@@ -887,17 +930,19 @@ class ProbeInspectorSession {
 constuniqueTargets=newSafeMap();
 
 for(letprobeIndex=0;probeIndex<this.probes.length;probeIndex++){
-const{ target }=this.probes[probeIndex];
-constkey=`${target.suffix}\n${target.line}\n${target.column??''}`;
+const{ target, condition }=this.probes[probeIndex];
+// Probes at the same location share one V8 breakpoint. parseProbeTokens has
+// already ensured they carry the same condition.
+constkey=locationKey(target);
 letentry=uniqueTargets.get(key);
 if(entry===undefined){
-entry={ target,probeIndices: []};
+entry={ target,condition,probeIndices: []};
 uniqueTargets.set(key,entry);
 }
 ArrayPrototypePush(entry.probeIndices,probeIndex);
 }
 
-for(const{ target, probeIndices }ofuniqueTargets.values()){
+for(const{ target,condition,probeIndices }ofuniqueTargets.values()){
 // On Windows, normalize backslashes to forward slashes so the regex matches
 // V8 script URLs which always use forward slashes.
 constnormalizedFile=process.platform==='win32' ?
@@ -918,6 +963,9 @@ class ProbeInspectorSession {
 // the inspector bind to the first executable column.
 params.columnNumber=target.column-1;
 }
+if(condition!==undefined){
+params.condition=condition;
+}
 
 constresult=awaitthis.callCdp('Debugger.setBreakpointByUrl',params);
 debug('breakpoint set: id=%s urlRegex=%s locations=%j',
@@ -943,9 +991,10 @@ class ProbeInspectorSession {
 code: exitCode,
 report: {
 v: kProbeVersion,
-probes: ArrayPrototypeMap(this.probes,({ expr, target, maxHit })=>{
-// Omit an unlimited maxHit, as Infinity would serialize to null in JSON.
+probes: ArrayPrototypeMap(this.probes,({ expr, target, maxHit, condition })=>{
 constprobe={ expr, target };
+if(condition!==undefined){probe.condition=condition;}
+// Omit an unlimited maxHit, as Infinity would serialize to null in JSON.
 if(maxHit!==Infinity){probe.maxHit=maxHit;}
 returnprobe;
 }),

test/parallel/test-debugger-probe-cond-invalid.js

@@ -0,0 +1,40 @@
+// This tests that probe mode rejects malformed --cond usage.
+'use strict';
+
+constcommon=require('../common');
+common.skipIfInspectorDisabled();
+
+constfixtures=require('../common/fixtures');
+const{ assertProbeCliError }=require('../common/debugger-probe');
+
+constcwd=fixtures.path('debugger');
+
+assertProbeCliError(
+['--cond','x','--probe','probe.js:12','--expr','finalValue','probe.js'],
+/Unexpected--condbefore--probe/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--cond','x','--expr','finalValue','probe.js'],
+/Each--probemustbefollowedimmediatelyby--expr/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond','x','--cond','y','probe.js'],
+/A--probecanhaveatmostone--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond',' ','probe.js'],
+/Missingvaluefor--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','finalValue','--cond'],
+/Missingvaluefor--cond/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','a','--cond','x',
+'--probe','probe.js:12','--expr','b','--cond','y','probe.js'],
+/Probesatprobe\.js:12mustusethesame--cond\(ornone\)/,{ cwd });
+
+assertProbeCliError(
+['--probe','probe.js:12','--expr','a','--cond','x',
+'--probe','probe.js:12','--expr','b','probe.js'],
+/Probesatprobe\.js:12mustusethesame--cond\(ornone\)/,{ cwd });

test/parallel/test-debugger-probe-cond-max-hit.js

@@ -0,0 +1,47 @@
+// This tests that --cond and --max-hit work together.
+'use strict';
+
+constcommon=require('../common');
+common.skipIfInspectorDisabled();
+
+constfixtures=require('../common/fixtures');
+const{ spawnSyncAndAssert }=require('../common/child_process');
+const{ assertProbeJson }=require('../common/debugger-probe');
+
+constcwd=fixtures.path('debugger');
+constprobeUrl=fixtures.fileURL('debugger','probe-max-hit.js').href;
+
+// --max-hit written before --cond. The condition still filters index !== 1, so
+// the only recorded hit carries value 1 rather than the loop's first iteration.
+spawnSyncAndAssert(process.execPath,[
+'inspect',
+'--json',
+'--probe','probe-max-hit.js:5',
+'--expr','index',
+'--max-hit','5',
+'--cond','index === 1',
+'probe-max-hit.js',
+],{ cwd },{
+stdout(output){
+assertProbeJson(output,{
+v: 2,
+probes: [{
+expr: 'index',
+condition: 'index === 1',
+maxHit: 5,
+target: {suffix: 'probe-max-hit.js',line: 5},
+}],
+results: [
+{
+probe: 0,
+event: 'hit',
+hit: 1,
+location: {url: probeUrl,line: 5,column: 3},
+result: {type: 'number',value: 1,description: '1'},
+},
+{event: 'completed'},
+],
+});
+},
+trim: true,
+});