inspector: support for worker inspection in chrome devtools #56759

islandryu · 2025-01-25T13:31:05Z

This PR introduces support for inspecting workers in Chrome DevTools. I would like to gather some feedback to confirm whether there seem to be no issues with this approach. If the approach in this PR deviates significantly from the desired direction, I am happy to close it. However, if the general approach seems acceptable, I will proceed with this PR and submit a change request to Chrome DevTools.

Summary of Changes

This implementation uses the attachedToTarget event to notify the creation of workers. More details on the protocol can be found [here](https://chromedevtools.github.io/devtools-protocol/tot/Target/#event-attachedToTarget).

This sequence is how to worker inspection works.
When a worker is created, attachedToTarget is notified to the server, and the server thread allocates methods from the client to the appropriate thread based on the sessionId.

sequenceDiagram
    participant DevtoolClient as DevTool Client
    participant ServerThread as Server Thread
    participant MainThread as Main Thread
    participant WorkerThread as Worker Thread

    DevtoolClient ->> ServerThread: attach
    ServerThread ->> MainThread: attach

    MainThread ->> MainThread: execute program

    MainThread ->> WorkerThread: create worker

    MainThread ->> ServerThread: attachedToTarget
    ServerThread ->> DevtoolClient: attachedToTarget

    DevtoolClient ->> ServerThread: debugger method
    ServerThread ->> ServerThread: Check which thread to send to by sessionId
    ServerThread ->> WorkerThread: Send to main thread or worker thread

How to Verify

Currently, dedicated DevTools for Node.js do not support worker targets. For verification, use inspector.html:

devtools://devtools/bundled/inspector.html?ws=127.0.0.1:9229/(sessionId)

Steps:

Start the Node.js process with the following command:

node --inspect-brk --experimental-worker-inspection index.js

Use the following index.js and worker.js files for testing:

index.js:

const { Worker } = require('worker_threads');
const workerPath =  __dirname + '/worker.js';
const worker = new Worker(workerPath);

worker.js:

console.log("worker thread");
process.on('exit', () => {
  console.log('Worker1: Exiting...');
});

~~Currently, the results of console.log within the worker are being sent twice, but I'm working on fixing this issue.~~

Additional Information

The approach used in this PR follows the CDP (Chrome DevTools Protocol) and is different from the Node.js worker debugging protocol used in VSCode. It adheres to the existing CDP protocol to ensure compatibility.

fix #56343

nodejs-github-bot · 2025-01-25T13:31:11Z

Review requested:

@nodejs/gyp
@nodejs/inspector

lpinca · 2025-01-25T19:49:23Z

test/parallel/test-inspector-worker-target.js

+  }));
+}
+
+test().then(common.mustCall());


I think the test() function wrapper is no longer needed: by default, an unhandled promise rejection makes the process exit with a non-zero exit code.

Thank you.
I removed the wrapper.

Sorry for the previous comment. The promise.then(common.mustCall()) pattern is still needed to handle the case where the process exits with the promise unsettled.

Ah, got it — I’ll bring it back.

legendecas · 2025-01-26T15:04:06Z

Tracing the history discussion, it would be great to have @eugeneo, @pavelfeldman and @dgozman weighing in this work

legendecas · 2025-01-29T13:52:02Z

Confirmed with Chrome DevTools team (dsv@, caseq@) that they are good with Node.js implementing the Target domain for worker discovery, or implementing NodeWorker domain support in Chrome DevTools frontend.

As the Target domain in this PR is behind the flag --experimental-worker-inspection, I believe it is fine to go ahead. Thank you for working on this!

islandryu · 2025-01-29T16:46:02Z

Confirmed with Chrome DevTools team (dsv@, caseq@) that they are good with Node.js implementing the Target domain for worker discovery, or implementing NodeWorker domain support in Chrome DevTools frontend.

As the Target domain in this PR is behind the flag --experimental-worker-inspection, I believe it is fine to go ahead. Thank you for working on this!

Thank you!
I'll resolve the conflicts, make a few minor fixes, and then open the PR.

Fixes: nodejs#56343

codecov · 2025-01-30T15:09:35Z

Codecov Report

Attention: Patch coverage is 94.07895% with 9 lines in your changes missing coverage. Please review.

Project coverage is 90.26%. Comparing base (0edeafd) to head (5c31756).
Report is 633 commits behind head on main.

Files with missing lines	Patch %	Lines
src/inspector/target_agent.cc	95.83%	0 Missing and 3 partials ⚠️
src/inspector_agent.cc	88.00%	0 Missing and 3 partials ⚠️
src/inspector_io.cc	93.18%	0 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #56759      +/-   ##
==========================================
+ Coverage   89.21%   90.26%   +1.05%     
==========================================
  Files         663      632      -31     
  Lines      192001   186021    -5980     
  Branches    36923    36442     -481     
