Skip to content

Commit

Permalink
doc: add notes on inspector breakpoints
Browse files Browse the repository at this point in the history
Setting breakpoints with a same-thread inspector session should be
avoided because the program being attached and paused is exactly the
debugger itself. A worker thread inspector session or a debugger
program should be used if breakpoints are needed.

PR-URL: #51417
Fixes: #51397
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
  • Loading branch information
legendecas authored and richardlau committed Mar 25, 2024
1 parent 713afed commit 3532f55
Showing 1 changed file with 29 additions and 0 deletions.
29 changes: 29 additions & 0 deletions doc/api/inspector.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,9 @@ session.on('inspectorNotification', (message) => console.log(message.method));
// Debugger.resumed
```

> **Caveat** Breakpoints with same-thread session is not recommended, see
> [support of breakpoints][].
It is also possible to subscribe only to notifications with specific method:

#### Event: `<inspector-protocol-method>`;
Expand All @@ -98,6 +101,9 @@ session.on('Debugger.paused', ({ params }) => {
// [ '/the/file/that/has/the/breakpoint.js:11:0' ]
```

> **Caveat** Breakpoints with same-thread session is not recommended, see
> [support of breakpoints][].
#### `session.connect()`

<!-- YAML
Expand Down Expand Up @@ -247,6 +253,9 @@ session.on('inspectorNotification', (message) => console.log(message.method));
// Debugger.resumed
```

> **Caveat** Breakpoints with same-thread session is not recommended, see
> [support of breakpoints][].
It is also possible to subscribe only to notifications with specific method:

#### Event: `<inspector-protocol-method>`;
Expand All @@ -271,6 +280,9 @@ session.on('Debugger.paused', ({ params }) => {
// [ '/the/file/that/has/the/breakpoint.js:11:0' ]
```

> **Caveat** Breakpoints with same-thread session is not recommended, see
> [support of breakpoints][].
#### `session.connect()`

<!-- YAML
Expand Down Expand Up @@ -476,10 +488,27 @@ Blocks until a client (existing or connected later) has sent

An exception will be thrown if there is no active inspector.

## Support of breakpoints

The Chrome DevTools Protocol [`Debugger` domain][] allows an
`inspector.Session` to attach to a program and set breakpoints to step through
the codes.

However, setting breakpoints with a same-thread `inspector.Session`, which is
connected by [`session.connect()`][], should be avoided as the program being
attached and paused is exactly the debugger itself. Instead, try connect to the
main thread by [`session.connectToMainThread()`][] and set breakpoints in a
worker thread, or connect with a [Debugger][] program over WebSocket
connection.

[CPU Profiler]: https://chromedevtools.github.io/devtools-protocol/v8/Profiler
[Chrome DevTools Protocol Viewer]: https://chromedevtools.github.io/devtools-protocol/v8/
[Debugger]: debugger.md
[Heap Profiler]: https://chromedevtools.github.io/devtools-protocol/v8/HeapProfiler
[`'Debugger.paused'`]: https://chromedevtools.github.io/devtools-protocol/v8/Debugger#event-paused
[`Debugger` domain]: https://chromedevtools.github.io/devtools-protocol/v8/Debugger
[`inspector.close()`]: #inspectorclose
[`session.connect()`]: #sessionconnect
[`session.connectToMainThread()`]: #sessionconnecttomainthread
[security warning]: cli.md#warning-binding-inspector-to-a-public-ipport-combination-is-insecure
[support of breakpoints]: #support-of-breakpoints

0 comments on commit 3532f55

Please sign in to comment.