Node.js Debugging Techniques

Effective debugging saves development time. Here's how to debug Node.js applications.

Console Methods#

// Basic logging
console.log('Value:', value);
console.error('Error:', error);
console.warn('Warning:', warning);

// Table format
const users = [
  { id: 1, name: 'John', age: 30 },
  { id: 2, name: 'Jane', age: 25 },
];
console.table(users);
// ┌─────────┬────┬────────┬─────┐
// │ (index) │ id │  name  │ age │
// ├─────────┼────┼────────┼─────┤
// │    0    │ 1  │ 'John' │ 30  │
// │    1    │ 2  │ 'Jane' │ 25  │
// └─────────┴────┴────────┴─────┘

// Grouping
console.group('User Processing');
console.log('Step 1: Validate');
console.log('Step 2: Transform');
console.log('Step 3: Save');
console.groupEnd();

// Timing
console.time('operation');
await someOperation();
console.timeEnd('operation');
// operation: 123.456ms

// Count calls
function processItem(item) {
  console.count('processItem called');
  // ...
}

// Trace stack
console.trace('Trace point');

// Assert
console.assert(value > 0, 'Value must be positive');

// Clear
console.clear();

// Dir for objects
console.dir(complexObject, { depth: null, colors: true });

Debugger Statement#

// Pause execution when debugger attached
function processData(data) {
  debugger; // Execution pauses here
  const result = transform(data);
  return result;
}

// Run with inspect
// node --inspect app.js
// node --inspect-brk app.js  // Break at start

// Open in Chrome DevTools
// chrome://inspect

VS Code Debugging#

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "program": "${workspaceFolder}/src/index.ts",
      "preLaunchTask": "tsc: build",
      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
      "console": "integratedTerminal"
    },
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Tests",
      "program": "${workspaceFolder}/node_modules/jest/bin/jest",
      "args": ["--runInBand", "--watchAll=false"],
      "console": "integratedTerminal"
    },
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to Process",
      "port": 9229,
      "restart": true
    }
  ]
}

// Conditional breakpoints
// Right-click breakpoint in VS Code
// Expression: user.id === '123'

// Logpoints (like console.log without modifying code)
// Right-click line number -> Add Logpoint
// Message: "User: {user.name}, Status: {status}"

Error Stack Traces#

// Capture stack trace
function captureStack() {
  const err = new Error();
  return err.stack;
}

// Async stack traces
// node --async-stack-traces app.js

// Custom error with stack
class AppError extends Error {
  constructor(message, code) {
    super(message);
    this.name = 'AppError';
    this.code = code;
    Error.captureStackTrace(this, AppError);
  }
}

// Clean stack traces
function cleanStack(stack) {
  return stack
    .split('\n')
    .filter(line => !line.includes('node_modules'))
    .join('\n');
}

// Source maps for TypeScript
// tsconfig.json: "sourceMap": true
// node --enable-source-maps dist/app.js

Memory Debugging#

// Memory usage
const used = process.memoryUsage();
console.log({
  rss: `${Math.round(used.rss / 1024 / 1024)} MB`,       // Total memory
  heapTotal: `${Math.round(used.heapTotal / 1024 / 1024)} MB`,
  heapUsed: `${Math.round(used.heapUsed / 1024 / 1024)} MB`,
  external: `${Math.round(used.external / 1024 / 1024)} MB`,
});

// Heap snapshot
const v8 = require('v8');
const fs = require('fs');

function takeHeapSnapshot() {
  const filename = `heap-${Date.now()}.heapsnapshot`;
  const snapshotStream = v8.writeHeapSnapshot(filename);
  console.log(`Heap snapshot written to ${filename}`);
}

// Trigger with signal
process.on('SIGUSR2', takeHeapSnapshot);

// Heap dump on memory limit
const MEMORY_LIMIT = 500 * 1024 * 1024; // 500MB

setInterval(() => {
  const { heapUsed } = process.memoryUsage();
  if (heapUsed > MEMORY_LIMIT) {
    takeHeapSnapshot();
    console.error('Memory limit exceeded');
  }
}, 30000);

// Detect memory leaks
// npm install memwatch-next
const memwatch = require('memwatch-next');

memwatch.on('leak', (info) => {
  console.error('Memory leak detected:', info);
});

