nodejs-profiling

You are nodejs-profiling - a specialized skill for Node.js runtime profiling and optimization. This skill provides expert capabilities for analyzing Node.js application performance including CPU profiling, memory analysis, event loop debugging, and V8 optimization.

Overview

This skill enables AI-powered Node.js profiling including:

• Using V8 CPU profiler for hot path identification
• Analyzing heap snapshots for memory leaks
• Configuring clinic.js tools (Doctor, Flame, Bubbleprof)
• Debugging event loop blocking and delays
• Profiling async operations with async_hooks
• Optimizing V8 JIT compilation
• Profiling native addons

Prerequisites

• Node.js 16+ (18+ or 20+ recommended)
• npm/yarn for package management
• clinic.js: npm install -g clinic
• Optional: 0x for flame graphs, heapdump for snapshots

Capabilities

1. V8 CPU Profiling

Profile CPU usage using V8's built-in profiler:

javascript
// cpu-profile.js - Programmatic CPU profiling
const v8Profiler = require('v8-profiler-next');
const fs = require('fs');

// Start profiling
v8Profiler.setGenerateType(1); // Generate call tree
v8Profiler.startProfiling('cpu-profile', true);

// Run your workload
await runWorkload();

// Stop and save profile
const profile = v8Profiler.stopProfiling('cpu-profile');
const profileData = profile.export();

fs.writeFileSync('cpu-profile.cpuprofile', JSON.stringify(profileData));
profile.delete();

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

bash
# Using Node.js built-in profiler
node --prof app.js
node --prof-process isolate-0x*.log > processed.txt

# Generate V8 log for analysis
node --trace-opt --trace-deopt app.js 2>&1 | grep -E "(opt|deopt)"

# Run with inspector for Chrome DevTools profiling
node --inspect app.js
# Then open chrome://inspect in Chrome

2. Heap Snapshot Analysis

Capture and analyze heap snapshots:

javascript
// heap-analysis.js
const v8 = require('v8');
const fs = require('fs');

// Take heap snapshot
function takeHeapSnapshot(filename) {
  const snapshotStream = v8.writeHeapSnapshot(filename);
  console.log(`Heap snapshot written to ${snapshotStream}`);
  return snapshotStream;
}

// Memory usage tracking
function trackMemory() {
  const usage = process.memoryUsage();
  return {
    heapUsed: `${(usage.heapUsed / 1024 / 1024).toFixed(2)} MB`,
    heapTotal: `${(usage.heapTotal / 1024 / 1024).toFixed(2)} MB`,
    external: `${(usage.external / 1024 / 1024).toFixed(2)} MB`,
    rss: `${(usage.rss / 1024 / 1024).toFixed(2)} MB`,
    arrayBuffers: `${(usage.arrayBuffers / 1024 / 1024).toFixed(2)} MB`
  };
}

// Heap statistics
function getHeapStats() {
  const stats = v8.getHeapStatistics();
  return {
    totalHeapSize: `${(stats.total_heap_size / 1024 / 1024).toFixed(2)} MB`,
    usedHeapSize: `${(stats.used_heap_size / 1024 / 1024).toFixed(2)} MB`,
    heapSizeLimit: `${(stats.heap_size_limit / 1024 / 1024).toFixed(2)} MB`,
    mallocedMemory: `${(stats.malloced_memory / 1024 / 1024).toFixed(2)} MB`,
    peakMallocedMemory: `${(stats.peak_malloced_memory / 1024 / 1024).toFixed(2)} MB`
  };
}

// Trigger garbage collection (requires --expose-gc flag)
function forceGC() {
  if (global.gc) {
    global.gc();
    console.log('Garbage collection triggered');
  } else {
    console.warn('Run with --expose-gc to enable manual GC');
  }
}

3. Clinic.js Tools

Use clinic.js suite for comprehensive analysis:

bash
# Clinic Doctor - Overall health check
clinic doctor -- node app.js
# Generates: .clinic/xxx.clinic-doctor

# Clinic Flame - CPU flame graphs
clinic flame -- node app.js
# Generates: .clinic/xxx.clinic-flame

# Clinic Bubbleprof - Async operations visualization
clinic bubbleprof -- node app.js
# Generates: .clinic/xxx.clinic-bubbleprof

# Clinic Heap Profiler - Memory analysis
clinic heapprofiler -- node app.js
# Generates: .clinic/xxx.clinic-heapprofiler

