debugger: add edit-free runtime expression probes to `node inspect` by joyeecheung · Pull Request #62713 · nodejs/node

joyeecheung · 2026-04-12T22:21:34Z

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.

This is proposed to be experimental first, so that we can iterate on the interface. There are a few features that would be nice to have but better left for follow-ups to avoid bloating the diff:

Source map support - which will allow developers to get a trace of ad-hoc interesting values without having to rebuild their apps
Attaching to a running process with inspector listening on a port - so it can be used to print a trace of ad-hoc interesting values from a local dev server without having to restart it

In this patch, 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 containing all the evaluated values when execution ends.

Interface:

node inspect [--json] [--preview] [--timeout=<ms>] [--port=<port>]
  --probe <file>:<line>[:<col>] --expr <expr> ...
  [--] <script> [args...]

For example, to inspect a string in an application without modifying the source:

// cli.js
let maxRSS = 0;
for (let i = 0; i < 2; i++) {
  const { rss } = process.memoryUsage();
  maxRSS = Math.max(maxRSS, rss);
}

$ node inspect --probe cli.js:5 --expr 'rss' cli.js
Hit 1 at cli.js:5
  rss = 54935552
Hit 2 at cli.js:5
  rss = 55083008
Completed

(Prettified JSON to fit in commit message restrictions).

$ node inspect --json --probe cli.js:5 --expr 'rss' cli.js
{"v":1,"probes":[{"expr":"rss","target":["cli.js",5]}],
"results":[
  {"probe":0,"event":"hit","hit":1,
   "result":{"type":"number","value":55443456,
             "description":"55443456"}},
  {"probe":0,"event":"hit","hit":2,
   "result":{"type":"number","value":55574528,
             "description":"55574528"}},
  {"event":"completed"}]}

joyeecheung · 2026-04-12T22:36:47Z

cc @nodejs/inspector @nodejs/diagnostics

Add a non-interactive probe mode to `node inspect` for inspecting runtime values in a run-to-completion application. This allows users to perform printf-style debugging without having to modify the application code and clean up afterwards, it also supports structured output to be consumed by tools. Probe mode launches the application, sets one or more source breakpoints, evaluates one expression at each hit, and prints a single text or JSON report when execution ends. Interface: node inspect [--json] [--preview] [--timeout=<ms>] [--port=<port>] --probe <file>:<line>[:<col>] --expr <expr> ... [--] <script> [args...] Example: ```js // cli.js let maxRSS = 0; for (let i = 0; i < 2; i++) { const { rss } = process.memoryUsage(); maxRSS = Math.max(maxRSS, rss); } ``` ``` $ node inspect --probe cli.js:5 --expr 'rss' cli.js Hit 1 at cli.js:5 rss = 54935552 Hit 2 at cli.js:5 rss = 55083008 Completed ``` (Prettified JSON to fit in commit message restrictions). ```js $ node inspect --json --probe cli.js:5 --expr 'rss' cli.js {"v":1,"probes":[{"expr":"rss","target":["cli.js",5]}], "results":[ {"probe":0,"event":"hit","hit":1, "result":{"type":"number","value":55443456, "description":"55443456"}}, {"probe":0,"event":"hit","hit":2, "result":{"type":"number","value":55574528, "description":"55574528"}}, {"event":"completed"}]} ``` Signed-off-by: Joyee Cheung <joyeec9h3@gmail.com>

codecov · 2026-04-13T02:05:30Z

Codecov Report

❌ Patch coverage is 78.50467% with 184 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.73%. Comparing base (dfe438d) to head (4278d22).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/debugger/inspect.js	78.06%	179 Missing and 5 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #62713      +/-   ##
==========================================
- Coverage   89.81%   89.73%   -0.08%     
==========================================
  Files         699      699              
  Lines      216379   217210     +831     
  Branches    41366    41557     +191     
==========================================
+ Hits       194340   194922     +582     
- Misses      14139    14368     +229     
- Partials     7900     7920      +20

