🔍 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.

🚀 Easy 3-Line Setup (Beginner Friendly)

Beginners can get a professional dashboard and request tracing with just 3 lines of code:

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

npm install flow-debugger

🚀 Quick Start (Express)

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)

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

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

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

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

// 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:

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

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:

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

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