Node.js inspector Module Guide

The inspector module provides an API for interacting with the V8 inspector, enabling debugging, profiling, and runtime analysis. Here's how to use it.

Basic Setup#

import inspector from 'node:inspector';

// Open inspector on default port (9229)
inspector.open();

// Open on specific port
inspector.open(9230);

// Open with host binding
inspector.open(9229, 'localhost');

// Wait for debugger to attach
inspector.open(9229, 'localhost', true);

// Check if inspector is active
console.log('Inspector active:', inspector.url());

// Close inspector
inspector.close();

Session API#

import inspector from 'node:inspector';

// Create a new session
const session = new inspector.Session();

// Connect to the inspector
session.connect();

// Send commands
session.post('Runtime.enable', (err) => {
  if (err) console.error(err);
});

// Receive events
session.on('Runtime.consoleAPICalled', (message) => {
  console.log('Console called:', message);
});

// Disconnect when done
session.disconnect();

CPU Profiling#

import inspector from 'node:inspector';
import fs from 'node:fs';

async function profileCPU(durationMs = 5000) {
  const session = new inspector.Session();
  session.connect();

  return new Promise((resolve, reject) => {
    // Enable profiler
    session.post('Profiler.enable', (err) => {
      if (err) return reject(err);

      // Start profiling
      session.post('Profiler.start', (err) => {
        if (err) return reject(err);

        console.log('Profiling started...');

        // Stop after duration
        setTimeout(() => {
          session.post('Profiler.stop', (err, { profile }) => {
            if (err) return reject(err);

            // Save profile
            fs.writeFileSync(
              'cpu-profile.cpuprofile',
              JSON.stringify(profile)
            );

            console.log('Profile saved to cpu-profile.cpuprofile');

            session.disconnect();
            resolve(profile);
          });
        }, durationMs);
      });
    });
  });
}

// Usage
await profileCPU(5000);

Heap Snapshot#

import inspector from 'node:inspector';
import fs from 'node:fs';

async function takeHeapSnapshot() {
  const session = new inspector.Session();
  session.connect();

  const chunks = [];

  return new Promise((resolve, reject) => {
    session.on('HeapProfiler.addHeapSnapshotChunk', (message) => {
      chunks.push(message.params.chunk);
    });

    session.post('HeapProfiler.takeHeapSnapshot', null, (err) => {
      if (err) return reject(err);

      const snapshot = chunks.join('');
      fs.writeFileSync('heap-snapshot.heapsnapshot', snapshot);

      console.log('Heap snapshot saved');

      session.disconnect();
      resolve(snapshot);
    });
  });
}

// Take snapshots to find memory leaks
async function findMemoryLeak() {
  console.log('Taking initial snapshot...');
  await takeHeapSnapshot();

  // Run code that might leak
  await runPotentiallyLeakyCode();

  console.log('Taking second snapshot...');
  await takeHeapSnapshot();

  console.log('Compare snapshots in Chrome DevTools');
}

Heap Profiling#

import inspector from 'node:inspector';
import fs from 'node:fs';

async function profileHeapAllocation(durationMs = 5000) {
  const session = new inspector.Session();
  session.connect();

  return new Promise((resolve, reject) => {
    session.post('HeapProfiler.enable', (err) => {
      if (err) return reject(err);

      // Start sampling
      session.post(
        'HeapProfiler.startSampling',
        { samplingInterval: 32768 },
        (err) => {
          if (err) return reject(err);

          console.log('Heap profiling started...');

          setTimeout(() => {
            session.post('HeapProfiler.stopSampling', (err, { profile }) => {
              if (err) return reject(err);

              fs.writeFileSync(
                'heap-profile.heapprofile',
                JSON.stringify(profile)
              );

              console.log('Heap profile saved');

              session.disconnect();
              resolve(profile);
            });
          }, durationMs);
        }
      );
    });
  });
}

Code Coverage#

import inspector from 'node:inspector';

async function collectCoverage(fn) {
  const session = new inspector.Session();
  session.connect();

  return new Promise((resolve, reject) => {
    // Enable profiler and debugger
    session.post('Profiler.enable', (err) => {
      if (err) return reject(err);

      // Start precise coverage
      session.post(
        'Profiler.startPreciseCoverage',
        { callCount: true, detailed: true },
        async (err) => {
          if (err) return reject(err);

          // Run the function
          await fn();

          // Get coverage
          session.post('Profiler.takePreciseCoverage', (err, { result }) => {
            if (err) return reject(err);

            // Stop coverage
            session.post('Profiler.stopPreciseCoverage', () => {
              session.disconnect();
              resolve(result);
            });
          });
        }
      );
    });
  });
}

// Usage
const coverage = await collectCoverage(async () => {
  // Code to measure coverage for
  await runTests();
});

console.log('Coverage:', coverage);

Runtime Evaluation#

import inspector from 'node:inspector';

function createEvaluator() {
  const session = new inspector.Session();
  session.connect();

  session.post('Runtime.enable');

  return {
    evaluate(expression) {
      return new Promise((resolve, reject) => {
        session.post(
          'Runtime.evaluate',
          {
            expression,
            returnByValue: true,
          },
          (err, result) => {
            if (err) return reject(err);
            resolve(result.result.value);
          }
        );
      });
    },

    close() {
      session.disconnect();
    },
  };
}

