flow-debugger 1.9.3 → 1.9.5

package/README.md

@@ -1,266 +1,391 @@
-# 🔍 flow-debugger
-
-**Production-safe flow-level debugging SDK for Node.js, Web, and React Native.**
-
-Traces requests step-by-step, measures timing, classifies errors, detects root causes, and provides endpoint analytics with a live dashboard.
-
-
-
-![Flow Debugger Dashboard](flowdebuger.png)
----
-![PROJECT Debugger Dashboard](./FLOWDUBGERDASH.png)
----
-## 🚀 Easy 3-Line Setup (Beginner Friendly)
-Beginners can get a professional dashboard and request tracing with just **3 lines of code**:
-
-```typescript
-const debug = flowDebugger({ enableDashboard: true }); // 1. Init
-app.use(debug.middleware);                             // 2. Middleware
-mongoTracer(mongoose, { getTracer: debug.getTracer }); // 3. Auto-Trace
-```
-
----
-
-## ✨ Features
-
-- **Request Tracing** — Every request gets a unique `traceId` with step-by-step timing
-- **Auto-Instrument** — MongoDB, MySQL, PostgreSQL, Redis — zero extra code needed
-- **Root Cause Detection** — Automatically identifies why a request failed or was slow
-- **Error Classification** — `INFO` / `WARN` / `ERROR` / `CRITICAL` auto-categorization
-- **Timeout Detection** — Catches hanging queries/operations with configurable timeouts
-- **Slow Query Detection** — Flags slow SQL/NoSQL queries with threshold alerts
-- **Endpoint Analytics** — Per-route stats: requests, errors, slow, avg/p95/max latency
-- **Service Health Monitor** — Real-time dependency health: `Redis: healthy`, `Mongo: degraded`
-- **Live Dashboard** — Beautiful analytics UI at `/__debugger/dashboard`
-- **Console Timeline** — Visual request timeline directly in your terminal
-- **Production-Safe** — Never blocks requests, never crashes your app, all try/catch wrapped
-- **Sampling** — Configurable sampling rate for high-traffic environments
-
----
-
-## 📦 Installation
-
-```bash
-npm install flow-debugger
-```
-
----
-
-## 🚀 Quick Start (Express)
-
-```typescript
-import express from 'express';
-import { flowDebugger, mongoTracer, mysqlTracer, pgTracer, redisTracer } from 'flow-debugger';
-
-const app = express();
-
-// 1. Initialize debugger
-const debug = flowDebugger({
-  slowThreshold: 300,      // ms — mark steps as slow
-  slowQueryThreshold: 300, // ms — flag slow DB queries
-  enableDashboard: true,   // serve /__debugger/dashboard
-});
-
-app.use(debug.middleware);
-
-// 2. Auto-instrument databases (optional — zero code tracing!)
-mongoTracer(mongoose, { getTracer: debug.getTracer });
-mysqlTracer(mysqlPool, { getTracer: debug.getTracer });
-pgTracer(pgPool, { getTracer: debug.getTracer });
-redisTracer(redisClient, { getTracer: debug.getTracer });
-
-// 3. Use manual steps in your routes
-app.post('/api/login', async (req, res) => {
-  const tracer = req.tracer;
-
-  const user = await tracer.step('DB find user', async () => {
-    return User.findOne({ email: req.body.email });
-  }, { service: 'mongo' });
-
-  await tracer.step('Redis cache session', async () => {
-    return redis.set(`session:${user.id}`, JSON.stringify(user));
-  }, { service: 'redis' });
-
-  const token = await tracer.step('JWT generate', async () => {
-    return jwt.sign({ id: user.id }, SECRET);
-  });
-
-  res.json({ token, user });
-});
-
-app.listen(3000);
-```
-
-### Console Output:
-```
-┌─── flow-debugger ── req_m3k2_abc123_1 ── POST /api/login ───
-│ [0ms]    Request start
-│ [2ms]    DB find user ✔ (14ms) [mongo]
-│ [16ms]   Redis cache session ✔ (3ms) [redis]
-│ [20ms]   JWT generate ✔ (1ms)
-│ [21ms]   Response 200
-│
-│ Classification: INFO
-│ Total: 21ms
-└──────────────────────────────────────────────────────
-```
-
----
-
-## 🧩 Auto-Instrument (Zero Code Tracing)
-
-```typescript
-import { mongoTracer, mysqlTracer, pgTracer, redisTracer } from 'flow-debugger';
-
-// Mongoose — patches Query.prototype.exec
-mongoTracer(mongoose, { getTracer: debug.getTracer });
-
-// mysql2 — patches pool.query() and pool.execute()
-mysqlTracer(pool, { getTracer: debug.getTracer });
-
-// pg — patches pool.query() and client.query()
-pgTracer(pgPool, { getTracer: debug.getTracer });
-
-// Redis — wraps get, set, del, hget, etc.
-redisTracer(redisClient, { getTracer: debug.getTracer });
-```
-
-**Auto output (no extra code needed):**
-```
-MySQL SELECT users → 12ms ✔
-Postgres SELECT orders → 18ms ✔
-Redis SET session → 3ms ✔
-Mongo users.findOne → 22ms ✔
-```
-
----
-
-## ⏱ Timeout Detection
-
-```typescript
-await tracer.step('DB query', async () => {
-  return db.query('SELECT * FROM orders');
-}, { service: 'postgres', timeout: 2000 });
-```
-
-If the query takes >2s:
-```
-CRITICAL: DB query timed out after 2000ms
-Root cause: DB timeout
-```
-
----
-
-## 🏷 Dependency Tagging
-
-```typescript
-await tracer.step('Cache lookup', fn, { service: 'redis' });
-await tracer.step('User query', fn, { service: 'postgres' });
-```
-
-Dashboard grouping:
-```
-Top failures:
-  Redis     42%
-  Postgres  33%
-  External  12%
-```
-
----
-
-## 📊 Dashboard
-
-Access the live analytics dashboard at:
-```
-http://localhost:3000/__debugger/dashboard
-```
-
-### API Endpoints:
-| Route | Description |
-|---|---|
-| `GET /__debugger` | Full analytics JSON |
-| `GET /__debugger/dashboard` | Live HTML dashboard |
-| `GET /__debugger/health` | Service health status |
-| `GET /__debugger/endpoint?path=/api/login` | Per-endpoint stats |
-
----
-
-## ⚙️ Configuration
-
-```typescript
-flowDebugger({
-  enabled: true,              // Enable/disable debugger
-  slowThreshold: 300,         // ms — slow step threshold
-  slowQueryThreshold: 300,    // ms — slow query threshold
-  defaultTimeout: 30000,      // ms — default step timeout
-  samplingRate: 1,            // 0-1 (1 = 100%)
-  alwaysSampleErrors: true,   // Always trace errors even if sampled out
-  maxTraces: 1000,            // Max traces in memory
-  enableTimeline: true,       // Console timeline output
-  enableDashboard: true,      // Serve /__debugger routes
-  logger: console.log,        // Custom logger function
-});
-```
-
----
-
-## 🔍 Root Cause Detection
-
-The package automatically identifies the most likely cause of failures:
-
-| Scenario | Root Cause |
-|---|---|
-| Response 500 + Redis failed | `Redis GET failed: connection refused` |
-| DB query 900ms + total latency high | `Slow PostgreSQL query: SELECT orders (900ms)` |
-| Step timeout after 2s | `Payment API timed out after 2000ms` |
-
----
-
-## 📡 Subpath Imports
-
-```typescript
-// Only import what you need
-import { flowDebugger } from 'flow-debugger/express';
-import { mongoTracer } from 'flow-debugger/mongo';
-import { mysqlTracer } from 'flow-debugger/mysql';
-import { pgTracer } from 'flow-debugger/postgres';
-import { redisTracer } from 'flow-debugger/redis';
-```
-
----
-
-## 🏗 Architecture
-
-```
-core/
-  TraceEngine     — request trace lifecycle
-  Classifier      — INFO/WARN/ERROR/CRITICAL
-  RootCause       — failure origin detection
-  Analytics       — endpoint-level aggregation
-  HealthMonitor   — dependency health tracking
-  Timeline        — console renderer
-
-integrations/
-  mongo           — Mongoose auto-tracing
-  mysql           — mysql2 auto-tracing
-  postgres        — pg auto-tracing
-  redis           — Redis auto-tracing
-
-middleware/
-  express         — Express middleware + dashboard
-```
-
----
-
-## 🛡 Production Rules
-
-1. **Debugger never blocks requests** — all logic is async & non-blocking
-2. **Debugger never crashes your app** — every operation is try/catch wrapped
-3. **Use sampling in high traffic** — set `samplingRate: 0.1` for 10% sampling
-4. **Errors always get traced** — even when sampling drops a request
-
----
-
-## 📄 License
-
-MIT
+# 🔍 flow-debugger
+
+**Production-safe flow-level debugging SDK for Node.js, Web, and React Native.**
+
+Traces requests step-by-step, measures timing, classifies errors, detects root causes, and provides endpoint analytics with a live dashboard.
+
+
+
+![Flow Debugger Dashboard](flowdebuger.png)
+---
+![PROJECT Debugger Dashboard](./FLOWDUBGERDASH.png)
+---
+## 🚀 Easy 3-Line Setup (Beginner Friendly)
+Beginners can get a professional dashboard and request tracing with just **3 lines of code**:
+
+```typescript
+const debug = flowDebugger({ enableDashboard: true }); // 1. Init
+app.use(debug.middleware);                             // 2. Middleware
+mongoTracer(mongoose, { getTracer: debug.getTracer }); // 3. Auto-Trace
+```
+
+---
+
+## ✨ Features
+
+- **Request Tracing** — Every request gets a unique `traceId` with step-by-step timing
+- **Auto-Instrument** — MongoDB, MySQL, PostgreSQL, Redis — zero extra code needed
+- **Root Cause Detection** — Automatically identifies why a request failed or was slow
+- **Error Classification** — `INFO` / `WARN` / `ERROR` / `CRITICAL` auto-categorization
+- **Timeout Detection** — Catches hanging queries/operations with configurable timeouts
+- **Slow Query Detection** — Flags slow SQL/NoSQL queries with threshold alerts
+- **Endpoint Analytics** — Per-route stats: requests, errors, slow, avg/p95/max latency
+- **Service Health Monitor** — Real-time dependency health: `Redis: healthy`, `Mongo: degraded`
+- **Live Dashboard** — Beautiful analytics UI at `/__debugger/dashboard`
+- **Console Timeline** — Visual request timeline directly in your terminal
+- **Production-Safe** — Never blocks requests, never crashes your app, all try/catch wrapped
+- **Sampling** — Configurable sampling rate for high-traffic environments
+
+---
+
+## 📦 Installation
+
+```bash
+npm install flow-debugger
+```
+
+---
+
+## 🚀 Quick Start (Express)
+
+```typescript
+import express from 'express';
+import { flowDebugger, mongoTracer, mysqlTracer, pgTracer, redisTracer } from 'flow-debugger';
+
+const app = express();
+
+// 1. Initialize debugger
+const debug = flowDebugger({
+  slowThreshold: 300,      // ms — mark steps as slow
+  slowQueryThreshold: 300, // ms — flag slow DB queries
+  enableDashboard: true,   // serve /__debugger/dashboard
+});
+
+app.use(debug.middleware);
+
+// 2. Auto-instrument databases (optional — zero code tracing!)
+mongoTracer(mongoose, { getTracer: debug.getTracer });
+mysqlTracer(mysqlPool, { getTracer: debug.getTracer });
+pgTracer(pgPool, { getTracer: debug.getTracer });
+redisTracer(redisClient, { getTracer: debug.getTracer });
+
+// 3. Use manual steps in your routes
+app.post('/api/login', async (req, res) => {
+  const tracer = req.tracer;
+
+  const user = await tracer.step('DB find user', async () => {
+    return User.findOne({ email: req.body.email });
+  }, { service: 'mongo' });
+
+  await tracer.step('Redis cache session', async () => {
+    return redis.set(`session:${user.id}`, JSON.stringify(user));
+  }, { service: 'redis' });
+
+  const token = await tracer.step('JWT generate', async () => {
+    return jwt.sign({ id: user.id }, SECRET);
+  });
+
+  res.json({ token, user });
+});
+
+app.listen(3000);
+```
+
+### Console Output:
+```
+┌─── flow-debugger ── req_m3k2_abc123_1 ── POST /api/login ───
+│ [0ms]    Request start
+│ [2ms]    DB find user ✔ (14ms) [mongo]
+│ [16ms]   Redis cache session ✔ (3ms) [redis]
+│ [20ms]   JWT generate ✔ (1ms)
+│ [21ms]   Response 200
+│
+│ Classification: INFO
+│ Total: 21ms
+└──────────────────────────────────────────────────────
+```
+
+---
+
+## 🧩 Auto-Instrument (Zero Code Tracing)
+
+```typescript
+import { mongoTracer, mysqlTracer, pgTracer, redisTracer } from 'flow-debugger';
+
+// Mongoose — patches Query.prototype.exec
+mongoTracer(mongoose, { getTracer: debug.getTracer });
+
+// mysql2 — patches pool.query() and pool.execute()
+mysqlTracer(pool, { getTracer: debug.getTracer });
+
+// pg — patches pool.query() and client.query()
+pgTracer(pgPool, { getTracer: debug.getTracer });
+
+// Redis — wraps get, set, del, hget, etc.
+redisTracer(redisClient, { getTracer: debug.getTracer });
+```
+
+**Auto output (no extra code needed):**
+```
+MySQL SELECT users → 12ms ✔
+Postgres SELECT orders → 18ms ✔
+Redis SET session → 3ms ✔
+Mongo users.findOne → 22ms ✔
+```
+
+---
+
+## ⏱ Timeout Detection
+
+```typescript
+await tracer.step('DB query', async () => {
+  return db.query('SELECT * FROM orders');
+}, { service: 'postgres', timeout: 2000 });
+```
+
+If the query takes >2s:
+```
+CRITICAL: DB query timed out after 2000ms
+Root cause: DB timeout
+```
+
+---
+
+## 🏷 Dependency Tagging
+
+```typescript
+await tracer.step('Cache lookup', fn, { service: 'redis' });
+await tracer.step('User query', fn, { service: 'postgres' });
+```
+
+Dashboard grouping:
+```
+Top failures:
+  Redis     42%
+  Postgres  33%
+  External  12%
+```
+
+---
+
+## 📊 Dashboard
+
+Access the live analytics dashboard at:
+```
+http://localhost:3000/__debugger/dashboard
+```
+
+### API Endpoints:
+| Route | Description |
+|---|---|
+| `GET /__debugger` | Full analytics JSON |
+| `GET /__debugger/dashboard` | Live HTML dashboard |
+| `GET /__debugger/health` | Service health status |
+| `GET /__debugger/endpoint?path=/api/login` | Per-endpoint stats |
+
+---
+
+## ⚙️ Configuration
+
+```typescript
+flowDebugger({
+  enabled: true,              // Enable/disable debugger
+  slowThreshold: 300,         // ms — slow step threshold
+  slowQueryThreshold: 300,    // ms — slow query threshold
+  defaultTimeout: 30000,      // ms — default step timeout
+  samplingRate: 1,            // 0-1 (1 = 100%)
+  alwaysSampleErrors: true,   // Always trace errors even if sampled out
+  maxTraces: 1000,            // Max traces in memory
+  enableTimeline: true,       // Console timeline output
+  enableDashboard: true,      // Serve /__debugger routes
+  logger: console.log,        // Custom logger function
+});
+```
+
+---
+
+## 🔍 Root Cause Detection
+
+The package automatically identifies the most likely cause of failures:
+
+| Scenario | Root Cause |
+|---|---|
+| Response 500 + Redis failed | `Redis GET failed: connection refused` |
+| DB query 900ms + total latency high | `Slow PostgreSQL query: SELECT orders (900ms)` |
+| Step timeout after 2s | `Payment API timed out after 2000ms` |
+
+---
+
+## 📡 Subpath Imports
+
+```typescript
+// Only import what you need
+import { flowDebugger } from 'flow-debugger/express';
+import { mongoTracer } from 'flow-debugger/mongo';
+import { mysqlTracer } from 'flow-debugger/mysql';
+import { pgTracer } from 'flow-debugger/postgres';
+import { redisTracer } from 'flow-debugger/redis';
+```
+
+---
+
+## 🐍 Python Support (FastAPI)
+
+Flow Debugger now supports Python applications with FastAPI integration:
+
+```python
+from fastapi import FastAPI
+from flow_debugger.fastapi_middleware import FlowDebuggerFastAPI
+
+app = FastAPI()
+
+# Initialize debugger
+debugger = FlowDebuggerFastAPI(
+    app=app,
+    debugger_url="http://localhost:3500/__debugger",
+    enabled=True,
+    slow_threshold=300
+)
+
+@app.get("/api/users")
+async def get_users(request):
+    tracer = request.state.tracer  # Available via middleware
+    
+    # Manual tracing
+    users = await trace_async_step(
+        request,
+        "DB query users", 
+        lambda: database.fetch_users(),
+        service="postgres"
+    )
+    
+    return {"users": users}
+```
+
+### Python Manual Tracing
+```python
+from flow_debugger.fastapi_middleware import traced_step
+
+@app.post("/api/orders")
+async def create_order(request):
+    with traced_step(request.state.tracer, "Validate user", "auth"):
+        user = await validate_user(request.user_id)
+    
+    with traced_step(request.state.tracer, "Create order", "postgres"):
+        order = await create_order_in_db(request.order_data)
+    
+    return {"order": order}
+```
+
+---
+
+## 📱 React Native Integration
+
+For React Native applications, use the React Native SDK:
+
+```typescript
+import { DebuggerProvider, useDebugger, traceAsyncOperation } from 'flow-debugger/react_native';
+
+// Wrap your app with the provider
+export default function App() {
+  return (
+    <DebuggerProvider debuggerUrl="http://localhost:3500/__debugger">
+      <YourAppContent />
+    </DebuggerProvider>
+  );
+}
+
+// Use in your components
+function MyComponent() {
+  const { step, startTrace } = useDebugger();
+  
+  const fetchData = async () => {
+    const traceId = startTrace('/api/data', 'GET');
+    
+    try {
+      // Trace an async operation
+      const result = await step(
+        traceId,
+        'API call',
+        () => fetch('https://api.example.com/data').then(r => r.json()),
+        { service: 'external' }
+      );
+      
+      // Send trace to dashboard
+      await sendTrace(traceId);
+      
+      return result;
+    } catch (error) {
+      await sendTrace(traceId);
+      throw error;
+    }
+  };
+  
+  // Or use the utility function
+  const fetchWithTrace = async () => {
+    return await traceAsyncOperation(
+      '/api/data',
+      'Fetch data',
+      () => fetch('https://api.example.com/data').then(r => r.json()),
+      'external'
+    );
+  };
+  
+  return <View>...</View>;
+}
+```
+
+### React Native Fetch Interceptor
+```typescript
+import { createFetchInterceptor } from 'flow-debugger/react_native';
+
+// Replace global fetch with intercepted version
+global.fetch = createFetchInterceptor("http://localhost:3500/__debugger");
+```
+
+---
+
+## 🏗 Architecture
+
+```
+core/
+  TraceEngine     — request trace lifecycle
+  Classifier      — INFO/WARN/ERROR/CRITICAL
+  RootCause       — failure origin detection
+  Analytics       — endpoint-level aggregation
+  HealthMonitor   — dependency health tracking
+  Timeline        — console renderer
+
+integrations/
+  mongo           — Mongoose auto-tracing
+  mysql           — mysql2 auto-tracing
+  postgres        — pg auto-tracing
+  redis           — Redis auto-tracing
+  fetch           — Global fetch tracing
+  axios           — Axios interceptor
+
+middleware/
+  express         — Express middleware + dashboard
+
+python-sdk/
+  fastapi_middleware — FastAPI integration
+  flow_debugger_core — Core Python classes
+
+react-native/
+  react_native    — React Native integration
+```
+
+---
+
+## 🛡 Production Rules
+
+1. **Debugger never blocks requests** — all logic is async & non-blocking
+2. **Debugger never crashes your app** — every operation is try/catch wrapped
+3. **Use sampling in high traffic** — set `samplingRate: 0.1` for 10% sampling
+4. **Errors always get traced** — even when sampling drops a request
+
+---
+
+## 📄 License
+
+MIT

package/bin/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 const pkg = require('../package.json');
-const { program } = require('commander');
+// No external dependencies needed for basic CLI
 
 function run() {
     const args = process.argv.slice(2);