Node.js Inspector Module Guide

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

Basic Usage#

const inspector = require('inspector');

// Open inspector
inspector.open(9229, 'localhost', true);

// Get inspector URL
const url = inspector.url();
console.log(`Inspector URL: ${url}`);

// Close inspector
inspector.close();

// Check if inspector is active
if (inspector.url()) {
  console.log('Inspector is active');
}

// Wait for debugger to connect
inspector.open(9229, 'localhost', true);
inspector.waitForDebugger();
console.log('Debugger connected!');

Session API#

const inspector = require('inspector');

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

// Connect to inspector
session.connect();

// Enable domains
session.post('Debugger.enable', (err, result) => {
  if (err) console.error(err);
  console.log('Debugger enabled');
});

session.post('Runtime.enable', (err, result) => {
  if (err) console.error(err);
  console.log('Runtime enabled');
});

// Listen for events
session.on('Debugger.paused', (message) => {
  console.log('Paused at:', message.params.callFrames[0].location);
});

// Disconnect
session.disconnect();

CPU Profiling#

const inspector = require('inspector');
const fs = require('fs');

async function profile(duration = 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(
              'profile.cpuprofile',
              JSON.stringify(profile)
            );

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

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

// Usage
await profile(5000);
// Load profile.cpuprofile in Chrome DevTools

Heap Snapshot#

const inspector = require('inspector');
const fs = require('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.heapsnapshot', snapshot);

      console.log('Heap snapshot saved to heap.heapsnapshot');

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

// Usage
await takeHeapSnapshot();
// Load heap.heapsnapshot in Chrome DevTools Memory tab

Memory Profiling#

const inspector = require('inspector');

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

  // Enable heap profiler
  await new Promise((resolve, reject) => {
    session.post('HeapProfiler.enable', (err) => {
      err ? reject(err) : resolve();
    });
  });

  // Start sampling
  await new Promise((resolve, reject) => {
    session.post(
      'HeapProfiler.startSampling',
      { samplingInterval: 512 },
      (err) => {
        err ? reject(err) : resolve();
      }
    );
  });

  console.log('Heap profiling started');

  return {
    stop: async () => {
      return new Promise((resolve, reject) => {
        session.post('HeapProfiler.stopSampling', (err, result) => {
          if (err) return reject(err);

          const fs = require('fs');
          fs.writeFileSync(
            'heap-profile.heapprofile',
            JSON.stringify(result.profile)
          );

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

// Usage
const profiler = await startHeapProfiling();
// ... run your code ...
await profiler.stop();

Code Coverage#

const inspector = require('inspector');
const fs = require('fs');

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

  // Enable profiler and coverage
  await post(session, 'Profiler.enable');
  await post(session, 'Profiler.startPreciseCoverage', {
    callCount: true,
    detailed: true,
  });

  // Run the function
  await fn();

  // Get coverage data
  const { result } = await post(session, 'Profiler.takePreciseCoverage');

  // Disable and cleanup
  await post(session, 'Profiler.stopPreciseCoverage');
  await post(session, 'Profiler.disable');
  session.disconnect();

  // Filter to your source files
  const coverage = result.filter((script) =>
    script.url.startsWith('file://')
  );

  return coverage;
}

function post(session, method, params = {}) {
  return new Promise((resolve, reject) => {
    session.post(method, params, (err, result) => {
      err ? reject(err) : resolve(result);
    });
  });
}

// Usage
const coverage = await collectCoverage(async () => {
  require('./my-module.js');
});

console.log('Coverage:', JSON.stringify(coverage, null, 2));

Breakpoints#

const inspector = require('inspector');

async function setBreakpoint(scriptUrl, lineNumber) {
  const session = new inspector.Session();
  session.connect();

  await post(session, 'Debugger.enable');

  // Set breakpoint by URL
  const { breakpointId } = await post(session, 'Debugger.setBreakpointByUrl', {
    url: scriptUrl,
    lineNumber: lineNumber,
    columnNumber: 0,
  });

  console.log(`Breakpoint set: ${breakpointId}`);

  // Handle pause
  session.on('Debugger.paused', async (message) => {
    const frame = message.params.callFrames[0];
    console.log(`Paused at ${frame.url}:${frame.location.lineNumber}`);

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

  return { session, breakpointId };
}

// Remove breakpoint
async function removeBreakpoint(session, breakpointId) {
  await post(session, 'Debugger.removeBreakpoint', { breakpointId });
}

Evaluate Expressions#

const inspector = require('inspector');

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

  await post(session, 'Runtime.enable');

  const { result, exceptionDetails } = await post(session, 'Runtime.evaluate', {
    expression,
    returnByValue: true,
  });

  session.disconnect();

  if (exceptionDetails) {
    throw new Error(exceptionDetails.exception.description);
  }

  return result.value;
}

// Usage
const result = await evaluate('1 + 2 * 3');
console.log(result); // 7

const arr = await evaluate('[1, 2, 3].map(x => x * 2)');
console.log(arr); // [2, 4, 6]

Call Stack Inspection#

const inspector = require('inspector');

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

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

// Get current execution context
async function getContexts() {
  const session = new inspector.Session();
  session.connect();

  await post(session, 'Runtime.enable');

  const contexts = [];
  session.on('Runtime.executionContextCreated', ({ params }) => {
    contexts.push(params.context);
  });

  // Wait a bit for contexts
  await new Promise((resolve) => setTimeout(resolve, 100));

  session.disconnect();
  return contexts;
}

Wrapper Utility#

const inspector = require('inspector');
const fs = require('fs');

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

  async post(method, params = {}) {
    return new Promise((resolve, reject) => {
      this.session.post(method, params, (err, result) => {
        err ? reject(err) : resolve(result);
      });
    });
  }

  async cpuProfile(fn) {
    await this.post('Profiler.enable');
    await this.post('Profiler.start');

    await fn();

    const { profile } = await this.post('Profiler.stop');
    await this.post('Profiler.disable');

    return profile;
  }

  async heapSnapshot() {
    const chunks = [];

    this.session.on('HeapProfiler.addHeapSnapshotChunk', ({ params }) => {
      chunks.push(params.chunk);
    });

    await this.post('HeapProfiler.takeHeapSnapshot');

    return chunks.join('');
  }

  async coverage(fn) {
    await this.post('Profiler.enable');
    await this.post('Profiler.startPreciseCoverage', {
      callCount: true,
      detailed: true,
    });

    await fn();

    const { result } = await this.post('Profiler.takePreciseCoverage');
    await this.post('Profiler.stopPreciseCoverage');
    await this.post('Profiler.disable');

    return result;
  }

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

// Usage
const insp = new Inspector();

const profile = await insp.cpuProfile(async () => {
  // Code to profile
});

const snapshot = await insp.heapSnapshot();

insp.close();

Production Debugging#

const inspector = require('inspector');

// Enable inspector on signal
process.on('SIGUSR1', () => {
  if (inspector.url()) {
    console.log('Inspector already active:', inspector.url());
    return;
  }

  inspector.open(9229, '0.0.0.0', false);
  console.log('Inspector activated:', inspector.url());

  // Auto-close after 5 minutes
  setTimeout(() => {
    inspector.close();
    console.log('Inspector closed');
  }, 5 * 60 * 1000);
});

// Usage: kill -USR1 <pid>
console.log(`Send SIGUSR1 to PID ${process.pid} to enable inspector`);

Best Practices#

Usage:
✓ Use for profiling
✓ Use for heap snapshots
✓ Use for code coverage
✓ Enable dynamically in production

Performance:
✓ Profile in production-like env
✓ Take multiple samples
✓ Clean up sessions
✓ Limit inspector exposure

Security:
✓ Bind to localhost only
✓ Use authentication in production
✓ Auto-close after timeout
✓ Limit exposed functionality

Avoid:
✗ Leaving inspector open
✗ Exposing to network
✗ Heavy profiling in production
✗ Ignoring session cleanup

The inspector module provides powerful programmatic access to V8's debugging and profiling capabilities. Use it for CPU profiling, heap snapshots, code coverage, and dynamic debugging. Always handle sessions properly and be cautious about security when enabling inspector access in production environments.