// Usage
const evaluator = createEvaluator();

const result = await evaluator.evaluate('1 + 2 + 3');
console.log('Result:', result); // 6

const globals = await evaluator.evaluate('Object.keys(globalThis)');
console.log('Globals:', globals);

evaluator.close();

Breakpoint Management#

import inspector from 'node:inspector';

function setupDebugger(scriptPath) {
  const session = new inspector.Session();
  session.connect();

  session.post('Debugger.enable');

  // Set breakpoint
  session.post('Debugger.setBreakpointByUrl', {
    lineNumber: 10,
    url: scriptPath,
  });

  // Handle breakpoint hit
  session.on('Debugger.paused', (message) => {
    console.log('Paused at:', message.params.callFrames[0].location);

    // Get local variables
    const scopeChain = message.params.callFrames[0].scopeChain;
    for (const scope of scopeChain) {
      session.post(
        'Runtime.getProperties',
        { objectId: scope.object.objectId },
        (err, result) => {
          if (!err) {
            console.log('Variables:', result.result);
          }
        }
      );
    }

    // Resume execution
    session.post('Debugger.resume');
  });

  return session;
}

Async Stack Traces#

import inspector from 'node:inspector';

function enableAsyncStackTraces() {
  const session = new inspector.Session();
  session.connect();

  session.post('Debugger.enable');
  session.post('Debugger.setAsyncCallStackDepth', { maxDepth: 32 });

  return session;
}

// Now async stack traces will show full call chain

Memory Monitoring#

import inspector from 'node:inspector';
import v8 from 'node:v8';

function monitorMemory(intervalMs = 1000) {
  const session = new inspector.Session();
  session.connect();

  session.post('Runtime.enable');

  const stats = [];

  const interval = setInterval(() => {
    const heapStats = v8.getHeapStatistics();

    session.post('Runtime.getHeapUsage', (err, result) => {
      if (!err) {
        stats.push({
          timestamp: Date.now(),
          heapUsed: heapStats.used_heap_size,
          heapTotal: heapStats.total_heap_size,
          external: heapStats.external_memory,
          ...result,
        });

        console.log('Memory:', {
          used: `${(heapStats.used_heap_size / 1024 / 1024).toFixed(2)} MB`,
          total: `${(heapStats.total_heap_size / 1024 / 1024).toFixed(2)} MB`,
        });
      }
    });
  }, intervalMs);

  return {
    stop() {
      clearInterval(interval);
      session.disconnect();
      return stats;
    },
  };
}

// Usage
const monitor = monitorMemory(1000);

// Later...
const memoryStats = monitor.stop();

Profiling Wrapper#

import inspector from 'node:inspector';
import fs from 'node:fs';

class Profiler {
  constructor() {
    this.session = new inspector.Session();
    this.session.connect();
  }

  async startCPUProfile() {
    return new Promise((resolve, reject) => {
      this.session.post('Profiler.enable', (err) => {
        if (err) return reject(err);
        this.session.post('Profiler.start', (err) => {
          if (err) return reject(err);
          resolve();
        });
      });
    });
  }

  async stopCPUProfile(filename = 'profile.cpuprofile') {
    return new Promise((resolve, reject) => {
      this.session.post('Profiler.stop', (err, { profile }) => {
        if (err) return reject(err);
        fs.writeFileSync(filename, JSON.stringify(profile));
        resolve(profile);
      });
    });
  }

  async profileFunction(fn, filename) {
    await this.startCPUProfile();
    const startTime = Date.now();

    try {
      await fn();
    } finally {
      const profile = await this.stopCPUProfile(filename);
      const duration = Date.now() - startTime;
      console.log(`Profiled in ${duration}ms, saved to ${filename}`);
      return profile;
    }
  }

  close() {
    this.session.disconnect();
  }
}

// Usage
const profiler = new Profiler();
await profiler.profileFunction(async () => {
  // Code to profile
  await heavyComputation();
}, 'computation.cpuprofile');
profiler.close();

Best Practices#

Profiling:
✓ Profile in production-like environment
✓ Use sampling for long runs
✓ Take multiple snapshots
✓ Compare before/after

Debugging:
✓ Use conditional breakpoints
✓ Enable async stack traces
✓ Inspect scope chain
✓ Monitor memory usage

Performance:
✓ Disable when not needed
✓ Use appropriate sample intervals
✓ Clean up sessions
✓ Avoid in production

Avoid:
✗ Leaving inspector open in production
✗ Taking snapshots too frequently
✗ Ignoring session cleanup
✗ Profiling with debugger attached

The Node.js inspector module provides powerful tools for debugging and profiling. Use it for CPU profiling to find performance bottlenecks, heap snapshots to diagnose memory leaks, and code coverage for testing. Create wrapper utilities for common profiling tasks and remember to properly clean up sessions. For production debugging, consider using the inspector URL to connect Chrome DevTools remotely.