Performance Profiling#

// CPU profiling
const inspector = require('inspector');
const session = new inspector.Session();
session.connect();

function startProfiling() {
  session.post('Profiler.enable');
  session.post('Profiler.start');
}

function stopProfiling() {
  session.post('Profiler.stop', (err, { profile }) => {
    if (err) return console.error(err);
    fs.writeFileSync(
      `profile-${Date.now()}.cpuprofile`,
      JSON.stringify(profile)
    );
  });
}

// Command line profiling
// node --prof app.js
// node --prof-process isolate-*.log > processed.txt

// Clinic.js for analysis
// npm install -g clinic
// clinic doctor -- node app.js
// clinic flame -- node app.js
// clinic bubbleprof -- node app.js

// perf_hooks
const { performance, PerformanceObserver } = require('perf_hooks');

const obs = new PerformanceObserver((items) => {
  items.getEntries().forEach((entry) => {
    console.log(`${entry.name}: ${entry.duration}ms`);
  });
});
obs.observe({ entryTypes: ['measure'] });

performance.mark('start');
await doWork();
performance.mark('end');
performance.measure('work', 'start', 'end');

Async Debugging#

// Async hooks for tracking
const asyncHooks = require('async_hooks');

const asyncStorage = new Map();

const hook = asyncHooks.createHook({
  init(asyncId, type, triggerAsyncId) {
    asyncStorage.set(asyncId, {
      type,
      triggerAsyncId,
      stack: new Error().stack,
    });
  },
  destroy(asyncId) {
    asyncStorage.delete(asyncId);
  },
});

hook.enable();

// Track unhandled rejections
process.on('unhandledRejection', (reason, promise) => {
  console.error('Unhandled Rejection:', reason);
  console.error('Promise:', promise);
});

// Long stack traces
// node --async-stack-traces app.js
async function main() {
  await step1();
  await step2();
  await step3(); // Error here shows full async trace
}

HTTP Debugging#

// Debug HTTP requests
const http = require('http');

const originalRequest = http.request;
http.request = function(options, callback) {
  console.log('HTTP Request:', {
    method: options.method || 'GET',
    host: options.host || options.hostname,
    path: options.path,
  });
  return originalRequest.apply(this, arguments);
};

// Using debug module
// DEBUG=express:* node app.js
const debug = require('debug')('app:http');
debug('Request received: %s %s', req.method, req.url);

// Request timing
app.use((req, res, next) => {
  const start = Date.now();

  res.on('finish', () => {
    const duration = Date.now() - start;
    console.log(`${req.method} ${req.url} - ${res.statusCode} - ${duration}ms`);
  });

  next();
});

Production Debugging#

// Structured logging
const pino = require('pino');
const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
  formatters: {
    level: (label) => ({ level: label }),
  },
});

logger.info({ userId: user.id, action: 'login' }, 'User logged in');
logger.error({ err, requestId }, 'Request failed');

// Error tracking
const Sentry = require('@sentry/node');
Sentry.init({ dsn: process.env.SENTRY_DSN });

process.on('uncaughtException', (error) => {
  Sentry.captureException(error);
  process.exit(1);
});

// Remote debugging
// node --inspect=0.0.0.0:9229 app.js
// Use SSH tunnel for production
// ssh -L 9229:localhost:9229 user@server

Debugging Tips#

# Run with verbose output
NODE_DEBUG=http,net node app.js

# Increase stack trace limit
node --stack-trace-limit=100 app.js

# Trace warnings
node --trace-warnings app.js

# Trace deprecations
node --trace-deprecation app.js

# Print V8 options
node --v8-options | grep -i debug

Best Practices#

Development:
✓ Use VS Code debugger
✓ Set meaningful breakpoints
✓ Use conditional breakpoints
✓ Enable source maps

Logging:
✓ Use structured logging
✓ Include context (request IDs)
✓ Log at appropriate levels
✓ Don't log sensitive data

Production:
✓ Set up error tracking
✓ Use proper logging service
✓ Monitor memory and CPU
✓ Enable remote debugging carefully

Effective debugging combines multiple techniques: console methods for quick checks, debuggers for stepping through code, profilers for performance issues, and proper logging for production. Master VS Code debugging, use Chrome DevTools for profiling, and set up robust error tracking for production applications.