node-loop-detective 1.2.0 → 1.4.0

package/README.md

@@ -74,6 +74,12 @@ loop-detective -p 12345 -d 30 -t 100
 # Detect slow I/O with a 1-second threshold
 loop-detective -p 12345 --io-threshold 1000
 
+# Connect to a remote inspector (Docker, K8s, remote server)
+loop-detective --host 192.168.1.100 --port 9229
+
+# Save raw CPU profile for Chrome DevTools / speedscope
+loop-detective -p 12345 --save-profile ./profile.cpuprofile
+
 # Continuous monitoring mode
 loop-detective -p 12345 --watch
 
@@ -86,11 +92,13 @@ loop-detective -p 12345 --json
 | Flag | Description | Default |
 |------|-------------|---------|
 | `-p, --pid <pid>` | Target Node.js process ID | — |
+| `-H, --host <host>` | Inspector host (remote connections) | 127.0.0.1 |
 | `-P, --port <port>` | Inspector port (skip SIGUSR1) | — |
 | `-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 |
+| `--save-profile <path>` | Save raw CPU profile to file | — |
 | `-j, --json` | Output as JSON | false |
 | `-w, --watch` | Continuous monitoring | false |
 
@@ -124,6 +132,7 @@ const { Detective } = require('node-loop-detective');
 
 const detective = new Detective({
   pid: 12345,
+  inspectorHost: '127.0.0.1',  // or remote host
   duration: 10000,
   threshold: 50,
   interval: 100,

package/bin/cli.js

@@ -4,17 +4,21 @@
 
 const { Detective } = require('../src/detective');
 const { Reporter } = require('../src/reporter');
+const fs = require('node:fs');
+const path = require('node:path');
 
 // Simple arg parser compatible with Node.js 16+
 function parseCliArgs(argv) {
   const args = argv.slice(2);
   const values = {
     pid: null,
+    host: null,
     port: null,
     duration: '10',
     threshold: '50',
     interval: '100',
     'io-threshold': '500',
+    'save-profile': null,
     json: false,
     watch: false,
     help: false,
@@ -24,11 +28,13 @@ function parseCliArgs(argv) {
 
   const flagMap = {
     '-p': 'pid', '--pid': 'pid',
+    '-H': 'host', '--host': 'host',
     '-P': 'port', '--port': 'port',
     '-d': 'duration', '--duration': 'duration',
     '-t': 'threshold', '--threshold': 'threshold',
     '-i': 'interval', '--interval': 'interval',
     '--io-threshold': 'io-threshold',
+    '--save-profile': 'save-profile',
   };
   const boolMap = {
     '-j': 'json', '--json': 'json',
@@ -85,14 +91,17 @@ function printUsage() {
     loop-detective <pid>
     loop-detective --pid <pid>
     loop-detective --port <inspector-port>
+    loop-detective --host <remote-host> --port <inspector-port>
 
   OPTIONS
     -p, --pid <pid>          Target Node.js process ID
+    -H, --host <host>        Inspector host (default: 127.0.0.1)
     -P, --port <port>        Connect to an already-open inspector port
     -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)
+    --save-profile <path>    Save raw CPU profile to .cpuprofile file
     -j, --json               Output results as JSON
     -w, --watch              Continuous monitoring mode
     -h, --help               Show this help
@@ -102,6 +111,7 @@ function printUsage() {
     loop-detective 12345
     loop-detective --pid 12345 --duration 30 --threshold 100
     loop-detective --port 9229 --watch
+    loop-detective --host 192.168.1.100 --port 9229
     loop-detective -p 12345 -d 5 -j
 
   HOW IT WORKS
@@ -116,11 +126,13 @@ function printUsage() {
 async function main() {
   const config = {
     pid: pid ? parseInt(pid, 10) : null,
+    inspectorHost: values.host || '127.0.0.1',
     inspectorPort,
     duration: parseInt(values.duration, 10) * 1000,
     threshold: parseInt(values.threshold, 10),
     interval: parseInt(values.interval, 10),
     ioThreshold: parseInt(values['io-threshold'], 10),
+    saveProfile: values['save-profile'],
     watch: values.watch,
     json: values.json,
   };
@@ -128,10 +140,32 @@ async function main() {
   const reporter = new Reporter(config);
   const detective = new Detective(config);
 
+  // Security warning for remote connections
+  if (config.inspectorHost !== '127.0.0.1' && config.inspectorHost !== 'localhost') {
+    reporter.onInfo(`⚠ Warning: Connecting to remote host ${config.inspectorHost}. The CDP protocol has no authentication — ensure the network is trusted.`);
+  }
+
   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('profile', (analysis, rawProfile) => {
+    reporter.onProfile(analysis);
+
+    // Save raw CPU profile if requested
+    if (config.saveProfile && rawProfile) {
+      try {
+        const filePath = path.resolve(config.saveProfile);
+        fs.writeFileSync(filePath, JSON.stringify(rawProfile));
+        if (!config.json) {
+          console.log(`\n  \x1b[32m✔\x1b[0m CPU profile saved to ${filePath}`);
+          console.log(`    Open in Chrome DevTools: Performance tab → Load profile`);
+          console.log(`    Or visit https://www.speedscope.app\n`);
+        }
+      } catch (err) {
+        console.error(`\n  \x1b[31m✖ Failed to save profile: ${err.message}\x1b[0m\n`);
+      }
+    }
+  });
   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.2.0",
+  "version": "1.4.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

@@ -406,7 +406,7 @@ class Detective extends EventEmitter {
     this._activateInspector();
     const port = await this._findInspectorPort();
 
-    this.inspector = new Inspector({ port });
+    this.inspector = new Inspector({ host: this.config.inspectorHost, port });
     await this.inspector.connect();
     this.emit('connected');
 
@@ -424,7 +424,7 @@ class Detective extends EventEmitter {
 
       const profile = await this._captureProfile(this.config.duration);
       const analysis = this.analyzer.analyzeProfile(profile);
-      this.emit('profile', analysis);
+      this.emit('profile', analysis, profile);
     } finally {
       await this.stop();
     }
@@ -444,7 +444,7 @@ class Detective extends EventEmitter {
       try {
         const profile = await this._captureProfile(this.config.duration);
         const analysis = this.analyzer.analyzeProfile(profile);
-        this.emit('profile', analysis);
+        this.emit('profile', analysis, profile);
       } catch (err) {
         this.emit('error', err);
       }