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

[joyeecheung]

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]

cc @nodejs/inspector @nodejs/diagnostics

[codecov]

Codecov Report

❌ Patch coverage is 79.22236% with 171 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.64%. Comparing base (dfe438d) to head (512ca16).
⚠️ Report is 20 commits behind head on main.

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

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #62713      +/-   ##
==========================================
- Coverage   89.81%   89.64%   -0.17%     
==========================================
  Files         699      706       +7     
  Lines      216379   218922    +2543     
  Branches    41366    41921     +555     
==========================================
+ Hits       194340   196261    +1921     
- Misses      14139    14562     +423     
- Partials     7900     8099     +199     

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	83.09% <78.78%> (-10.84%)	⬇️

... and 50 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]

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..?

[joyeecheung]

It's testing that without --probe, it won't enter probe mode even if --expr and friends are passed (i.e. they are going to be ignored and captured in process.argv for user land parsing) to be somewhat compatible to the old behavior. Not sure if it's over thinking a bit here though, maybe people don't inject these arguments for scripts debugged by node inspect enough to be broken? Other seems rare but --json or --timeout might not be. I can't imagine anyone having production code broken by change of interpretation of --probe in node inspect (not even our tests would care) , but for others better to stay on the safe side.

Alternatively we can also error, but I feel that it might be a bit too strict, also could potentially break someone.

[joyeecheung]

Added more comments to explain that it's testing script arguments.

[hybrist]

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

[joyeecheung]

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

I feel that since we already have the text format for more readable output, the JSON format can be a bit more condensed since it's meant to be consumed by tools anyway? Using new-line delimited JSON would kind of force tools to be able to deal with that instead of just parsing it directly, and also not sure where the version field should go in that case, if we want to reuse the probes (because many hits can come from the same probe) they have to maintain some states to collect the probes first then collect the events, which means the tools all have to add specialized state management to parse it instead of just using whatever JSON parser they have.