Source Code: lib/inspector.js
\nThe node:inspector module provides an API for interacting with the V8\ninspector.
It can be accessed using:
\nimport * as inspector from 'node:inspector/promises';\nconst inspector = require('node:inspector/promises');\nor
\nimport * as inspector from 'node:inspector';\nconst inspector = require('node:inspector');\nThe inspector.Session is used for dispatching messages to the V8 inspector\nback-end and receiving message responses and notifications.
Emitted when any notification from the V8 Inspector is received.
\nsession.on('inspectorNotification', (message) => console.log(message.method));\n// Debugger.paused\n// Debugger.resumed\n\n\nCaveat Breakpoints with same-thread session is not recommended, see\nsupport of breakpoints.
\n
It is also possible to subscribe only to notifications with specific method:
" }, { "textRaw": "Event: `Emitted when an inspector notification is received that has its method field set\nto the <inspector-protocol-method> value.
The following snippet installs a listener on the 'Debugger.paused'\nevent, and prints the reason for program suspension whenever program\nexecution is suspended (through breakpoints, for example):
session.on('Debugger.paused', ({ params }) => {\n console.log(params.hitBreakpoints);\n});\n// [ '/the/file/that/has/the/breakpoint.js:11:0' ]\n\n" } ], "methods": [ { "textRaw": "`session.connect()`", "type": "method", "name": "connect", "meta": { "added": [ "v8.0.0" ], "changes": [] }, "signatures": [ { "params": [] } ], "desc": "Caveat Breakpoints with same-thread session is not recommended, see\nsupport of breakpoints.
\n
Connects a session to the inspector back-end.
" }, { "textRaw": "`session.connectToMainThread()`", "type": "method", "name": "connectToMainThread", "meta": { "added": [ "v12.11.0" ], "changes": [] }, "signatures": [ { "params": [] } ], "desc": "Connects a session to the main thread inspector back-end. An exception will\nbe thrown if this API was not called on a Worker thread.
" }, { "textRaw": "`session.disconnect()`", "type": "method", "name": "disconnect", "meta": { "added": [ "v8.0.0" ], "changes": [] }, "signatures": [ { "params": [] } ], "desc": "Immediately close the session. All pending message callbacks will be called\nwith an error. session.connect() will need to be called to be able to send\nmessages again. Reconnected session will lose all inspector state, such as\nenabled agents or configured breakpoints.
Posts a message to the inspector back-end.
\nimport { Session } from 'node:inspector/promises';\ntry {\n const session = new Session();\n session.connect();\n const result = await session.post('Runtime.evaluate', { expression: '2 + 2' });\n console.log(result);\n} catch (error) {\n console.error(error);\n}\n// Output: { result: { type: 'number', value: 4, description: '4' } }\nThe latest version of the V8 inspector protocol is published on the\nChrome DevTools Protocol Viewer.
\nNode.js inspector supports all the Chrome DevTools Protocol domains declared\nby V8. Chrome DevTools Protocol domain provides an interface for interacting\nwith one of the runtime agents used to inspect the application state and listen\nto the run-time events.
\nApart from the debugger, various V8 Profilers are available through the DevTools\nprotocol.
", "modules": [ { "textRaw": "CPU profiler", "name": "cpu_profiler", "desc": "Here's an example showing how to use the CPU Profiler:
\nimport { Session } from 'node:inspector/promises';\nimport fs from 'node:fs';\nconst session = new Session();\nsession.connect();\n\nawait session.post('Profiler.enable');\nawait session.post('Profiler.start');\n// Invoke business logic under measurement here...\n\n// some time later...\nconst { profile } = await session.post('Profiler.stop');\n\n// Write profile to disk, upload, etc.\nfs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile));\nHere's an example showing how to use the Heap Profiler:
\nimport { Session } from 'node:inspector/promises';\nimport fs from 'node:fs';\nconst session = new Session();\n\nconst fd = fs.openSync('profile.heapsnapshot', 'w');\n\nsession.connect();\n\nsession.on('HeapProfiler.addHeapSnapshotChunk', (m) => {\n fs.writeSync(fd, m.params.chunk);\n});\n\nconst result = await session.post('HeapProfiler.takeHeapSnapshot', null);\nconsole.log('HeapProfiler.takeHeapSnapshot done:', result);\nsession.disconnect();\nfs.closeSync(fd);\nCreate a new instance of the inspector.Session class. The inspector session\nneeds to be connected through session.connect() before the messages\ncan be dispatched to the inspector backend.
When using Session, the object outputted by the console API will not be\nreleased, unless we performed manually Runtime.DiscardConsoleEntries\ncommand.
The inspector.Session is used for dispatching messages to the V8 inspector\nback-end and receiving message responses and notifications.
Emitted when any notification from the V8 Inspector is received.
\nsession.on('inspectorNotification', (message) => console.log(message.method));\n// Debugger.paused\n// Debugger.resumed\n\n\nCaveat Breakpoints with same-thread session is not recommended, see\nsupport of breakpoints.
\n
It is also possible to subscribe only to notifications with specific method:
" }, { "textRaw": "Event: `Emitted when an inspector notification is received that has its method field set\nto the <inspector-protocol-method> value.
The following snippet installs a listener on the 'Debugger.paused'\nevent, and prints the reason for program suspension whenever program\nexecution is suspended (through breakpoints, for example):
session.on('Debugger.paused', ({ params }) => {\n console.log(params.hitBreakpoints);\n});\n// [ '/the/file/that/has/the/breakpoint.js:11:0' ]\n\n" } ], "methods": [ { "textRaw": "`session.connect()`", "type": "method", "name": "connect", "meta": { "added": [ "v8.0.0" ], "changes": [] }, "signatures": [ { "params": [] } ], "desc": "Caveat Breakpoints with same-thread session is not recommended, see\nsupport of breakpoints.
\n
Connects a session to the inspector back-end.
" }, { "textRaw": "`session.connectToMainThread()`", "type": "method", "name": "connectToMainThread", "meta": { "added": [ "v12.11.0" ], "changes": [] }, "signatures": [ { "params": [] } ], "desc": "Connects a session to the main thread inspector back-end. An exception will\nbe thrown if this API was not called on a Worker thread.
" }, { "textRaw": "`session.disconnect()`", "type": "method", "name": "disconnect", "meta": { "added": [ "v8.0.0" ], "changes": [] }, "signatures": [ { "params": [] } ], "desc": "Immediately close the session. All pending message callbacks will be called\nwith an error. session.connect() will need to be called to be able to send\nmessages again. Reconnected session will lose all inspector state, such as\nenabled agents or configured breakpoints.
Posts a message to the inspector back-end. callback will be notified when\na response is received. callback is a function that accepts two optional\narguments: error and message-specific result.
session.post('Runtime.evaluate', { expression: '2 + 2' },\n (error, { result }) => console.log(result));\n// Output: { type: 'number', value: 4, description: '4' }\nThe latest version of the V8 inspector protocol is published on the\nChrome DevTools Protocol Viewer.
\nNode.js inspector supports all the Chrome DevTools Protocol domains declared\nby V8. Chrome DevTools Protocol domain provides an interface for interacting\nwith one of the runtime agents used to inspect the application state and listen\nto the run-time events.
\nYou can not set reportProgress to true when sending a\nHeapProfiler.takeHeapSnapshot or HeapProfiler.stopTrackingHeapObjects\ncommand to V8.
Apart from the debugger, various V8 Profilers are available through the DevTools\nprotocol.
", "modules": [ { "textRaw": "CPU profiler", "name": "cpu_profiler", "desc": "Here's an example showing how to use the CPU Profiler:
\nconst inspector = require('node:inspector');\nconst fs = require('node:fs');\nconst session = new inspector.Session();\nsession.connect();\n\nsession.post('Profiler.enable', () => {\n session.post('Profiler.start', () => {\n // Invoke business logic under measurement here...\n\n // some time later...\n session.post('Profiler.stop', (err, { profile }) => {\n // Write profile to disk, upload, etc.\n if (!err) {\n fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile));\n }\n });\n });\n});\nHere's an example showing how to use the Heap Profiler:
\nconst inspector = require('node:inspector');\nconst fs = require('node:fs');\nconst session = new inspector.Session();\n\nconst fd = fs.openSync('profile.heapsnapshot', 'w');\n\nsession.connect();\n\nsession.on('HeapProfiler.addHeapSnapshotChunk', (m) => {\n fs.writeSync(fd, m.params.chunk);\n});\n\nsession.post('HeapProfiler.takeHeapSnapshot', null, (err, r) => {\n console.log('HeapProfiler.takeHeapSnapshot done:', err, r);\n session.disconnect();\n fs.closeSync(fd);\n});\nCreate a new instance of the inspector.Session class. The inspector session\nneeds to be connected through session.connect() before the messages\ncan be dispatched to the inspector backend.
When using Session, the object outputted by the console API will not be\nreleased, unless we performed manually Runtime.DiscardConsoleEntries\ncommand.
Attempts to close all remaining connections, blocking the event loop until all\nare closed. Once all connections are closed, deactivates the inspector.
" }, { "textRaw": "`inspector.open([port[, host[, wait]]])`", "type": "method", "name": "open", "meta": { "changes": [ { "version": "v20.6.0", "pr-url": "https://github.com/nodejs/node/pull/48765", "description": "inspector.open() now returns a `Disposable` object." } ] }, "signatures": [ { "return": { "textRaw": "Returns: {Disposable} A Disposable that calls [`inspector.close()`][].", "name": "return", "type": "Disposable", "desc": "A Disposable that calls [`inspector.close()`][]." }, "params": [ { "textRaw": "`port` {number} Port to listen on for inspector connections. Optional. **Default:** what was specified on the CLI.", "name": "port", "type": "number", "default": "what was specified on the CLI", "desc": "Port to listen on for inspector connections. Optional." }, { "textRaw": "`host` {string} Host to listen on for inspector connections. Optional. **Default:** what was specified on the CLI.", "name": "host", "type": "string", "default": "what was specified on the CLI", "desc": "Host to listen on for inspector connections. Optional." }, { "textRaw": "`wait` {boolean} Block until a client has connected. Optional. **Default:** `false`.", "name": "wait", "type": "boolean", "default": "`false`", "desc": "Block until a client has connected. Optional." } ] } ], "desc": "Activate inspector on host and port. Equivalent to\nnode --inspect=[[host:]port], but can be done programmatically after node has\nstarted.
If wait is true, will block until a client has connected to the inspect port\nand flow control has been passed to the debugger client.
See the security warning regarding the host\nparameter usage.
Return the URL of the active inspector, or undefined if there is none.
$ node --inspect -p 'inspector.url()'\nDebugger listening on ws://127.0.0.1:9229/166e272e-7a30-4d09-97ce-f1c012b43c34\nFor help, see: https://nodejs.org/en/docs/inspector\nws://127.0.0.1:9229/166e272e-7a30-4d09-97ce-f1c012b43c34\n\n$ node --inspect=localhost:3000 -p 'inspector.url()'\nDebugger listening on ws://localhost:3000/51cf8d0e-3c36-4c59-8efd-54519839e56a\nFor help, see: https://nodejs.org/en/docs/inspector\nws://localhost:3000/51cf8d0e-3c36-4c59-8efd-54519839e56a\n\n$ node -p 'inspector.url()'\nundefined\nBlocks until a client (existing or connected later) has sent\nRuntime.runIfWaitingForDebugger command.
An exception will be thrown if there is no active inspector.
" } ], "properties": [ { "textRaw": "`console` {Object} An object to send messages to the remote inspector console.", "type": "Object", "name": "console", "desc": "require('node:inspector').console.log('a message');\nThe inspector console does not have API parity with Node.js\nconsole.
", "shortDesc": "An object to send messages to the remote inspector console." } ], "type": "module", "displayName": "Common Objects" }, { "textRaw": "Support of breakpoints", "name": "support_of_breakpoints", "desc": "The Chrome DevTools Protocol Debugger domain allows an\ninspector.Session to attach to a program and set breakpoints to step through\nthe codes.
However, setting breakpoints with a same-thread inspector.Session, which is\nconnected by session.connect(), should be avoided as the program being\nattached and paused is exactly the debugger itself. Instead, try connect to the\nmain thread by session.connectToMainThread() and set breakpoints in a\nworker thread, or connect with a Debugger program over WebSocket\nconnection.