Inspector

Owners: @nodejs/inspector.

Purpose

Implement the V8 Inspector protocol so that DevTools clients (Chrome DevTools, VS Code, IntelliJ, node inspect) can attach to a running Node process. The inspector lets users debug JS, profile CPU and heap, evaluate expressions in the running context, and (via Node-specific extensions) trace HTTP and worker-thread events.

Directory layout

src/
  inspector_agent.{cc,h}                    // Agent: high-level lifecycle
  inspector_io.{cc,h}                       // IO loop running on a separate thread
  inspector_socket.{cc,h}                   // WebSocket framing
  inspector_socket_server.{cc,h}            // listening / accept loop
  inspector_js_api.{cc,h}                   // exposes inspector.Session to JS
  inspector_profiler.{cc,h}                 // CPU and heap profilers
  inspector/
    main_thread_interface.{cc,h}            // bridges V8 inspector with main thread
    node_inspector_protocol_extensions/...  // Node-specific domains
    runtime_agent.{cc,h}                    // Runtime domain extension
    network_inspector.{cc,h}                // Node's network-tracking add-on
    tracing_agent.{cc,h}                    // trace_events bridge
    worker_inspector.{cc,h}                 // Worker thread integration
lib/
  inspector.js                              // user-facing module
  internal/inspector/
    network.js                              // Network domain
    network_undici.js                       // undici hookup
  internal/inspector_async_hook.js          // async stack capture
  internal/inspector_network_tracking.js    // public-ish hooks for fetch tracing
tools/inspector_protocol/                   // codegen for Inspector protocol JSON

Key abstractions

Type / file	Role
Agent (inspector_agent.cc)	Per-Environment owner of the inspector channel.
Session (lib/inspector.js)	In-process programmatic inspector channel.
IoThread (inspector_io.cc)	Runs the inspector's WebSocket loop on a dedicated thread.
MainThreadInterface (main_thread_interface.cc)	Bridges V8's inspector clients into the JS thread cleanly.
WorkerInspectorParent / Child (worker_inspector.{cc,h})	Cross-thread inspector forwarding.
Tracing/NetworkAgent (network_inspector.cc, tracing_agent.cc)	Node-specific protocol extensions.

Architecture

graph LR
    DevTools[DevTools client] --> WS[WebSocket :9229]
    WS --> Server[InspectorSocketServer]
    Server --> Io[Inspector IO thread]
    Io --> Main[MainThreadInterface]
    Main --> Agent[V8 Inspector Channel]
    Agent --> Iso[V8 Isolate]
    Agent --> NodeExt[Node protocol extensions]
    NodeExt --> tracing[trace_events]
    NodeExt --> net[Network domain]

The IO thread handles socket framing concurrently with JS execution. When a protocol message arrives that needs to interact with V8 (e.g. evaluate, set breakpoint), it is funneled through MainThreadInterface so it executes on the JS thread.

Programmatic use

require('inspector') exposes:

• inspector.open(port, host, wait) — start the agent (if not already started).
• inspector.close() — stop the agent.
• inspector.url() — returns the WebSocket URL clients connect to.
• inspector.waitForDebugger() — block until a client attaches (≥ Node 22).
• class Session — open an in-process inspector session that can drive Profiler.*, Debugger.*, Runtime.* programmatically without needing a remote client. Used by the test runner to collect coverage.

Worker support

Each Worker has its own Environment and its own inspector channel. WorkerInspectorParent and WorkerInspectorChild route messages between the parent's inspector router and the worker's. From a DevTools client this looks like multiple "Targets" attached to the same root URL.

CLI

Flag	Effect
--inspect[=host:port]	Start the agent, do not break.
--inspect-brk[=host:port]	Start the agent, break on the first line of user code.
--inspect-publish-uid=...	Where to publish the WebSocket URL (stderr, http, both).
--inspect-port=...	Override port without changing other flags.
--inspect-wait	Wait for a debugger to attach before continuing.

Permission model

The inspector permission domain (src/permission/inspector_permission.cc) gates Agent::Start. Without a grant, --inspect is rejected.

Entry points for modification

• Add a new Node protocol domain? Generate the codegen via tools/inspector_protocol/, expose handlers in src/inspector/, and document at doc/api/inspector.md.
• Bug in attach / detach? Agent::Start/Stop and MainThreadInterface.
• Bug in the JS Session? lib/inspector.js and src/inspector_js_api.cc.