Skip to content

Commit a4e8c05

Browse files
committed
debugger: add edit-free runtime expression probes to node inspect
Add a non-interactive probe mode to `node inspect` for inspecting runtime values in a run-to-completion application. This allows users to perform printf-style debugging without having to modify the application code and clean up afterwards, it also supports structured output to be consumed by tools. Probe mode launches the application, sets one or more source breakpoints, evaluates one expression at each hit, and prints a single text or JSON report when execution ends. Interface: node inspect [--json] [--preview] [--timeout=<ms>] [--port=<port>] --probe <file>:<line>[:<col>] --expr <expr> ... [--] <script> [args...] Example: ```js // cli.js const date = new Date(); const str = date.toLocaleDateString(); const result = str.length; ``` ``` $ node inspect --probe cli.js:4 --expr 'str' cli.js Hit 1 at cli.js:4 str = "4/12/2026" Completed ``` (Prettified JSON to fit in commit message restrictions). ```js $ node inspect --json --probe cli.js:4 --expr 'str' cli.js { "v": 1, "probes": [ { "expr": "str", "target": [ "cli.js", 4 ] } ], "results": [ { "probe": 0, "event": "hit", "hit": 1, "result": { "type": "string", "value": "4/12/2026" } }, { "event": "completed" } ] } ```
1 parent dfe438d commit a4e8c05

25 files changed

+1755
-25
lines changed

doc/api/debugger.md

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,144 @@ steps to the next line. Type `help` to see what other commands are available.
9090
Pressing `enter` without typing a command will repeat the previous debugger
9191
command.
9292

93+
## Probe mode
94+
95+
<!-- YAML
96+
added:
97+
- REPLACEME
98+
-->
99+
100+
> Stability: 1 - Experimental
101+
102+
`node inspect` supports a non-interactive probe mode for inspecting
103+
runtime values in a run-to-completion application. Probe mode launches the application,
104+
sets one or more source breakpoints, evaluates one expression
105+
whenever a matching breakpoint is hit, and prints one final report when the
106+
session ends (either on normal completion or timeout). This allows users to
107+
perform printf-style debugging without having to modify the application code and
108+
clean up afterwards, and it supports structured output for tool use.
109+
110+
```console
111+
$ node inspect [--json] [--preview] [--timeout=<ms>] [--port=<port>] \
112+
--probe app.js:10 --expr 'x' \
113+
[--probe app.js:20 --expr 'y' ...] \
114+
[--] [<node-option> ...] <script.js> [args...]
115+
```
116+
117+
* `--probe <file>:<line>[:<col>]`: Source location to probe. Line and column number
118+
are 1-based.
119+
* `--timeout=<ms>`: A global wall-clock deadline for the entire probe session.
120+
The default is `30000`. This can be used to probe a long-running application
121+
that can be terminated externally.
122+
* `--json`: If used, prints a structured JSON report instead of the default text report.
123+
* `--preview`: If used, non-primitive values will include CDP property previews for
124+
object-like JSON probe values.
125+
* `--port=<port>`: Selects the local inspector port used for the `--inspect-brk`
126+
launch path. Probe mode defaults to `0`, which requests a random port.
127+
* `--` is optional unless the child needs its own Node.js flags.
128+
129+
Additional rules about the `--probe` and `--expr` arguments:
130+
131+
* `--probe <file>:<line>[:<col>]` and `--expr <expr>` are strict pairs. Each
132+
`--probe` must be followed immediately by exactly one `--expr`.
133+
* `--timeout`, `--json`, `--preview`, and `--port` are global probe options
134+
for the whole probe session. They may appear before or between probe pairs,
135+
but not between a `--probe` and its matching `--expr`.
136+
137+
If a single probe needs to evaluate more than one value,
138+
evaluate a structured value in `--expr`, for example `--expr "{ foo, bar }"`
139+
or `--expr "[foo, bar]"`, and use `--preview` to include property previews for
140+
any object-like values in the output.
141+
142+
Probe mode only prints the final probe report to stdout, and otherwise silences
143+
stdout/stderr from the child process. If the child exits with an error after the
144+
probe session starts, the final report records a terminal `error` event with the
145+
exit code and captured child stderr. Invalid arguments and fatal launch or
146+
connect failures may still print diagnostics to stderr without a final probe
147+
result.
148+
149+
Consider this script:
150+
151+
```js
152+
// cli.js
153+
const date = new Date();
154+
const str = date.toLocaleDateString();
155+
const result = str.length;
156+
```
157+
158+
If `--json` is not used, the output is printed in a human-readable text format:
159+
160+
```console
161+
$ node inspect --probe cli.js:4 --expr 'str' cli.js
162+
Hit 1 at cli.js:4
163+
str = "4/12/2026"
164+
Completed
165+
```
166+
167+
Primitive results are printed directly, while objects and arrays use Chrome
168+
DevTools Protocol preview data when available. Other non-primitive values
169+
fall back to the Chrome DevTools Protocol `description` string.
170+
Expression failures are recorded as `[error] ...` lines and do not fail
171+
the overall session. If richer text formatting is needed, wrap the expression
172+
in `JSON.stringify(...)` or `util.inspect(...)`.
173+
174+
When `--json` is used, the output shape looks like this:
175+
176+
```console
177+
$ node inspect --json --probe cli.js:4 --expr 'str' cli.js
178+
{"v":1,"probes":[{"expr":"str","target":["cli.js",4]}],"results":[{"probe":0,"event":"hit","hit":1,"result":{"type":"string","value":"4/12/2026"}},{"event":"completed"}]}
179+
```
180+
181+
```json
182+
{
183+
"v": 1, // Probe JSON schema version.
184+
"probes": [
185+
{
186+
"expr": "str", // The expression paired with --probe.
187+
"target": ["cli.js", 4] // [file, line] or [file, line, col].
188+
}
189+
],
190+
"results": [
191+
{
192+
"probe": 0, // Index into probes[].
193+
"event": "hit", // Hit events are recorded in observation order.
194+
"hit": 1, // 1-based hit count for this probe.
195+
"result": {
196+
"type": "string",
197+
"value": "4/12/2026"
198+
// Object-like values may also include "description".
199+
// Pass --preview to also include abbreviated "preview" payloads.
200+
}
201+
// If the expression throws, "error" is present instead of "result".
202+
},
203+
{
204+
"event": "completed"
205+
// The final entry is always a terminal event, for example:
206+
// 1. { "event": "completed" }
207+
// 2. { "event": "miss", "pending": [0, 1] }
208+
// 3. {
209+
// "event": "timeout",
210+
// "pending": [0],
211+
// "error": {
212+
// "code": "probe_timeout",
213+
// "message": "Timed out after 30000ms waiting for probes: app.js:10"
214+
// }
215+
// }
216+
// 4. {
217+
// "event": "error",
218+
// "pending": [0],
219+
// "error": {
220+
// "code": "probe_target_exit",
221+
// "exitCode": 1,
222+
// "stderr": "[Error: boom]",
223+
// "message": "Target exited with code 1 before probes: app.js:10"
224+
// }
225+
// }
226+
}
227+
]
228+
}
229+
```
230+
93231
## Watchers
94232

95233
It is possible to watch expression and variable values while debugging. On

0 commit comments

Comments
 (0)