node-loop-detective 1.0.1 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # node-loop-detective 🔍
 
-Detect event loop blocking & lag in **running** Node.js apps — without code changes or restarts.
+Detect event loop blocking, lag, and slow async I/O in **running** Node.js apps — without code changes or restarts.
 
 ```
 $ loop-detective 12345
@@ -10,6 +10,8 @@ $ loop-detective 12345
 
 ⚠ Event loop lag: 312ms at 2025-01-15T10:23:45.123Z
 ⚠ Event loop lag: 156ms at 2025-01-15T10:23:48.456Z
+🌐 Slow HTTP: 2340ms GET api.example.com/users → 200
+🔌 Slow TCP: 1520ms db-server:3306
 
 ────────────────────────────────────────────────────────────
   Event Loop Detective Report
@@ -28,6 +30,17 @@ $ loop-detective 12345
    1. heavyComputation
       ██████████████░░░░░░ 6245ms (62.3%)
       /app/server.js:42:1
+
+  ⚠ Slow Async I/O Summary
+    Total slow ops: 3
+
+    🌐 HTTP — 2 slow ops, avg 1800ms, max 2340ms
+      GET api.example.com/users
+        2 calls, total 3600ms, avg 1800ms, max 2340ms
+
+    🔌 TCP — 1 slow ops, avg 1520ms, max 1520ms
+      db-server:3306
+        1 calls, total 1520ms, max 1520ms
 ```
 
 ## How It Works
@@ -35,9 +48,10 @@ $ loop-detective 12345
 1. Sends `SIGUSR1` to activate the Node.js built-in inspector (or connects to `--port`)
 2. Connects via Chrome DevTools Protocol (CDP)
 3. Injects a lightweight event loop lag monitor
-4. Captures a CPU profile to identify blocking code
-5. Analyzes the profile for common blocking patterns
-6. Disconnects cleanly — minimal impact on your running app
+4. Tracks slow async I/O (HTTP, DNS, TCP) via monkey-patching
+5. Captures a CPU profile to identify blocking code
+6. Analyzes the profile for common blocking patterns
+7. Disconnects cleanly — minimal impact on your running app
 
 ## Install
 
@@ -57,6 +71,9 @@ loop-detective --port 9229
 # Profile for 30 seconds with 100ms lag threshold
 loop-detective -p 12345 -d 30 -t 100
 
+# Detect slow I/O with a 1-second threshold
+loop-detective -p 12345 --io-threshold 1000
+
 # Continuous monitoring mode
 loop-detective -p 12345 --watch
 
@@ -73,11 +90,14 @@ loop-detective -p 12345 --json
 | `-d, --duration <sec>` | Profiling duration in seconds | 10 |
 | `-t, --threshold <ms>` | Event loop lag threshold | 50 |
 | `-i, --interval <ms>` | Lag sampling interval | 100 |
+| `--io-threshold <ms>` | Slow I/O threshold | 500 |
 | `-j, --json` | Output as JSON | false |
 | `-w, --watch` | Continuous monitoring | false |
 
 ## What It Detects
 
+### CPU / Event Loop Blocking
+
 | Pattern | Description |
 |---------|-------------|
 | `cpu-hog` | Single function consuming >50% CPU |
@@ -87,6 +107,16 @@ loop-detective -p 12345 --json
 | `sync-io` | Synchronous file I/O calls |
 | `crypto-heavy` | CPU-intensive crypto operations |
 
