Debugging Tools and Techniques

Overview

Debugging Tools and Techniques provide systematic approaches to finding and fixing bugs efficiently. Good debugging skills separate senior developers from juniors.

Core Principle: "Debugging is a science, not an art. Use tools, form hypotheses, test systematically."

---

1. Debugging Mindset

## The Scientific Method for Debugging

1. **Observe**: What is the actual behavior?
2. **Hypothesize**: What could cause this?
3. **Test**: How can I verify my hypothesis?
4. **Analyze**: Was my hypothesis correct?
5. **Repeat**: If not, form new hypothesis

### Example
**Bug**: User login fails with 500 error

1. **Observe**: Server returns 500, logs show "Cannot read property 'id' of undefined"
2. **Hypothesize**: User object is null/undefined
3. **Test**: Add console.log before accessing user.id
4. **Analyze**: User is undefined when email doesn't exist
5. **Fix**: Add null check before accessing user.id

---

2. Browser DevTools

Console Debugging

// Basic logging
console.log('User:', user);

// Structured logging
console.table([
  { name: 'Alice', age: 30 },
  { name: 'Bob', age: 25 }
]);

// Grouping
console.group('User Login');
console.log('Email:', email);
console.log('Password length:', password.length);
console.groupEnd();

// Timing
console.time('API Call');
await fetchUser();
console.timeEnd('API Call');

// Conditional logging
console.assert(user !== null, 'User should not be null');

// Stack trace
console.trace('How did we get here?');

Breakpoints

// Debugger statement
function processPayment(amount) {
  debugger;  // Execution pauses here
  
  if (amount > 1000) {
    // Complex logic
  }
}

// Conditional breakpoint (in DevTools)
// Right-click line number → Add conditional breakpoint
// Condition: amount > 1000

Network Tab

## Network Debugging Checklist

- [ ] Check request URL (correct endpoint?)
- [ ] Check request method (GET/POST/PUT/DELETE)
- [ ] Check request headers (auth token present?)
- [ ] Check request payload (correct data?)
- [ ] Check response status (200/400/500?)
- [ ] Check response body (expected data?)
- [ ] Check timing (slow requests?)
- [ ] Check CORS errors

---

3. VS Code Debugging

Launch Configuration

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Node.js",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/src/index.ts",
      "preLaunchTask": "tsc: build - tsconfig.json",
      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
      "env": {
        "NODE_ENV": "development"
      }
    },
    {
      "name": "Debug Jest Tests",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/.bin/jest",
      "args": ["--runInBand", "--no-cache"],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen"
    },
    {
      "name": "Attach to Process",
      "type": "node",
      "request": "attach",
      "port": 9229,
      "restart": true,
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

Debugging Features

// Logpoints (log without modifying code)
// Right-click line number → Add Logpoint
// Message: User ID: {user.id}, Email: {user.email}

// Watch expressions
// Add to Watch panel:
// - user.id
// - user.permissions.includes('admin')
// - Object.keys(user)

// Call stack inspection
// See how you got to current line

// Variable inspection
// Hover over variables to see values

---

4. Node.js Debugging

Built-in Debugger

# Start with inspector
node --inspect src/index.js

# Start and break immediately
node --inspect-brk src/index.js

# Custom port
node --inspect=9230 src/index.js

Chrome DevTools

# Start Node with inspector
node --inspect src/index.js

# Open Chrome
# Navigate to: chrome://inspect
# Click "inspect" under your process

Debug Logging

import debug from 'debug';

const log = debug('app:server');
const dbLog = debug('app:database');

log('Server starting on port %d', 3000);
dbLog('Connecting to database');

// Run with:
// DEBUG=app:* node src/index.js
// DEBUG=app:database node src/index.js

---

5. React Debugging

React DevTools

// Install React DevTools browser extension

// Component inspection
// - View props
// - View state
// - View hooks
// - View component tree

// Profiler
// - Record performance
// - Identify slow renders
// - Find unnecessary re-renders

Common React Bugs

// Bug: Infinite re-render
function BadComponent() {
  const [count, setCount] = useState(0);
  
  // ❌ This causes infinite loop
  setCount(count + 1);
  
  return <div>{count}</div>;
}

// Fix: Use useEffect
function GoodComponent() {
  const [count, setCount] = useState(0);
  
  useEffect(() => {
    setCount(count + 1);
  }, []);  // Empty deps = run once
  
  return <div>{count}</div>;
}

// Bug: Stale closure
function Counter() {
  const [count, setCount] = useState(0);
  
  useEffect(() => {
    const interval = setInterval(() => {
      // ❌ count is always 0 (stale closure)
      setCount(count + 1);
    }, 1000);
    
    return () => clearInterval(interval);
  }, []);
  
  // ✅ Fix: Use functional update
  useEffect(() => {
    const interval = setInterval(() => {
      setCount(c => c + 1);
    }, 1000);
    
    return () => clearInterval(interval);
  }, []);
}

---

6. Database Debugging

PostgreSQL

-- Enable query logging
ALTER SYSTEM SET log_statement = 'all';
SELECT pg_reload_conf();

-- Explain query plan
EXPLAIN ANALYZE
SELECT * FROM users WHERE email = 'test@example.com';

-- Find slow queries
SELECT query, mean_exec_time, calls
FROM pg_stat_statements
ORDER BY mean_exec_time DESC
LIMIT 10;

-- Active queries
SELECT pid, query, state, query_start
FROM pg_stat_activity
WHERE state = 'active';

Prisma Debugging

// Enable query logging
const prisma = new PrismaClient({
  log: ['query', 'info', 'warn', 'error'],
});

// Custom logging
const prisma = new PrismaClient({
  log: [
    {
      emit: 'event',
      level: 'query',
    },
  ],
});

prisma.$on('query', (e) => {
  console.log('Query: ' + e.query);
  console.log('Duration: ' + e.duration + 'ms');
});

---

7. API Debugging

cURL

# Basic request
curl https://api.example.com/users

# With headers
curl -H "Authorization: Bearer token123" \
     https://api.example.com/users

# POST with JSON
curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"email":"test@example.com"}' \
     https://api.example.com/users

