Skip to content

Commit a5932b2

Browse files
joshgavjoshgav
committed
inspector,doc: update hint text, add guide
Updates hint text for --inspect to be more generic. Instructions for various debugger clients moved into a referenced guide. PR-URL: #8978 Fixes: #7182 Reviewed-By: <tbd> Reviewed-By: <tbd>
1 parent 92ece86 commit a5932b2

File tree

3 files changed

+194
-13
lines changed

3 files changed

+194
-13
lines changed

‎doc/guides/debugging.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# Debugging Guide
2+
3+
<!-- type=misc -->
4+
5+
The goal of this guide is to provide you with enough information to get started
6+
debugging your Node.js apps and scripts.
7+
8+
## Enable Debugging
9+
10+
When started with the **--debug** or **--debug-brk** switches, Node.js listens
11+
for debugging commands defined by the [V8 Debugging Protocol][] on a TCP port,
12+
by default `5858`. Any debugger client which speaks this protocol can connect
13+
to and debug the running process.
14+
15+
A running Node.js process can also be instructed to start listening for
16+
debugging messages by signaling it with `SIGUSR1` (on Linux and OS X).
17+
18+
When started with the **--inspect** or **--inspect-brk** switches, Node.js
19+
listens for diagnostic commands defined by the [Chrome Debugging Protocol][]
20+
via websockets, by default at `ws://127.0.0.1:9229/node`. Any diagnostics
21+
client which speaks this protocol can connect to and debug the running process.
22+
23+
The `--inspect` option and protocol are _experimental_ and may change.
24+
25+
[V8 Debugging Protocol]: https://github.com/v8/v8/wiki/Debugging-Protocol
26+
[Chrome Debugging Protocol]: https://developer.chrome.com/devtools/docs/debugger-protocol
27+
28+
29+
## Debugging Clients
30+
31+
Several commercial and open source tools can connect to Node's
32+
debugger and/or inspector. Info on these follows.
33+
34+
* [Built-in Debugger](https://github.com/nodejs/node/blob/master/lib/_debugger.js)
35+
36+
* Start `node debug script_name.js` to start your script under Node's
37+
builtin command-line debugger. Your script starts in another Node
38+
process started with the `--debug-brk` option, and the initial Node
39+
process runs the `_debugger.js` script and connects to your target.
40+
41+
* [Chrome DevTools](https://github.com/ChromeDevTools/devtools-frontend)
42+
43+
* **Option 1 (Chrome 55+)**: Open `chrome://inspect` in your Chromium
44+
browser. Click the Configure button and ensure your target host and port
45+
are listed.
46+
* **Option 2**: Paste the following URL in Chrome,
47+
replacing the `ws` parameter with your hostname and port as needed:
48+
49+
`chrome-devtools://devtools/remote/serve_file/@60cd6e859b9f557d2312f5bf532f6aec5f284980/inspector.html?experiments=true&v8only=true&ws=localhost:9229/node`
50+
51+
> The hash represents the current revision and is specified in
52+
<https://github.com/nodejs/node/blob/master/deps/v8_inspector/third_party/v8_inspector/platform/v8_inspector/public/InspectorVersion.h>
53+
54+
* [VS Code](https://github.com/microsoft/vscode)
55+
* **Option 1**: In the Debug panel, click the settings button to choose
56+
initial debug configurations. Select "Node.js v6.3+ (Experimental)" for
57+
`--inspect` support, or "Node.js" for `--debug` support.
58+
* **Option 2**: In debug configurations in `.vscode/launch.json`, set `type`
59+
as `node2`.
60+
61+
* For more info, see <https://github.com/Microsoft/vscode-node-debug2>.
62+
63+
* [IntelliJ WebStorm](tbd)
64+
65+
* [node-inspector](https://github.com/node-inspector/node-inspector)
66+
67+
* [chrome-remote-interface](https://github.com/cyrus-and/chrome-remote-interface)
68+
69+
70+
## Debugging command-line options
71+
72+
* The following table clarifies the implications of various diag-related flags:
73+
74+
<table cellpadding=0 cellspacing=0>
75+
<tr><th>Flag</th><th>Meaning</th></tr>
76+
<tr>
77+
<td>--debug</td>
78+
<td>
79+
<ul>
80+
<li>Enable debugger agent</li>
81+
<li>Listen on default port (5858)</li>
82+
</ul>
83+
</td>
84+
</tr>
85+
<tr>
86+
<td>--debug=<i>port</i></td>
87+
<td>
88+
<ul>
89+
<li>Enable debugger agent</li>
90+
<li>Listen on port <i>port</i></li>
91+
</ul>
92+
</td>
93+
</tr>
94+
<tr>
95+
<td>--debug-brk</td>
96+
<td>
97+
<ul>
98+
<li>Enable debugger agent</li>
99+
<li>Listen on default port (5858)</li>
100+
<li>Break before user code starts</li>
101+
</ul>
102+
</td>
103+
</tr>
104+
<tr>
105+
<td>--debug-brk=<i>port</i></td>
106+
<td>
107+
<ul>
108+
<li>Enable debugger agent</li>
109+
<li>Listen on port <i>port</i></li>
110+
<li>Break before user code starts</li>
111+
</ul>
112+
</td>
113+
</tr>
114+
<tr>
115+
<td>--inspect</td>
116+
<td>
117+
<ul>
118+
<li>Enable inspector agent</li>
119+
<li>Listen on default port (9229)</li>
120+
</ul>
121+
</td>
122+
</tr>
123+
<tr>
124+
<td>--inspect=<i>port</i></td>
125+
<td>
126+
<ul>
127+
<li>Enable inspector agent</li>
128+
<li>Listen on port <i>port</i></li>
129+
</ul>
130+
</td>
131+
</tr>
132+
<tr>
133+
<td>--inspect-brk</td>
134+
<td>
135+
<ul>
136+
<li>Enable inspector agent</li>
137+
<li>Listen on default port (9229)</li>
138+
<li>Break before user code starts</li>
139+
</ul>
140+
</td>
141+
</tr>
142+
<tr>
143+
<td>--inspect-brk=<i>port</i></td>
144+
<td>
145+
<ul>
146+
<li>Enable debugger agent</li>
147+
<li>Listen on port <i>port</i></li>
148+
<li>Break before user code starts</li>
149+
</ul>
150+
</td>
151+
</tr>
152+
<tr>
153+
<td>--debug-port=<i>port</i></td>
154+
<td>
155+
<ul>
156+
<li> Set port to <i>port</i> for other flags. Must come after others.
157+
</ul>
158+
</td>
159+
</tr>
160+
<tr>
161+
<td><code>node debug <i>script.js</i></code></td>
162+
<td>
163+
<ul>
164+
<li>Spawn child process to run user script under --debug mode,
165+
and use main process to run CLI debugger.</li>
166+
</ul>
167+
</td>
168+
</tr>
169+
</table>
170+
171+
172+
## Default ports:
173+
174+
* Inpsector: 9229
175+
* Debugger: 5858
176+

‎src/inspector_agent.cc‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -43,13 +43,12 @@ std::string GetWsUrl(int port, const std::string& id) {
4343
}
4444

4545
void PrintDebuggerReadyMessage(int port, const std::string& id) {
46-
fprintf(stderr, "Debugger listening on port %d.\n"
47-
"Warning: This is an experimental feature and could change at any time.\n"
48-
"To start debugging, open the following URL in Chrome:\n"
49-
" chrome-devtools://devtools/remote/serve_file/"
50-
"@" V8_INSPECTOR_REVISION "/inspector.html?"
51-
"experiments=true&v8only=true&ws=%s\n",
52-
port, GetWsUrl(port, id).c_str());
46+
fprintf(stderr, "Debugger listening on \x1B[33mws://%s\x1b[0m\n"
47+
"* Info on connecting at"
48+
"\x1B[33mhttps://nodejs.org/en/docs/guides/debugging\x1B[0m.\n"
49+
"* Warning: This is an experimental feature and could change at any time."
50+
"\n\n",
51+
GetWsUrl(port, id).c_str());
5352
fflush(stderr);
5453
}
5554

‎test/inspector/inspector-helper.js‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -412,20 +412,26 @@ exports.startNodeForInspectorTest = function(callback) {
412412

413413
const timeoutId = timeout('Child process did not start properly', 4);
414414

415-
let found = false;
415+
var found = false;
416416

417417
const dataCallback = makeBufferingDataCallback((text) => {
418418
clearTimeout(timeoutId);
419419
console.log('[err]', text);
420420
if (found) return;
421-
const match = text.match(/Debugger listening on port (\d+)/);
422-
found = true;
423-
child.stderr.removeListener('data', dataCallback);
424-
assert.ok(match, text);
425-
callback(new Harness(match[1], child));
421+
const re = /Debugger listening on.*ws:\/\/(.*):(\d+)\/(\w+)/;
422+
const match = text.match(re);
423+
if (match) {
424+
found = true;
425+
child.stderr.removeListener('data', dataCallback);
426+
callback(new Harness(match[2], child));
427+
return;
428+
}
426429
});
427430

428431
child.stderr.on('data', dataCallback);
432+
child.on('exit', (code, signal) => {
433+
assert.ok(found, 'Failed to start child script.');
434+
});
429435

430436
const handler = tearDown.bind(null, child);
431437

0 commit comments

Comments
 (0)