Inspecting Node.js with Chrome DevTools

Objective

We’ve been thinking about providing unified debugger support across various v8 embedders. One natural approach to that is to reuse Chrome DevTools and provide its JS debugger, performance and memory profiler functionality to Node.js users. What we aim for Node is what we have for Chrome for Android. You basically go to chrome://inspect on a stable version of Chrome and it debugs your running Node instance. You might need to override / specify ports to both if you want them to be non-default. The rest is behind the scenes.

Internal design

DevTools is comprised of the two major components: Frontend providing UI and Backend that instruments inspected application. Frontend is essentially a web application that communicates to the Backend via remote debugging protocol and nothing prevents it from connecting to Node.js instead of Chrome. To support that we’ll need to extract parts of debugger and profiler functionality from Blink into a separate project that would implement DevTools remote debugging protocol. Let’s call the project v8-inspector. Node.js could then expose the protocol to the Frontend over a WebSocket connection.

Proof of concept

I’ve created a prototype demonstrating this approach:

https://github.com/yury-s/v8-inspector - implementation of DevTools protocol for debugger, performance and memory profilers. I started with forking Blink and then removed dependencies that wouldn’t make sense in Node.js. There is definitely more work to be done but I believe this is good enough as a proof of concept.
https://github.com/yury-s/io.js/tree/remote-debugger - io.js clone that uses the project decribed above and ws module to allow using DevTools Frontend for debugging/profiling.

Local Node debugging scenario with custom ports would look like this:

Start Node with --remote-debugging-port=9222 command-line flag
Start Chrome with --remote-debugging-targets=localhost:9222 command-line flag
Navigate Chrome to chrome:inspect to see list of inspectable Node.js targets

Longer term

Long-term solution would be to have both Blink and Node.js use the same native v8-inspector library linked against v8. DevTools Frontend development would continue in Blink. For each version of v8-inspector there is a compatible version of DevTools Frontend served from the cloud. This is how it works with Android debugging at the moment: when the user opens DevTools for Chrome running on Android, the desktop browser loads a version of DevTools UI corresponding to the version of Chrome running on Android and forwards all traffic from the device to that Frontend.

Open questions

Before moving forward with this approach and investing into Blink refactorings necessary for extracting common code into its own library we’d like to collect some feedback on whether Node.js community would be interested in that. In particular, is there an interest in integrating such debugger library into Node.js core?

This will require compiling Node with the v8-inspector library and providing Node.js-specific implementation of interfaces required by the debugger.
Remote debugging protocol will be exposed to third party Node.js modules as a simple API similar to what is available for Chrome extensions (https://developer.chrome.com/extensions/debugger). Client of such API should run on a separate thread not to interfere with JavaScript in the inspected Node application. In the prototype all debugger events are forwarded from the main thread to a node instance running on a separate thread.
Implementing transport for the protocol. It can be a module that would use the debug API described above and send protocol commands over WebSocket. E.g. in the prototype it is a simple web server based on ‘ws’ module: https://github.com/yury-s/io.js/blob/remote-debugger/lib/remote_debugging_server.js. Bundling this module with the core would enable zero-conf rich devtools experience (on par with Chrome’s DevTools).
As the project evolves it will require adding new instrumentation to use some new features such as asynchronous call stacks. On the DevTools side we’ll be providing generic API that would work for both Blink and Node.js
There is some maintenance cost related to the debugger if Node.js decides to ship with it but I don’t expect it to be much higher than for the current debugger that includes debugger-agent.cc. Ideally, v8-inspector would be included as part of the v8 checkout and the obsolete debugging protocol implemented by v8 would be removed, but that is not a done deal yet.

@trevnorris

/cc @trevnorris, @bmeck

@thlorenz

/cc @thlorenz @3y3 @bajtos

/cc @nodejs/tracing

I did some related work a while ago: https://github.com/thlorenz/debugium

Implementing the protocol is the easy part. However trying to reuse code from chromium that communicates with v8 turned out to be non-trivial.
Things are quite coupled in there as I realized when I tried to unfuddle things.

For anyone working on this https://github.com/thlorenz/chromium-remote-debugging-proxy may come in useful as it allows watching the messages sent between chrome DevTools and the debugged instance which helps in understanding the protocol used.

@bajtos

To add a few items…

This project brings all of the DevTools's JS features to Node. That includes:

the sampling profiler with flame chart, top-down and bottom-up tree views
memory heap snapshot capture and viewing
memory allocation profiler
JS debugger with breakpoints, step-out/in/over. Asynchronous stacks
Experimental efforts around Step into Async, Promises view, etc.

Moving forward with this would make the current node-inspector codebase somewhat redundant, but we'd like to work with @bajtos, @3y3 and friends on making sure the experience of launching a debugging/profiling session with these tools is smooth and enjoyable.

@thlorenz

At one point I was told that the chrome team was going to take that on, but afaik that never materialized.

This ticket is the materialization of that work. ;) @yury-s is an engineer on Chrome and owns the JS debugging tools and how they interface with V8.