+### Slow Async I/O
+
+| Type | What It Tracks |
+|------|---------------|
+| 🌐 HTTP/HTTPS | Outgoing HTTP requests — method, target, status code, duration |
+| 🔍 DNS | DNS lookups — hostname, resolution time |
+| 🔌 TCP | TCP connections — target host:port, connect time (covers databases, Redis, etc.) |
+
+Each slow I/O event includes the caller stack trace, so you know exactly which code initiated the slow operation.
+
 ## Programmatic API
 
 ```js
@@ -97,9 +127,11 @@ const detective = new Detective({
   duration: 10000,
   threshold: 50,
   interval: 100,
+  ioThreshold: 500,
 });
 
 detective.on('lag', (data) => console.log('Lag:', data.lag, 'ms'));
+detective.on('slowIO', (data) => console.log('Slow I/O:', data.type, data.target, data.duration, 'ms'));
 detective.on('profile', (analysis) => {
   console.log('Heavy functions:', analysis.heavyFunctions);
   console.log('Patterns:', analysis.blockingPatterns);
@@ -117,7 +149,7 @@ await detective.start();
 
 ## How is this different from clinic.js / 0x?
 
-Those are great tools, but they require you to **start** your app through them. `loop-detective` attaches to an **already running** process — perfect for production debugging.
+Those are great tools, but they require you to **start** your app through them. `loop-detective` attaches to an **already running** process — perfect for production debugging. It also tracks slow async I/O (HTTP, DNS, TCP) which those tools don't focus on.
 
 ## License
 

package/bin/cli.js

@@ -14,6 +14,7 @@ function parseCliArgs(argv) {
     duration: '10',
     threshold: '50',
     interval: '100',
+    'io-threshold': '500',
     json: false,
     watch: false,
     help: false,
@@ -27,6 +28,7 @@ function parseCliArgs(argv) {
     '-d': 'duration', '--duration': 'duration',
     '-t': 'threshold', '--threshold': 'threshold',
     '-i': 'interval', '--interval': 'interval',
+    '--io-threshold': 'io-threshold',
   };
   const boolMap = {
     '-j': 'json', '--json': 'json',
@@ -90,6 +92,7 @@ function printUsage() {
     -d, --duration <sec>     Profiling duration in seconds (default: 10)
     -t, --threshold <ms>     Event loop lag threshold in ms (default: 50)
     -i, --interval <ms>      Sampling interval in ms (default: 100)
+    --io-threshold <ms>      Slow I/O threshold in ms (default: 500)
     -j, --json               Output results as JSON
     -w, --watch              Continuous monitoring mode
     -h, --help               Show this help
@@ -117,6 +120,7 @@ async function main() {
     duration: parseInt(values.duration, 10) * 1000,
     threshold: parseInt(values.threshold, 10),
     interval: parseInt(values.interval, 10),
+    ioThreshold: parseInt(values['io-threshold'], 10),
     watch: values.watch,
     json: values.json,
   };
@@ -126,6 +130,7 @@ async function main() {
 
   detective.on('connected', () => reporter.onConnected());
   detective.on('lag', (data) => reporter.onLag(data));
+  detective.on('slowIO', (data) => reporter.onSlowIO(data));
   detective.on('profile', (data) => reporter.onProfile(data));
   detective.on('error', (err) => reporter.onError(err));
   detective.on('disconnected', () => reporter.onDisconnected());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-loop-detective",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Detect event loop blocking & lag in running Node.js apps without code changes or restarts",
   "main": "src/index.js",
   "bin": {

package/src/detective.js

@@ -12,6 +12,7 @@ class Detective extends EventEmitter {
     this.analyzer = new Analyzer(config);
     this._running = false;
     this._lagTimer = null;
+    this._ioTimer = null;
   }
 
   /**
@@ -56,7 +57,7 @@ class Detective extends EventEmitter {
    * We inject a tiny lag-measuring snippet into the target process
    */
   async _startLagDetection() {
-    // Inject a lag detector into the target process
+    // Inject a lag detector that also captures stack traces
     const script = `
       (function() {
         if (globalThis.__loopDetective) {
@@ -66,12 +67,33 @@ class Detective extends EventEmitter {
         let lastTime = Date.now();
         const threshold = ${this.config.threshold};
 
+        // Capture stack trace at the point of lag detection
+        function captureStack() {
+          const orig = Error.stackTraceLimit;
+          Error.stackTraceLimit = 20;
+          const err = new Error();
+          Error.stackTraceLimit = orig;
+          // Parse the stack into structured frames
+          const frames = (err.stack || '').split('\\n').slice(2).map(line => {
+            const m = line.match(/at\\s+(?:(.+?)\\s+\\()?(.+?):(\\d+):(\\d+)\\)?/);
+            if (m) return { fn: m[1] || '(anonymous)', file: m[2], line: +m[3], col: +m[4] };
+            const m2 = line.match(/at\\s+(.+)/);
+            if (m2) return { fn: m2[1], file: '', line: 0, col: 0 };
+            return null;
+          }).filter(Boolean).filter(f =>
+            !f.file.includes('loopDetective') &&
+            !f.fn.includes('Timeout.') &&
+            !f.file.includes('node:internal')
+          );
+          return frames;
+        }
+
         const timer = setInterval(() => {
           const now = Date.now();
           const delta = now - lastTime;
           const lag = delta - ${this.config.interval};
           if (lag > threshold) {
-            lags.push({ lag, timestamp: now });
+            lags.push({ lag, timestamp: now, stack: captureStack() });
             if (lags.length > 100) lags.shift();
           }
           lastTime = now;
@@ -123,6 +145,224 @@ class Detective extends EventEmitter {
     }, 1000);
   }
 
+  /**
+   * Start slow async I/O detection via CDP Runtime.evaluate
+   * Monkey-patches http, https, net, dns to track slow operations
+   */
+  async _startAsyncIOTracking() {
+    const ioThreshold = this.config.ioThreshold || 500;
+
+    const script = `
+      (function() {
+        if (globalThis.__loopDetectiveIO) {
+          return { alreadyRunning: true };
+        }
+
+        const slowOps = [];
+        const threshold = ${ioThreshold};
+
+        // --- Track outgoing HTTP/HTTPS requests ---
+        function patchHttp(modName) {
+          let mod;
+          try { mod = require(modName); } catch { return; }
+          const origRequest = mod.request;
+          const origGet = mod.get;
+
+          mod.request = function patchedRequest(...args) {
+            const startTime = Date.now();
+            const opts = typeof args[0] === 'string' ? { href: args[0] } : (args[0] || {});
+            const target = opts.href || opts.hostname || opts.host || 'unknown';
+            const method = (opts.method || 'GET').toUpperCase();
+            const label = modName + ' ' + method + ' ' + target;
+
+            // Capture caller stack
+            const origLimit = Error.stackTraceLimit;
+            Error.stackTraceLimit = 10;
+            const stackErr = new Error();
+            Error.stackTraceLimit = origLimit;
+            const callerStack = (stackErr.stack || '').split('\\n').slice(2, 6).map(l => l.trim());
+
+            const req = origRequest.apply(this, args);
+
+            req.on('response', (res) => {
+              const duration = Date.now() - startTime;
+              if (duration >= threshold) {
+                slowOps.push({
+                  type: 'http',
+                  protocol: modName,
+                  method,
+                  target,
+                  statusCode: res.statusCode,
+                  duration,
+                  timestamp: Date.now(),
+                  stack: callerStack,
+                });
+                if (slowOps.length > 200) slowOps.shift();
+              }
+            });
+
+            req.on('error', (err) => {
+              const duration = Date.now() - startTime;
+              if (duration >= threshold) {
+                slowOps.push({
+                  type: 'http',
+                  protocol: modName,
+                  method,
+                  target,
+                  error: err.message,
+                  duration,
+                  timestamp: Date.now(),
+                  stack: callerStack,
+                });
+                if (slowOps.length > 200) slowOps.shift();
+              }
+            });
+
+            return req;
+          };
+
+          mod.get = function patchedGet(...args) {
+            const req = mod.request(...args);
+            req.end();
+            return req;
+          };
+        }
+
+        patchHttp('http');
+        patchHttp('https');
+
+        // --- Track DNS lookups ---
+        (function patchDns() {
+          let dns;
+          try { dns = require('dns'); } catch { return; }
+          const origLookup = dns.lookup;
+
+          dns.lookup = function patchedLookup(hostname, options, callback) {
+            const startTime = Date.now();
+            if (typeof options === 'function') {
+              callback = options;
+              options = {};
+            }
+
+            const origLimit = Error.stackTraceLimit;
+            Error.stackTraceLimit = 10;
+            const stackErr = new Error();
+            Error.stackTraceLimit = origLimit;
+            const callerStack = (stackErr.stack || '').split('\\n').slice(2, 6).map(l => l.trim());
+
+            return origLookup.call(dns, hostname, options, function(err, address, family) {
+              const duration = Date.now() - startTime;
+              if (duration >= threshold) {
+                slowOps.push({
+                  type: 'dns',
+                  target: hostname,
+                  duration,
+                  error: err ? err.message : null,
+                  timestamp: Date.now(),
+                  stack: callerStack,
+                });
+                if (slowOps.length > 200) slowOps.shift();
+              }
+              if (callback) callback(err, address, family);
+            });
+          };
+        })();
+
+        // --- Track TCP socket connections ---
+        (function patchNet() {
+          let net;
+          try { net = require('net'); } catch { return; }
+          const origConnect = net.Socket.prototype.connect;
+
+          net.Socket.prototype.connect = function patchedConnect(...args) {
+            const startTime = Date.now();
+            const opts = typeof args[0] === 'object' ? args[0] : { port: args[0], host: args[1] };
+            const target = (opts.host || '127.0.0.1') + ':' + (opts.port || '?');
+
+            const origLimit = Error.stackTraceLimit;
+            Error.stackTraceLimit = 10;
+            const stackErr = new Error();
+            Error.stackTraceLimit = origLimit;
+            const callerStack = (stackErr.stack || '').split('\\n').slice(2, 6).map(l => l.trim());
+
+            this.once('connect', () => {
+              const duration = Date.now() - startTime;
+              if (duration >= threshold) {
+                slowOps.push({
+                  type: 'tcp',
+                  target,
+                  duration,
+                  timestamp: Date.now(),
+                  stack: callerStack,
+                });
+                if (slowOps.length > 200) slowOps.shift();
+              }
+            });
+
+            this.once('error', (err) => {
+              const duration = Date.now() - startTime;
+              if (duration >= threshold) {
+                slowOps.push({
+                  type: 'tcp',
+                  target,
+                  error: err.message,
+                  duration,
+                  timestamp: Date.now(),
+                  stack: callerStack,
+                });
+                if (slowOps.length > 200) slowOps.shift();
+              }
+            });
+
+            return origConnect.apply(this, args);
+          };
+        })();
+
+        globalThis.__loopDetectiveIO = {
+          getSlowOps: () => {
+            const result = slowOps.splice(0);
+            return result;
+          },
+          cleanup: () => {
+            // Note: we don't restore originals to avoid complexity.
+            // The patches become no-ops once threshold filtering removes them.
+            delete globalThis.__loopDetectiveIO;
+          }
+        };
+
+        return { started: true };
+      })()
+    `;
+
+    const result = await this.inspector.send('Runtime.evaluate', {
+      expression: script,
+      returnByValue: true,
+    });
+
+    if (result.exceptionDetails) {
+      // Non-fatal: IO tracking is optional
+      this.emit('error', new Error(`Failed to inject I/O tracker (non-fatal): ${JSON.stringify(result.exceptionDetails)}`));
+      return;
+    }
+
+    // Poll for slow I/O events
+    this._ioTimer = setInterval(async () => {
+      if (!this._running) return;
+      try {
+        const pollResult = await this.inspector.send('Runtime.evaluate', {
+          expression: 'globalThis.__loopDetectiveIO ? globalThis.__loopDetectiveIO.getSlowOps() : []',
+          returnByValue: true,
+        });
+        const ops = pollResult.result?.value || [];
+        for (const op of ops) {
+          this.emit('slowIO', op);
+        }
+      } catch {
+        // Inspector may have disconnected
+      }
+    }, 1000);
+  }
+
   /**
    * Take a CPU profile to identify blocking code
    */
@@ -140,7 +380,7 @@ class Detective extends EventEmitter {
   }
 
   /**
-   * Clean up the injected lag detector
+   * Clean up the injected lag detector and I/O tracker
    */
   async _cleanupLagDetector() {
     try {
@@ -151,6 +391,14 @@ class Detective extends EventEmitter {
     } catch {
       // Best effort cleanup
     }
+    try {
+      await this.inspector.send('Runtime.evaluate', {
+        expression: 'globalThis.__loopDetectiveIO && globalThis.__loopDetectiveIO.cleanup()',
+        returnByValue: true,
+      });
+    } catch {
+      // Best effort cleanup
+    }
   }
 
   /**
@@ -177,8 +425,9 @@ class Detective extends EventEmitter {
 
   async _singleRun() {
     try {
-      // Step 3: Start lag detection
+      // Step 3: Start lag detection + async I/O tracking
       await this._startLagDetection();
+      await this._startAsyncIOTracking();
 
       // Step 4: Capture CPU profile
       const profile = await this._captureProfile(this.config.duration);
@@ -193,6 +442,7 @@ class Detective extends EventEmitter {
 
   async _watchMode() {
     await this._startLagDetection();
+    await this._startAsyncIOTracking();
 
     const runCycle = async () => {
       if (!this._running) return;
@@ -220,6 +470,11 @@ class Detective extends EventEmitter {
       this._lagTimer = null;
     }
 
+    if (this._ioTimer) {
+      clearInterval(this._ioTimer);
+      this._ioTimer = null;
+    }
+
     if (this.inspector) {
       await this._cleanupLagDetector();
       await this.inspector.disconnect();

package/src/reporter.js

@@ -20,6 +20,7 @@ class Reporter {
   constructor(config) {
     this.config = config;
     this.lagEvents = [];
+    this.slowIOEvents = [];
   }
 
   onConnected() {
@@ -33,12 +34,36 @@ class Reporter {
     if (this.config.json) return;
     const severity = data.lag > 500 ? COLORS.red : data.lag > 200 ? COLORS.yellow : COLORS.cyan;
     this._print(`${severity}⚠ Event loop lag: ${data.lag}ms${COLORS.reset} ${COLORS.dim}at ${new Date(data.timestamp).toISOString()}${COLORS.reset}`);
+    if (data.stack && data.stack.length > 0) {
+      for (const frame of data.stack.slice(0, 5)) {
+        this._print(`  ${COLORS.dim}  → ${frame.fn} ${frame.file}:${frame.line}:${frame.col}${COLORS.reset}`);
+      }
+    }
+  }
+
+  onSlowIO(data) {
+    this.slowIOEvents.push(data);
+    if (this.config.json) return;
+    const severity = data.duration > 5000 ? COLORS.red : data.duration > 2000 ? COLORS.yellow : COLORS.magenta;
+    const icon = data.type === 'http' ? '🌐' : data.type === 'dns' ? '🔍' : '🔌';
+    const detail = data.type === 'http'
+      ? `${data.method} ${data.target} → ${data.statusCode || data.error || '?'}`
+      : data.type === 'dns'
+      ? `lookup ${data.target}${data.error ? ' (' + data.error + ')' : ''}`
+      : `connect ${data.target}${data.error ? ' (' + data.error + ')' : ''}`;
+    this._print(`${severity}${icon} Slow ${data.type.toUpperCase()}: ${data.duration}ms${COLORS.reset} ${detail}`);
+    if (data.stack && data.stack.length > 0) {
+      for (const line of data.stack.slice(0, 3)) {
+        this._print(`  ${COLORS.dim}  ${line}${COLORS.reset}`);
+      }
+    }
   }
 
   onProfile(analysis) {
     if (this.config.json) {
-      this._print(JSON.stringify({ ...analysis, lagEvents: this.lagEvents }, null, 2));
+      this._print(JSON.stringify({ ...analysis, lagEvents: this.lagEvents, slowIOEvents: this.slowIOEvents }, null, 2));
       this.lagEvents = [];
+      this.slowIOEvents = [];
       return;
     }
 
@@ -46,9 +71,11 @@ class Reporter {
     this._printPatterns(analysis.blockingPatterns);
     this._printHeavyFunctions(analysis.heavyFunctions);
     this._printCallStacks(analysis.callStacks);
+    this._printSlowIOSummary();
     this._printLagSummary();
 
     this.lagEvents = [];
+    this.slowIOEvents = [];
   }
 
   onError(err) {
@@ -133,6 +160,53 @@ class Reporter {
     }
   }
 
+  _printSlowIOSummary() {
+    if (this.slowIOEvents.length === 0) {
+      this._print(`\n  ${COLORS.green}✔ No slow I/O operations detected${COLORS.reset}`);
+      return;
+    }
+
+    this._print(`\n  ${COLORS.magenta}⚠ Slow Async I/O Summary${COLORS.reset}`);
+    this._print(`    Total slow ops: ${this.slowIOEvents.length}`);
+
+    // Group by type
+    const byType = {};
+    for (const op of this.slowIOEvents) {
+      if (!byType[op.type]) byType[op.type] = [];
+      byType[op.type].push(op);
+    }
+
+    for (const [type, ops] of Object.entries(byType)) {
+      const icon = type === 'http' ? '🌐' : type === 'dns' ? '🔍' : '🔌';
+      const maxDur = Math.max(...ops.map(o => o.duration));
+      const avgDur = Math.round(ops.reduce((s, o) => s + o.duration, 0) / ops.length);
+      this._print(`\n    ${icon} ${COLORS.bold}${type.toUpperCase()}${COLORS.reset} — ${ops.length} slow ops, avg ${avgDur}ms, max ${maxDur}ms`);
+
+      // Group by target
+      const byTarget = {};
+      for (const op of ops) {
+        const key = op.type === 'http' ? `${op.method} ${op.target}` : op.target;
+        if (!byTarget[key]) byTarget[key] = { count: 0, totalDuration: 0, maxDuration: 0, errors: 0, stack: op.stack };
+        byTarget[key].count++;
+        byTarget[key].totalDuration += op.duration;
+        byTarget[key].maxDuration = Math.max(byTarget[key].maxDuration, op.duration);
+        if (op.error) byTarget[key].errors++;
+      }
+
+      const sorted = Object.entries(byTarget).sort((a, b) => b[1].totalDuration - a[1].totalDuration);
+      for (const [target, stats] of sorted.slice(0, 5)) {
+        const errStr = stats.errors > 0 ? ` ${COLORS.red}(${stats.errors} errors)${COLORS.reset}` : '';
+        this._print(`      ${COLORS.yellow}${target}${COLORS.reset}${errStr}`);
+        this._print(`        ${stats.count} calls, total ${stats.totalDuration}ms, avg ${Math.round(stats.totalDuration / stats.count)}ms, max ${stats.maxDuration}ms`);
+        if (stats.stack && stats.stack.length > 0) {
+          for (const line of stats.stack.slice(0, 2)) {
+            this._print(`        ${COLORS.dim}${line}${COLORS.reset}`);
+          }
+        }
+      }
+    }
+  }
+
   _printLagSummary() {
     if (this.lagEvents.length === 0) {
       this._print(`\n  ${COLORS.green}✔ No event loop lag detected above threshold${COLORS.reset}`);
@@ -143,6 +217,29 @@ class Reporter {
       this._print(`    Events: ${this.lagEvents.length}`);
       this._print(`    Max:    ${maxLag}ms`);
       this._print(`    Avg:    ${avgLag}ms`);
+
+      // Aggregate lag by code location
+      const locationMap = new Map();
+      for (const evt of this.lagEvents) {
+        if (evt.stack && evt.stack.length > 0) {
+          const top = evt.stack[0];
+          const key = `${top.fn} ${top.file}:${top.line}`;
+          const entry = locationMap.get(key) || { count: 0, totalLag: 0, maxLag: 0, frame: top };
+          entry.count++;
+          entry.totalLag += evt.lag;
+          entry.maxLag = Math.max(entry.maxLag, evt.lag);
+          locationMap.set(key, entry);
+        }
+      }
+
+      if (locationMap.size > 0) {
+        this._print(`\n    ${COLORS.bold}Lag by Code Location:${COLORS.reset}`);
+        const sorted = [...locationMap.values()].sort((a, b) => b.totalLag - a.totalLag);
+        for (const loc of sorted.slice(0, 5)) {
+          this._print(`    ${COLORS.yellow}${loc.frame.fn}${COLORS.reset} ${COLORS.dim}${loc.frame.file}:${loc.frame.line}${COLORS.reset}`);
+          this._print(`      ${loc.count} events, total ${loc.totalLag}ms, max ${loc.maxLag}ms`);
+        }
+      }
     }
 
     this._print(`\n${'─'.repeat(60)}\n`);