Files with missing lines	Coverage Δ
lib/internal/debugger/inspect_client.js	`87.94% <100.00%> (+0.37%)`	⬆️
lib/internal/errors.js	`97.63% <100.00%> (+<0.01%)`	⬆️
lib/internal/debugger/inspect.js	`82.51% <78.06%> (-11.43%)`	⬇️

... and 29 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

hybrist · 2026-04-14T20:05:53Z

test/parallel/test-debugger-probe-activation.js

+  '--json',
+  '--preview',
+  '--timeout=1',
+  '--expr',


I'm not sure what this tests in relation to the probes. Shouldn't it fail because --expr is passed without any probe location? The test below appears to only test the exec command and not involve the value expression..?

hybrist · 2026-04-14T20:10:58Z

lib/internal/debugger/inspect.js

+// Parse from right to left to allow Windows paths with drive letters.
+// Accepts file:line or file:line:column formats.
+function parseProbeLocation(text) {
+  const lastColon = StringPrototypeLastIndexOf(text, ':');


It feels like using a single regex for the entire text would be easier to read here. But I don't have super strong opitions.

hybrist · 2026-04-14T20:11:56Z

lib/internal/debugger/inspect.js

+}
+
+function formatProbeTuple(tuple) {
+  return ArrayPrototypeJoin(ArrayPrototypeMap(tuple, (part) => `${part}`), ':');


Does the map really do anything here? I assume all elements are primitives that would be converted to strings by join already?

hybrist · 2026-04-14T20:12:59Z

lib/internal/debugger/inspect.js

+
+function formatPendingProbeLocations(probes, pending) {
+  const seen = new SafeSet();
+  const names = [];


Isn't this redundant with seen? Should we just Array.from(seen) at the end?

hybrist · 2026-04-14T20:16:11Z

lib/internal/debugger/inspect.js

+  }
+}
+
+async function runScript(script, scriptArgs, inspectHost, inspectPort,


Since this only has one call site, should we just update that call to match the launchChildProcess signature instead of having this wrapper function?

hybrist · 2026-04-14T20:17:10Z

This is really cool! Have we considered to use new line delimited JSON instead of a big JSON array as the primary output format?

nodejs-github-bot added debugger Issues and PRs related to the debugger subsystem. errors Issues and PRs related to JavaScript errors originated in Node.js core. needs-ci PRs that need a full CI run. labels Apr 12, 2026

joyeecheung added the semver-minor PRs that contain new features and should be released in the next minor version. label Apr 12, 2026

joyeecheung force-pushed the probe-eval branch from a4e8c05 to 4341960 Compare April 12, 2026 22:36

joyeecheung force-pushed the probe-eval branch 4 times, most recently from 3608c5d to b0ec4b2 Compare April 12, 2026 23:56

joyeecheung force-pushed the probe-eval branch from b0ec4b2 to 4278d22 Compare April 13, 2026 00:42

hybrist reviewed Apr 14, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

debugger: add edit-free runtime expression probes to `node inspect`#62713

debugger: add edit-free runtime expression probes to `node inspect`#62713
joyeecheung wants to merge 1 commit intonodejs:mainfrom
joyeecheung:probe-eval

joyeecheung commented Apr 12, 2026 •

edited

Loading

Uh oh!

joyeecheung commented Apr 12, 2026

Uh oh!

codecov bot commented Apr 13, 2026 •

edited

Loading

Uh oh!

hybrist Apr 14, 2026

Uh oh!

hybrist Apr 14, 2026

Uh oh!

hybrist Apr 14, 2026

Uh oh!

hybrist Apr 14, 2026

Uh oh!

hybrist Apr 14, 2026

Uh oh!

hybrist commented Apr 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

joyeecheung commented Apr 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

joyeecheung commented Apr 12, 2026

Uh oh!

codecov bot commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

hybrist Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

hybrist Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

hybrist Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

hybrist Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

hybrist Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

hybrist commented Apr 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

joyeecheung commented Apr 12, 2026 •

edited

Loading

codecov bot commented Apr 13, 2026 •

edited

Loading