# Run with specific workload
clinic flame --autocannon [ /api/users -- -c 10 -d 30 ] -- node app.js

# Analyze specific endpoint
clinic bubbleprof --autocannon [ /api/slow-endpoint -c 5 -d 60 ] -- node server.js

javascript
// Using clinic programmatically
const ClinicDoctor = require('@clinic/doctor');
const doctor = new ClinicDoctor();

doctor.collect(['node', 'app.js'], (err, filepath) => {
  if (err) throw err;

  doctor.visualize(filepath, filepath + '.html', (err) => {
    if (err) throw err;
    console.log(`Report: ${filepath}.html`);
  });
});

4. Event Loop Analysis

Debug event loop blocking and delays:

javascript
// event-loop-monitor.js
const { monitorEventLoopDelay } = require('perf_hooks');

// Create histogram for event loop delay
const h = monitorEventLoopDelay({ resolution: 20 });
h.enable();

// Periodic reporting
setInterval(() => {
  console.log('Event Loop Delay:');
  console.log(`  Min: ${h.min / 1e6} ms`);
  console.log(`  Max: ${h.max / 1e6} ms`);
  console.log(`  Mean: ${h.mean / 1e6} ms`);
  console.log(`  P50: ${h.percentile(50) / 1e6} ms`);
  console.log(`  P99: ${h.percentile(99) / 1e6} ms`);
  h.reset();
}, 5000);

// Detect blocking operations
const blocked = require('blocked-at');
blocked((time, stack, { type, resource }) => {
  console.warn(`Event loop blocked for ${time}ms`);
  console.warn(`Type: ${type}`);
  console.warn(`Stack:\n${stack.join('\n')}`);
}, { threshold: 100, resourcesCap: 100 });

javascript
// Async operation timing
const async_hooks = require('async_hooks');
const { performance, PerformanceObserver } = require('perf_hooks');

// Track async operation durations
const asyncTiming = new Map();

const hook = async_hooks.createHook({
  init(asyncId, type, triggerAsyncId) {
    asyncTiming.set(asyncId, {
      type,
      start: performance.now(),
      triggerAsyncId
    });
  },
  destroy(asyncId) {
    const timing = asyncTiming.get(asyncId);
    if (timing) {
      const duration = performance.now() - timing.start;
      if (duration > 100) { // Log slow operations
        console.log(`Slow async: ${timing.type} took ${duration.toFixed(2)}ms`);
      }
      asyncTiming.delete(asyncId);
    }
  }
});

hook.enable();

5. Flame Graph Generation

Generate flame graphs for CPU analysis:

bash
# Using 0x
npm install -g 0x
0x -o app.js
# Opens flame graph in browser

# Using perf and FlameGraph (Linux)
perf record -F 99 -g -- node app.js
perf script | ./stackcollapse-perf.pl | ./flamegraph.pl > flame.svg

# Using node --perf-basic-prof
node --perf-basic-prof app.js &
perf record -F 99 -p $! -g -- sleep 30
perf script | ./stackcollapse-perf.pl | ./flamegraph.pl > flame.svg

6. V8 Optimization Analysis

Analyze V8 JIT optimization:

bash
# Trace optimizations and deoptimizations
node --trace-opt --trace-deopt app.js 2>&1 | tee opt.log

# Analyze inline caches
node --trace-ic app.js 2>&1 | tee ic.log

# Check for hidden class transitions
node --allow-natives-syntax -e "
  function Point(x, y) { this.x = x; this.y = y; }
  const p = new Point(1, 2);
  %DebugPrint(p);
  %HaveSameMap(new Point(1,2), p);
"

# Detailed V8 flags
node --v8-options | grep -i "optimize"

javascript
// Optimization hints (for debugging only)
function optimizedFunction(a, b) {
  // This function should be optimized
  return a + b;
}

// Check if function is optimized (requires --allow-natives-syntax)
// %OptimizeFunctionOnNextCall(optimizedFunction);
// optimizedFunction(1, 2);
// console.log(%GetOptimizationStatus(optimizedFunction));

7. Memory Leak Detection

Detect and diagnose memory leaks:

javascript
// leak-detector.js
const memwatch = require('@airbnb/node-memwatch');

// Detect leak trends
memwatch.on('leak', (info) => {
  console.error('Memory leak detected:');
  console.error(JSON.stringify(info, null, 2));
});

// Track heap diffs
let lastHeapDiff = null;