@paulirish

@paulirish Awesome! Happy this is finally happening :)

Does --remote-debugging-port=9222 bind to localhost or 0.0.0.0? Could it be made configurable? Much usage will come from debugging remote processes.

Will we have to integrate the same type of code into our JS, along with our C++, like in v8/src/promise.js:

  if (DEBUG_IS_ACTIVE) {
    %DebugPromiseEvent({ promise: promise, status: status, value: value });
  }

Having this w/o LTS support reduces its utility in node. As such it will become a maintenance burden across 4 or 5 active branches. Is it even possible that this API is integrated in a V8 release that's 1-2 years old?

Also in regards to LTS support, I assume that there isn't indefinite support of Chrome to debugger API support. Or am I wrong?

Does --remote-debugging-port=9222 bind to localhost or 0.0.0.0? Could it be made configurable? Much usage will come from debugging remote processes.

It can be bound to any interface that we want, I don't see any issues with that (except security). Chrome already accepts both host and port as values of --remote-debugging-targets and the host may well be remote one.

It makes sense to differentiate between transport and the debugger backend implementing the remote debugging protocol. Same debugger implementation can be used with different types of connections similar to how it works in Chrome at the moment where various transports are used to transfer DevTools traffic depending on the inspected target:

Chrome IPC in case of Chrome embedded DevTools.
Web Socket when connecting to remote Chrome instance.
Adb when connecting to Chrome and WebView running on Android devices.

Will we have to integrate the same type of code into our JS, along with our C++, like in v8/src/promise.js:

If Node uses alternative implementation of Promises and wants to leverage debugging capabilities provided by v8-inspector then yes, you will need to provide corresponding instrumentation that way or another. v8-inspector is going to have C++ API so you'll need at least one binding to notify the debugger. The call will go through the v8-inspector C++ API not through some internal v8 API.

Is it even possible that this API is integrated in a V8 release that's 1-2 years old?

I'm afraid not, as it would require making v8-inspector work with such old releases of v8. This is a non-goal for the project. As I mentioned, the idea is to have particular version of v8-inspector compatible with particular version of v8 API. If v8 is updated, v8-inspector will likely need to be updated as well.

Also in regards to LTS support, I assume that there isn't indefinite support of Chrome to debugger API support. Or am I wrong?

At the moment, there is no official v8 debugger API which would be well-supported. There is a set of C++ methods in v8-debug.h as well as debug context which provides access to the debugger internals. This is one of the issues we'd like to address with v8-inspector. It should become a recommended way to debug v8. Eventually we'd like to drop most of v8/src/debug/debug.js and prohibit using the debug context directly.

Such approach would leave us the freedom of changing remote debugging protocol without committing to its backward compatibility as there will always be a version of Chrome DevTools compatible with given version of the backend. There are already two types of protocol commands: public and hidden. Public ones are those for which we commit to backward compatibility. We're hesitant on adding more public commands as it limits our development pace.

In terms of LTS, similar to v8 we don't want to commit to keeping the API stable as it would be too restrictive. What we can do is to follow the same public API compatibility as v8 does (or at least declares): https://code.google.com/p/v8-wiki/wiki/Source#V8_public_API_compatibility

Since Blink is going to use v8-inspector too, we'll have to keep it up to date with latest v8 API changes. Should we make any breaking changes they will be easy to detect in nightly builds and can be reverted. On our side we'll have to make sure that changes to v8-inspector API would be made in a non-breaking manner, follow the same public API deprecation policy as v8 does and the new APIs would work for Node too, not only for Chrome.

Will this work for you?

@thlorenz

@thlorenz ,

Implementing the protocol is the easy part. However trying to reuse code from chromium that communicates with v8 turned out to be non-trivial.

At current iteration node-inspector tries to inject some parts of Chrome debugger API to app.
There exists some outdated experiments with InjectedScriptSource.js and DebuggerScript.js from blink source.

v8-debug has experimental method enableWebkitProtocol
(but work in progress)

Main problem of this experiments - compatibility:

Compatibility of js codebase - chrome debugger uses all latest js features implemented in v8 (generators, arrow functions, for of) (I say here about InjectedScriptSource.js and DebuggerScript.js)
Compatibility of features (c++ codebase) - async call stack, workers, network debugging etc. This is also described in issue open questions

