Inspector in Node.js: Debugging and Profiling with the DevTools Protocol

1. Introduction

The inspector module can be accessed via require('node:inspector') or require('node:inspector/promises'). It enables communication with the V8 Inspector back-end and supports Chrome DevTools Protocol domains for runtime inspection and event listening.

2. Class: inspector.Session

• new inspector.Session(): Creates a new session instance.
• session.connect(): Connects to the inspector back-end.
• session.connectToMainThread(): Connects to the main thread inspector (for worker threads).
• session.disconnect(): Closes the session and clears inspector state.
• session.post(method[, params]): Sends commands to the inspector back-end (e.g., Runtime.evaluate).

3. Events

• inspectorNotification: Fired when any notification is received from the V8 Inspector.
• Specific events such as Debugger.paused can be listened to for breakpoints and execution suspension.

4. Profiling

• CPU Profiler: Enable with Profiler.enable, start with Profiler.start, and stop with Profiler.stop to capture CPU usage data.
• Heap Profiler: Use HeapProfiler.takeHeapSnapshot to capture memory usage and save snapshots for analysis.

5. Common Inspector Methods

• inspector.open([port, host, wait]): Activates the inspector on a given port and host.
• inspector.url(): Returns the active inspector’s URL.
• inspector.waitForDebugger(): Blocks execution until a debugger client connects.
• inspector.close(): Closes all connections and deactivates the inspector.

6. DevTools Integration

The Inspector can broadcast Chrome DevTools Protocol events such as Network.requestWillBeSent, Network.responseReceived, and Network.webSocketCreated. These events allow developers to monitor HTTP requests, responses, and WebSocket activity in real time.

7. Example

const inspector = require('node:inspector');
const session = new inspector.Session();
session.connect();

session.post('Runtime.evaluate', { expression: '2 + 2' }, 
             (err, { result }) => console.log(result));
// Output: { type: 'number', value: 4, description: '4' }

Conclusion

The inspector module in Node.js is a powerful tool for debugging and profiling. By connecting to the Chrome DevTools Protocol, developers can monitor runtime behavior, capture CPU and memory profiles, and inspect network activity, gaining deep insights into application performance and execution.