Debugging tool usage

The Importance of Debugging Tools

In Node.js development, debugging tools are crucial for identifying and resolving issues. Whether it's tracing asynchronous call stacks, analyzing memory leaks, or identifying performance bottlenecks, the right debugging tools can significantly improve development efficiency. Common debugging methods include built-in debuggers, Chrome DevTools, VS Code debuggers, and third-party tools like ndb.

Node.js Built-in Debugger

Node.js comes with basic debugging functionality, which can be activated using the --inspect flag:

node --inspect app.js

This starts a debugging server, defaulting to port 9229. More detailed parameters include:

• --inspect-brk: Breaks at the first line of code
• --inspect-port: Specifies a port number
• --inspect=[host:port]: Customizes the host and port

Basic commands available during debugging:

• cont/c: Continue execution
• next/n: Step over
• step/s: Step into
• out/o: Step out
• pause: Pause execution

// Example: Debugging an async function
async function fetchData() {
  const response = await fetch('https://api.example.com/data'); // Breakpoint location
  const data = await response.json();
  console.log(data);
}

Chrome DevTools Integration

Access the remote debugging interface via chrome://inspect:

1. Ensure the Node.js process is running with the --inspect flag
2. Open Chrome and navigate to chrome://inspect
3. Locate the target script under "Remote Targets"
4. Click "inspect" to open the full debugging interface

Debugging features include:

• Source code viewing and breakpoint setting
• Call stack tracing
• Scope variable inspection
• Performance profiler
• Memory heap snapshots

// Memory leak example
const leaks = [];
setInterval(() => {
  leaks.push(new Array(1000).fill('*'));
}, 100);

VS Code Debug Configuration

Typical .vscode/launch.json configuration:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "skipFiles": ["<node_internals>/**"],
      "program": "${workspaceFolder}/app.js",
      "outFiles": ["${workspaceFolder}/**/*.js"]
    }
  ]
}

Advanced debugging techniques:

• Conditional breakpoints: Right-click a breakpoint to set triggering conditions
• Logpoints: Output logs without interrupting execution
• Function breakpoints: Add directly in the call stack panel
• Multi-target debugging: Debug both main and child processes simultaneously

// Conditional breakpoint example
for (let i = 0; i < 100; i++) {
  // Set condition to trigger when i > 90
  console.log(i);
}

Third-Party Debugging Tools

ndb Debugger

Installation and usage:

npm install -g ndb
ndb app.js

Features:

• Improved breakpoint management
• Better async stack traces
• Integrated console output
• Automatic attachment to forked processes

node-inspect

Legacy command-line debugger:

node inspect app.js

Provides a GDB-like interactive interface, suitable for GUI-less environments.

Performance Analysis Tools

CPU profiling:

node --cpu-prof app.js

Generates isolate-0xnnnnnnnnnnnn-v8.log, analyzable with Chrome DevTools' JavaScript Profiler.

Heap memory analysis:

node --heapsnapshot-signal=SIGUSR2 app.js

Trigger a snapshot with kill -USR2 <pid>, generating Heap.${Date.now()}.heapsnapshot files.

// Memory analysis example
class Cache {
  constructor() {
    this.store = new Map();
  }
  add(key, value) {
    this.store.set(key, value);
  }
}

const cache = new Cache();
setInterval(() => {
  cache.add(Date.now(), new Array(1000000));
}, 10);

Debugging Tips and Practices

Async Stack Traces

Enhance async error stacks with --async-stack-traces:

node --async-stack-traces app.js

// Async error example
async function processData() {
  await new Promise((resolve) => {
    setTimeout(() => {
      throw new Error('Async error');
    }, 100);
  });
}

REPL Debugging

Insert repl to start an interactive session:

const repl = require('repl');

function debugContext() {
  const r = repl.start('debug> ');
  r.context.app = app; // Expose current context
}

Debugging Child Processes

Child process debug configuration:

{
  "type": "node",
  "request": "attach",
  "name": "Attach to Child",
  "port": 9230,
  "restart": true
}

Parent process code:

const { fork } = require('child_process');
const child = fork('child.js', [], {
  execArgv: ['--inspect=9230']
});

Common Issue Troubleshooting

Breakpoints Not Triggering

Possible causes and solutions:

1. Source map issues: Ensure outFiles is correctly configured
2. Code optimization: Disable JIT optimization with --jitless
3. File path issues: Use absolute paths

Debugger Connection Failures

Checklist:

1. Verify the debug port is not occupied
2. Check firewall settings
3. Validate host configuration (especially in Docker environments)

Memory Analysis Techniques

Typical memory issue indicators:

• Heap grows continuously without release
• Large numbers of duplicate objects
• Unexpectedly large object retention

Use comparison to analyze multiple snapshots and identify growth points.

Advanced Debugging Scenarios

TypeScript Debugging

Configuration example:

{
  "type": "node",
  "request": "launch",
  "runtimeExecutable": "ts-node",
  "args": ["${workspaceFolder}/src/index.ts"],
  "sourceMaps": true,
  "outFiles": ["${workspaceFolder}/dist/**/*.js"]
}

Debugging Electron Main Process

Special configuration:

{
  "type": "node",
  "request": "launch",
  "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron",
  "runtimeArgs": ["--remote-debugging-port=9222", "."],
  "windows": {
    "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron.cmd"
  }
}

Debugging in Containers

Docker debug configuration:

FROM node:14
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 9229
CMD ["node", "--inspect=0.0.0.0:9229", "app.js"]

Run command:

docker run -p 3000:3000 -p 9229:9229 -it my-app

Performance Optimization Debugging

CPU Bottleneck Identification

Generate logs with --prof:

node --prof app.js

Analyze with --prof-process:

node --prof-process isolate-0xnnnnnnnnnnnn-v8.log > processed.txt

Key metrics:

• ticks: Sample count
• Optimization/deoptimization counts
• Function call percentages

Event Loop Latency Detection

Measure with perf_hooks:

const { monitorEventLoopDelay } = require('perf_hooks');

const histogram = monitorEventLoopDelay();
histogram.enable();

setInterval(() => {
  console.log(`EventLoop latency: 
    P50: ${histogram.percentile(50)}ms
    P99: ${histogram.percentile(99)}ms`);
  histogram.reset();
}, 1000);

Debugging Toolchain Integration

Integration with Testing Frameworks

Jest debug configuration:

{
  "type": "node",
  "request": "launch",
  "name": "Jest Tests",
  "program": "${workspaceFolder}/node_modules/jest/bin/jest",
  "args": ["--runInBand"],
  "console": "integratedTerminal"
}

Combining Logs and Debugging

Structured logging example:

const util = require('util');
const debug = util.debuglog('app');

function processRequest(req) {
  debug('Processing request %O', req.headers);
  // ...
}

Control via environment variables:

NODE_DEBUG=app node server.js

Debugging Tool Extensions

Custom Debug Clients

Inspector API example:

const { Session } = require('inspector');
const session = new Session();
session.connect();

session.post('Debugger.enable', () => {
  session.post('Debugger.setBreakpointByUrl', {
    lineNumber: 10,
    url: 'app.js'
  });
});

session.on('Debugger.paused', (event) => {
  console.log('Paused on:', event.params.callFrames[0].location);
  session.post('Debugger.resume');
});

Visual Debugging Tools

Memory visualization with Heap.js:

const { Heap } = require('heap-js');

const heap = new Heap();
heap.init();

setInterval(() => {
  const snapshot = heap.takeSnapshot();
  console.log(snapshot.getNodeCount());
}, 5000);