==========================================
- Hits       171290   167914    -3376     
+ Misses      13582    10984    -2598     
+ Partials     7129     7123       -6

Files with missing lines	Coverage Δ
src/inspector/main_thread_interface.h	`95.00% <100.00%> (+1.66%)`	⬆️
src/inspector/target_agent.h	`100.00% <100.00%> (ø)`
src/node_options.cc	`85.25% <ø> (-2.71%)`	⬇️
src/node_options.h	`98.89% <100.00%> (+0.56%)`	⬆️
src/inspector/target_agent.cc	`95.83% <95.83%> (ø)`
src/inspector_agent.cc	`79.58% <88.00%> (-0.16%)`	⬇️
src/inspector_io.cc	`92.56% <93.18%> (-0.02%)`	⬇️

... and 281 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.

islandryu · 2025-02-03T13:11:42Z

Issue to devtools-frontend
https://issues.chromium.org/issues/393746702

legendecas · 2025-02-04T10:57:06Z

test/parallel/test-inspector-worker-target.js

+  const sessionId = '1';
+  await session.waitForNotification('Target.targetCreated');
+  await session.waitForNotification((notification) => {
+    return notification.method === 'Target.attachedToTarget' &&


Event Target.attachedToTarget should not be emitted without a Target.setAutoAttach command or Target.attachToTarget command.

islandryu · 2025-02-08T11:19:26Z

src/inspector/target_agent.cc

+// TODO(islandryu): Currently, setAutoAttach applies the main thread's value to
+// all threads. Modify it to be managed per worker thread.
+crdtp::DispatchResponse TargetAgent::setAutoAttach(
+    bool auto_attach, bool wait_for_debugger_on_start) {
+  auto_attach_ = auto_attach;
+  wait_for_debugger_on_start_ = wait_for_debugger_on_start;
+
+  if (auto_attach) {
+    for (auto& target : targets_) {
+      if (!target.attached) {
+        target.attached = true;
+        attachedToTarget(target.worker,
+                         target.target_id,
+                         target.type,
+                         target.title,
+                         target.url);
+      }
+    }
+  }


setAutoAttach is implemented.
However, I am not able to determine autoAttach for each related Target and waitForDebuggerOnStart.
I have tried several way, but it was difficult to make the changes without affecting the existing nodeWorker, so I would like to make a TODO.

doc/api/cli.md

RafaelGSS · 2025-03-28T18:23:55Z

test/parallel/test-inspector-worker-target.js

+  );
+
+
+  const session = await child.connectInspectorSession();


Can you add another suite to guarantee this command will fail when --permission is used?

I added it below.

Co-authored-by: Rafael Gonzaga <rafael.nunu@hotmail.com>

src/inspector/target_agent.h

src/inspector_agent.cc

Co-authored-by: James M Snell <jasnell@gmail.com>

legendecas

Thank you for working on this! This will need change in the Chrome DevTools Frontend code as well: https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/core/sdk/ChildTargetManager.ts;l=143-188?q=ChildTargetManager.ts

Would you like to draft the change as well? Otherwise I can help with the work to land the change in devtools-frontend.

src/inspector/node_inspector.gypi

legendecas · 2025-04-15T09:47:22Z

src/inspector/target_agent.cc

+    const std::string& title,
+    const std::string& url) {
+  std::string target_id = std::to_string(getNextTargetId());
+  std::string type = "worker";


This type conflicts with the web worker type in https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/core/sdk/ChildTargetManager.ts;l=176?q=ChildTargetManager.ts

If devtools-frontend recognize Node.js worker as a web worker, it will fail to attach to this target as Node.js does not support all domains supported by a web worker.

Would you like to draft the change as well? Otherwise I can help with the work to land the change in devtools-frontend.

Thx, I have prepared a draft on my end.
https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/6218804

For now, I named the new type node_worker.

Co-authored-by: Chengzhong Wu <legendecas@gmail.com>

nodejs-github-bot · 2025-04-23T09:34:47Z

CI: https://ci.nodejs.org/job/node-test-pull-request/66425/

nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels Jan 25, 2025

lpinca reviewed Jan 25, 2025

View reviewed changes

legendecas added the inspector Issues and PRs related to the V8 inspector protocol label Jan 29, 2025

legendecas linked an issue Jan 29, 2025 that may be closed by this pull request

Debug worker_threads #26609

Open

islandryu added 2 commits January 30, 2025 15:44

inspector: support for worker inspection in chrome devtools

525a2d2

Fixes: nodejs#56343

fix/test

cab3f96

islandryu force-pushed the feat/cdpTarget branch from 141ec5a to 984f640 Compare January 30, 2025 10:04

format

fafadd0

islandryu force-pushed the feat/cdpTarget branch from 984f640 to fafadd0 Compare January 30, 2025 10:34

islandryu changed the title ~~[WIP] inspector: support for worker inspection in chrome devtools~~ inspector: support for worker inspection in chrome devtools Jan 30, 2025

islandryu marked this pull request as ready for review January 30, 2025 11:07

islandryu marked this pull request as draft January 30, 2025 12:06

format

234a139

islandryu marked this pull request as ready for review January 30, 2025 12:15

fix test

01011f6

legendecas reviewed Feb 4, 2025

View reviewed changes

support setAutoAttach

cde7b09

islandryu commented Feb 8, 2025

View reviewed changes

fix stoi error

b669db4

legendecas mentioned this pull request Feb 26, 2025

Session Proposal: Node.js integration with Chrome DevTools openjs-foundation/summit#439

Open

6 tasks

RafaelGSS reviewed Mar 28, 2025

View reviewed changes

add permission option test

d8747cf

islandryu force-pushed the feat/cdpTarget branch from 62315c8 to d8747cf Compare March 31, 2025 05:19

islandryu and others added 2 commits March 31, 2025 14:20

Update doc/api/cli.md

3f0b1b4

Co-authored-by: Rafael Gonzaga <rafael.nunu@hotmail.com>

fix doc

f0dc69f

jasnell reviewed Apr 12, 2025

View reviewed changes

src/inspector/target_agent.h Outdated Show resolved Hide resolved

jasnell reviewed Apr 12, 2025

View reviewed changes

src/inspector/target_agent.h Show resolved Hide resolved

jasnell reviewed Apr 12, 2025

View reviewed changes

src/inspector_agent.cc Outdated Show resolved Hide resolved

islandryu and others added 3 commits April 14, 2025 23:45

Update src/inspector/target_agent.h

85e78eb

Co-authored-by: James M Snell <jasnell@gmail.com>

fix string_view

81f91a8

fix lint

86e20df

jasnell approved these changes Apr 14, 2025

View reviewed changes

format

d31fa3e

legendecas requested changes Apr 15, 2025

View reviewed changes

islandryu and others added 2 commits April 17, 2025 17:21

Update src/inspector/node_inspector.gypi

f2cb355

Co-authored-by: Chengzhong Wu <legendecas@gmail.com>

change worker name

5c31756

islandryu requested a review from legendecas April 20, 2025 11:45

legendecas approved these changes Apr 23, 2025

View reviewed changes

legendecas added the request-ci Add this label to start a Jenkins CI on a PR. label Apr 23, 2025

github-actions bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Apr 23, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

inspector: support for worker inspection in chrome devtools #56759

inspector: support for worker inspection in chrome devtools #56759

islandryu commented Jan 25, 2025 •

edited

Loading

nodejs-github-bot commented Jan 25, 2025 •

edited by legendecas

Loading

lpinca Jan 25, 2025

islandryu Jan 27, 2025

lpinca Apr 11, 2025 •

edited

Loading

islandryu Apr 14, 2025

legendecas commented Jan 26, 2025

legendecas commented Jan 29, 2025

islandryu commented Jan 29, 2025

codecov bot commented Jan 30, 2025 •

edited

Loading

islandryu commented Feb 3, 2025

legendecas Feb 4, 2025

islandryu Feb 8, 2025

RafaelGSS Mar 28, 2025

islandryu Mar 31, 2025

legendecas left a comment •

edited

Loading

legendecas Apr 15, 2025

islandryu Apr 17, 2025

nodejs-github-bot commented Apr 23, 2025

inspector: support for worker inspection in chrome devtools #56759

Are you sure you want to change the base?

inspector: support for worker inspection in chrome devtools #56759

Conversation

islandryu commented Jan 25, 2025 • edited Loading

Summary of Changes

How to Verify

Steps:

Additional Information

nodejs-github-bot commented Jan 25, 2025 • edited by legendecas Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lpinca Apr 11, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

legendecas commented Jan 26, 2025

legendecas commented Jan 29, 2025

islandryu commented Jan 29, 2025

codecov bot commented Jan 30, 2025 • edited Loading

Codecov Report

islandryu commented Feb 3, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

legendecas left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nodejs-github-bot commented Apr 23, 2025

islandryu commented Jan 25, 2025 •

edited

Loading

nodejs-github-bot commented Jan 25, 2025 •

edited by legendecas

Loading

lpinca Apr 11, 2025 •

edited

Loading

codecov bot commented Jan 30, 2025 •

edited

Loading

legendecas left a comment •

edited

Loading