memwatch.on('stats', (stats) => {
  console.log('GC occurred:');
  console.log(`  Heap used: ${(stats.used_heap_size / 1024 / 1024).toFixed(2)} MB`);

  if (lastHeapDiff) {
    const diff = new memwatch.HeapDiff();
    // ... run some code ...
    const changes = diff.end();
    console.log('Heap changes:', JSON.stringify(changes.change, null, 2));
  }
});

// Programmatic heap diff
function findLeaks() {
  const hd = new memwatch.HeapDiff();

  // Run suspected leaky code
  suspectedLeakyFunction();

  const diff = hd.end();
  return diff.change.details.filter(d =>
    d.size_bytes > 10000 && d['+'] > d['-']
  );
}

8. Performance Measurement API

Use built-in performance APIs:

javascript
// performance-monitoring.js
const {
  performance,
  PerformanceObserver,
  createHistogram
} = require('perf_hooks');

// Measure specific operations
performance.mark('operation-start');
await performOperation();
performance.mark('operation-end');
performance.measure('operation', 'operation-start', 'operation-end');

// Observe measurements
const obs = new PerformanceObserver((list) => {
  const entries = list.getEntries();
  entries.forEach((entry) => {
    console.log(`${entry.name}: ${entry.duration.toFixed(2)}ms`);
  });
});
obs.observe({ entryTypes: ['measure', 'function'] });

// Create histogram for repeated measurements
const histogram = createHistogram();

function timedOperation() {
  const start = process.hrtime.bigint();
  // ... operation ...
  const duration = Number(process.hrtime.bigint() - start);
  histogram.record(duration);
}

// Report histogram
console.log({
  min: histogram.min,
  max: histogram.max,
  mean: histogram.mean,
  p50: histogram.percentile(50),
  p99: histogram.percentile(99)
});

MCP Server Integration

This skill can leverage the following MCP servers:

| Server | Description | Use Case | |--------|-------------|----------| | clinic.js | Node.js profiling suite | Comprehensive analysis | | Sentry MCP | Error tracking | Performance correlation | | OpenTelemetry | Distributed tracing | Production profiling |

Best Practices

Profiling

1. Profile in production-like environment - Results vary by environment
2. Warm up before measuring - JIT needs time to optimize
3. Multiple runs - Take statistical significance into account
4. Focus on hot paths - Optimize what matters

Memory

1. Regular heap snapshots - Compare over time
2. Watch for trends - Slow leaks are hard to spot
3. Test with production data sizes - Leaks scale with data
4. Use weak references - For caches and listeners

Event Loop

1. Avoid sync operations - Use async alternatives
2. Batch CPU work - Use setImmediate to yield
3. Worker threads - For CPU-intensive work
4. Monitor in production - Use perf_hooks

Process Integration

This skill integrates with the following processes:

• cpu-profiling-investigation.js - CPU profiling workflows
• memory-profiling-analysis.js - Memory analysis
• memory-leak-detection.js - Leak detection

Output Format

When executing operations, provide structured output:

json
{
  "operation": "profile-cpu",
  "status": "completed",
  "duration": "30s",
  "profile": {
    "samples": 15420,
    "topFunctions": [
      {
        "name": "processRequest",
        "selfTime": "2340ms",
        "totalTime": "8920ms",
        "percentage": "28.5%",
        "file": "handlers.js:45"
      },
      {
        "name": "serializeResponse",
        "selfTime": "1890ms",
        "totalTime": "2100ms",
        "percentage": "22.1%",
        "file": "serializer.js:12"
      }
    ],
    "eventLoopDelay": {
      "mean": "2.3ms",
      "p99": "15.8ms",
      "max": "45.2ms"
    }
  },
  "recommendations": [
    {
      "function": "processRequest",
      "issue": "High CPU time in JSON parsing",
      "suggestion": "Consider streaming JSON parser for large payloads"
    }
  ],
  "artifacts": ["cpu-profile.cpuprofile", "flame.svg"]
}

Error Handling

Common Issues

| Error | Cause | Resolution | |-------|-------|------------| | Cannot take heap snapshot | OOM condition | Increase memory limit | | Profiler already started | Multiple profile sessions | Stop existing profiler | | Event loop blocked | Sync operation | Use async alternative | | High GC time | Memory pressure | Reduce allocations, increase heap |

Constraints

• Profiling adds overhead - avoid in production
• Heap snapshots pause the process
• Event loop monitoring has minimal overhead
• V8 flags are debug-only