# Verbose output
curl -v https://api.example.com/users

# Save response
curl https://api.example.com/users > response.json

Postman/Insomnia

## API Debugging Workflow

1. **Create Collection**: Organize related requests
2. **Environment Variables**: Store API URL, tokens
3. **Pre-request Scripts**: Generate auth tokens
4. **Tests**: Validate responses
5. **Mock Server**: Test without backend

HTTP Debugging Proxy

# Charles Proxy / Fiddler
# - Intercept all HTTP traffic
# - Modify requests/responses
# - Simulate slow network
# - Breakpoint on requests

---

8. Production Debugging

Logging Best Practices

import winston from 'winston';

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  defaultMeta: { service: 'user-service' },
  transports: [
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.File({ filename: 'combined.log' }),
  ],
});

// Structured logging
logger.info('User login', {
  userId: user.id,
  email: user.email,
  ip: req.ip,
  timestamp: new Date(),
});

// Error logging with context
try {
  await processPayment(order);
} catch (error) {
  logger.error('Payment failed', {
    error: error.message,
    stack: error.stack,
    orderId: order.id,
    userId: order.userId,
    amount: order.total,
  });
  throw error;
}

Error Tracking (Sentry)

import * as Sentry from '@sentry/node';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
  tracesSampleRate: 0.1,
});

// Capture exception with context
try {
  await processOrder(order);
} catch (error) {
  Sentry.captureException(error, {
    tags: {
      orderId: order.id,
      userId: order.userId,
    },
    extra: {
      orderData: order,
    },
  });
}

// Breadcrumbs
Sentry.addBreadcrumb({
  category: 'order',
  message: 'Order validation started',
  level: 'info',
});

---

9. Performance Debugging

Chrome Performance Tab

## Performance Profiling

1. Open DevTools → Performance tab
2. Click Record
3. Perform slow action
4. Stop recording
5. Analyze:
   - Long tasks (> 50ms)
   - Layout thrashing
   - Excessive re-renders
   - Memory leaks

Node.js Profiling

# CPU profiling
node --prof src/index.js

# Generate report
node --prof-process isolate-0x*.log > profile.txt

# Memory profiling
node --inspect src/index.js
# Open Chrome DevTools
# Take heap snapshot
# Compare snapshots to find leaks

Lighthouse

# Install
npm install -g lighthouse

# Run audit
lighthouse https://example.com --view

# CI integration
lighthouse https://example.com --output=json --output-path=./report.json

---

10. Debugging Checklist

# Debugging Checklist

## Before You Start
- [ ] Can you reproduce the bug consistently?
- [ ] What changed recently?
- [ ] Check error logs
- [ ] Check monitoring dashboards

## Investigation
- [ ] Read error message carefully
- [ ] Check stack trace
- [ ] Add logging around problem area
- [ ] Use debugger to step through code
- [ ] Check network requests
- [ ] Check database queries
- [ ] Verify environment variables
- [ ] Test in different environment

## Hypothesis Testing
- [ ] Form hypothesis about cause
- [ ] Design test to verify
- [ ] Run test
- [ ] Analyze results
- [ ] Repeat if needed

## After Fix
- [ ] Add test to prevent regression
- [ ] Update documentation
- [ ] Share learnings with team
- [ ] Consider monitoring/alerting

---

11. Common Debugging Scenarios

Scenario 1: "It works on my machine"

**Symptoms**: Works locally, fails in production

**Checklist**:
- [ ] Environment variables different?
- [ ] Node version different?
- [ ] Database data different?
- [ ] Network/firewall issues?
- [ ] Timezone differences?
- [ ] Case-sensitive file systems?

Scenario 2: Intermittent Failures

**Symptoms**: Bug appears randomly

**Checklist**:
- [ ] Race condition?
- [ ] Timing-dependent?
- [ ] Load-dependent?
- [ ] External service flakiness?
- [ ] Memory leak causing OOM?

Scenario 3: Performance Degradation

**Symptoms**: App getting slower over time

**Checklist**:
- [ ] Memory leak?
- [ ] Database query performance?
- [ ] Cache not working?
- [ ] Too many connections?
- [ ] Disk space full?

---

12. Debugging Tools Checklist

• Browser DevTools: Proficient with Console, Network, Debugger?
• VS Code Debugger: Launch configs set up?
• Logging: Structured logging implemented?
• Error Tracking: Sentry/similar configured?
• API Testing: Postman/Insomnia collections?
• Database Tools: Query debugging enabled?
• Performance Tools: Profiling tools available?
• Production Access: Can debug production safely?
• Documentation: Common issues documented?
• Team Knowledge: Debugging practices shared?

---

Related Skills

• 45-developer-experience/dev-environment-setup

• 45-developer-experience/hot-reload-fast-feedback

• 40-system-resilience/observability