As the project evolves it will require adding new instrumentation to use some new features such as asynchronous call stacks. On the DevTools side we’ll be providing generic API that would work for both Blink and Node.js

For this reason I also worried about @trevnorris questions:

Is it even possible that this API is integrated in a V8 release that's 1-2 years old?

@paulirish ,

Moving forward with this would make the current node-inspector codebase somewhat redundant

I will be happy, if node-inspector will change his main target from "supporting compatibility with DevTools" to something like "extended debugging environment for nodejs"

@yury-s , are you want to backport async call stack from chrome to node? And some other features?

I'd like to think about v8-inspector.h like about current v8-debug.h in v8. His provide main api to implement debugger into nodejs, but also provides entry points for external developers.
In context of v8-debug.h main entry point is getDebugContext.
So I'd like to see more api for external developers =)

@auchenberg

/cc @auchenberg

@yury-s

@yury-s Thank you for the comprehensive response.

If Node uses alternative implementation of Promises and wants to leverage debugging capabilities provided by v8-inspector then yes

Our process.nextTick() emulates the micro task queue. This and our handling of timers would most likely require insertion.

Is it even possible that this API is integrated in a V8 release that's 1-2 years old?

I'm afraid not, as it would require making v8-inspector work with such old releases of v8. This is a non-goal for the project.

While I understand, it's also unfortunate. Our main stable release is 6 month. Taking into account V8's rapid release cycle I will make the assumption that the same API could break before that is over. If we can't guarantee support for at least the 6 months of latest stable then I'm afraid that it won't do us any good.

Beyond that, saying it would be available for the 6 months of stable but not for the 18 months of LTS would need to have serious discussion as to whether bringing it is still viable. For the time I'm ignoring the additional 12 months a release will be in maintenance. Which brings full support to 3 years.

I do hope we can work out these issues, as having this available would be very helpful.

@trevnorris

For this reason I also worried about @trevnorris questions:

Is it even possible that this API is integrated in a V8 release that's 1-2 years old?

No. See my reply above.

@yury-s , are you want to backport async call stack from chrome to node? And some other features?

As Paul Irish wrote above the project will come with all debugging features available in Chromium. Async call stacks is not an exception. There is a generic API resembling the one described in this MSDN article which needs to be called from appropriate places where we'd like to capture async call stacks. I can help with adding such instrumentation to Node but we'll need some person knowledgeable better than me to identify places where the hooks should be added.

I'd like to think about v8-inspector.h like about current v8-debug.h in v8. His provide main api to implement debugger into nodejs, but also provides entry points for external developers.
In context of v8-debug.h main entry point is getDebugContext.

This is a good way to think about v8-inspector. Ideally, we should be able to drop v8-debug.h in favor of v8-inspector. This would make the API more explicit and allow to provide better support for it.

While I understand, it's also unfortunate. Our main stable release is 6 month. Taking into account V8's rapid release cycle I will make the assumption that the same API could break before that is over. If we can't guarantee support for at least the 6 months of latest stable then I'm afraid that it won't do us any good.

How does this work with v8 at the moment? There may be 4 or 5 major v8 releases in 6 months which means there may be a lot of breaking changes. Assuming that v8-inspector is shipped as part of v8 and its API is defined in /include/v8-inspector.h (which would be ideal case for us long-term) how would that work with Node?

I do hope we can work out these issues, as having this available would be very helpful.

I hope so too.

Can this be closed now?

I think so. Please reopen if I'm wrong.

What is the current status on the effort to integrate in with vanilla v8? I'm currently building this functionality and have it minimally functional but would rather not, but I don't know how to find out about the progress being made.

Thank you.

@xaxxon

@xaxxon use node --inspect on v6+, should work fairly well

@xaxxon

I'm not using node, though.

On Wed, Oct 5, 2016 at 8:23 AM, Bradley Meck notifications@github.com
wrote:

@xaxxon https://github.com/xaxxon use node --inspect on v6+, should
work fairly well

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#2546 (comment), or mute
the thread
https://github.com/notifications/unsubscribe-auth/AAIycuUi5Tj8B7sVus9suliVTUI_stEeks5qw8DWgaJpZM4FyAmT
.

You might want to check the V8 issue tracker then.

The code is in the V8 now, e.g. -
https://github.com/v8/v8/tree/ba41697cbd72ea7dcdd89e6dbe9090ecb156ce6c/src/inspector

On Wed, Oct 5, 2016 at 8:24 AM Colin Ihrig notifications@github.com wrote:

You might want to check the V8 issue tracker then.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
#2546 (comment), or mute
the thread
https://github.com/notifications/unsubscribe-auth/AARkrVMxf-2hCea0SHccmwmrYQR7_m7Wks5qw8E8gaJpZM4FyAmT
.

thank you.

On Wed, Oct 5, 2016 at 9:24 AM, Eugene Ostroukhov notifications@github.com
wrote:

The code is in the V8 now, e.g. -
https://github.com/v8/v8/tree/ba41697cbd72ea7dcdd89e6dbe9090
ecb156ce6c/src/inspector

On Wed, Oct 5, 2016 at 8:24 AM Colin Ihrig notifications@github.com
wrote:

You might want to check the V8 issue tracker then.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
#2546 (comment), or
mute
the thread
<https://github.com/notifications/unsubscribe-auth/AARkrVMxf-
2hCea0SHccmwmrYQR7_m7Wks5qw8E8gaJpZM4FyAmT>

.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#2546 (comment), or mute
the thread
https://github.com/notifications/unsubscribe-auth/AAIyckAW2RICpAYxAYi6zBOjV2PykixBks5qw88-gaJpZM4FyAmT
.

I wonder if it is currently or would be possible to access this url programatically from the Node process?

No, not yet. We can expose it if it is really needed.

I'm just think it would be nice to be able to expose it so in the process can open the tab for you automatically if you so wish. However It seems that you can actually determine the URL yourself if you know the port, which you can specify with --inspect=1234

UUID is not exposed.

On Wed, Nov 2, 2016 at 9:55 AM Matthew Spence notifications@github.com
wrote:

I'm just think it would be nice to be able to expose it so in the process
can open the tab for you automatically if you so wish. However It seems
that you can actually determine the URL yourself if you know the port,
which you can specify with --inspect=1234

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
#2546 (comment), or mute
the thread
https://github.com/notifications/unsubscribe-auth/AARkrVmlK-gwGRcNbq4PZSlaTl8O2cSEks5q6MCRgaJpZM4FyAmT
.

With chrome-cli installed (open doesn't like the chrome-devtools protocol) I have the following proof of concept working on node 6.9.1

const { exec } = require('child_process');
  exec('chrome-cli list links', (_error, stdout) => {
    const url = `chrome-devtools://devtools/bundled/inspector.html?experiments=true&v8only=true&ws=localhost:${process.env.npm_package_config_debugPort || 9221}/node`;
    const match = stdout.match(new RegExp(`\\[(\\d+)\\] chrome-devtools://devtools/bundled/inspector.html\\?experiments=true&v8only=true&ws=localhost:${process.env.npm_package_config_debugPort || 9221}/node`));
    const tabId = match ? ` -t ${match[1]}` : '';
    exec(`chrome-cli open "${url}"${tabId}`);
  });

Where $npm_package_config_debugPort is provided to the node --inspect flag.

I was having the same issue a few days ago and wrote a Chrome extension to solve it. Would love any feedback.

http://june07.com/nim

Direct Chrome Web Store link: https://chrome.google.com/webstore/detail/nim-node-inspector-monito/gnhhdgbaldcilmgcpfddgdbkhjohddkj

Navigation Menu

Repository navigation

Inspecting Node.js with Chrome DevTools #2546

Objective

Internal design

Proof of concept

Longer term

Open questions

64 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Inspecting Node.js with Chrome DevTools #2546

Description

Objective

Internal design

Proof of concept

Longer term

Open questions

Activity

ofrobots commented on Aug 25, 2015

bmeck commented on Aug 25, 2015

Qard commented on Aug 25, 2015

thlorenz commented on Aug 25, 2015

paulirish commented on Aug 25, 2015

thlorenz commented on Aug 25, 2015

trevnorris commented on Aug 25, 2015

yury-s commented on Aug 25, 2015

3y3 commented on Aug 25, 2015

3y3 commented on Aug 25, 2015

trevnorris commented on Aug 25, 2015

yury-s commented on Aug 25, 2015

yury-s commented on Aug 25, 2015

64 remaining items

trevnorris commented on Jun 2, 2016

cjihrig commented on Jun 2, 2016

xaxxon commented on Oct 5, 2016

bmeck commented on Oct 5, 2016

xaxxon commented on Oct 5, 2016

cjihrig commented on Oct 5, 2016

eugeneo commented on Oct 5, 2016

xaxxon commented on Oct 5, 2016

msaspence commented on Nov 2, 2016

eugeneo commented on Nov 2, 2016

msaspence commented on Nov 2, 2016

eugeneo commented on Nov 2, 2016

msaspence commented on Nov 2, 2016

june07 commented on Nov 16, 2016

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions