flow-debugger
v1.9.5 • STABLE
Debug your application flow with high granularity and low overhead.
Readme.md
# 🔍 flow-debugger
> [!IMPORTANT]
> **Production-safe flow-level debugging SDK for Node.js, Web, and React Native.**
<p align="center">
<strong>🔬 Trace Requests Step-by-Step with Root Cause Detection</strong>
</p>
<div align="center">
<img src="https://img.shields.io/npm/v/flow-debugger" alt="NPM Version">
<img src="https://img.shields.io/bundlephobia/minzip/flow-debugger" alt="Bundle Size">
<img src="https://img.shields.io/npm/dm/flow-debugger" alt="Downloads">
<img src="https://img.shields.io/badge/TypeScript-100%25-blue" alt="TypeScript">
<img src="https://img.shields.io/badge/Node.js-14%2B-green" alt="Node.js 14+">
</div>
---
## 🌟 Core Highlights
> **"Debug production issues in minutes, not hours."**
> - **3-Line Setup** — Professional dashboard in minutes
> - **Auto-Instrument** — MongoDB, MySQL, PostgreSQL, Redis — zero code
> - **Root Cause Detection** — Automatically identifies failures
> - **Never Crashes** — All try/catch wrapped, production-safe
---
## 📊 Dashboard Preview
### **Flow Debugger Dashboard**
Traces requests step-by-step with timing analytics:
```
┌─── 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
└──────────────────────────────────────────────────────
```
---
## 🏗️ Architecture
### **System Flow**
```mermaid
graph LR
A[Request Starts] --> B[Flow Tracer]
B --> C[Internal Logic Steps]
C --> D[Trace Injection]
D --> E[Real-Time Dashboard]
E --> F[Success/Error Monitoring]
```
### **Request Lifecycle**
```mermaid
graph TB
A[Incoming Request] --> B[Generate traceId]
B --> C[Create Tracer]
C --> D[Execute Steps]
D --> E{Step Success?}
E -->|Yes| F[Record Timing]
E -->|No| G[Classify Error]
F --> H[Send to Dashboard]
G --> H
H --> I[Update Analytics]
```
### **Core Components**
```mermaid
graph TB
A[Express Middleware] --> B[Tracer Factory]
B --> C[Step Executor]
C --> D[Timing Calculator]
D --> E[Error Classifier]
E --> F[Root Cause Detector]
F --> G[Dashboard API]
F --> H[Console Timeline]
F --> I[Analytics Engine]
G --> J[Live Dashboard]
H --> K[Terminal Output]
I --> L[Endpoint Stats]
```
---
## ✨ Key Features
### 🔬 **Request Tracing**
- **Unique traceId** — Every request gets a unique identifier
- **Step-by-step timing** — Precise measurement for each operation
- **Service detection** — Auto-identifies MongoDB, Redis, MySQL, etc.
- **Console timeline** — Visual request flow in terminal
### 🎯 **Auto-Instrumentation**
| Database | Status | Operations Traced |
|----------|--------|-------------------|
| **MongoDB** | ✅ Full | find, findOne, insert, update, delete |
| **MySQL** | ✅ Full | query, execute |
| **PostgreSQL** | ✅ Full | query |
| **Redis** | ✅ Full | get, set, del, hget, hset |
### 🚨 **Error Intelligence**
- **Error Classification** — INFO / WARN / ERROR / CRITICAL
- **Root Cause Detection** — Identifies why requests fail
- **Timeout Detection** — Catches hanging queries/operations
- **Slow Query Detection** — Flags slow DB operations
### 📊 **Analytics Dashboard**
- **Endpoint Analytics** — Per-route stats (requests, errors, latency)
- **Service Health Monitor** — Real-time dependency health
- **Live Dashboard** — Beautiful UI at `/__debugger/dashboard`
- **P95/P99 Metrics** — Advanced latency percentiles
### 🛡️ **Production-Safe**
- **Never blocks** — All async, non-blocking
- **Never crashes** — All try/catch wrapped
- **Sampling support** — Configurable rate for high-traffic
- **Zero dependencies** — Lightweight core
---
## 📦 Package Info
- **Version**: 1.9.5
- **License**: MIT
- **TypeScript**: 100% type-safe
- **Node.js**: >=14.0.0
- **Dependencies**: 0 production dependencies
- **Peer Dependencies**: Express, Mongoose, MySQL2, PG, Redis (optional)
---
## 🧪 Testing
### **Test Coverage**
```bash
npm test
```
---
## 📈 Version History
| Version | Features | Status |
|---------|----------|--------|
| **1.0.0 - 1.5.0** | Basic tracing | ✅ Stable |
| **1.5.1 - 1.8.0** | Auto-instrument | ✅ Stable |
| **1.8.1 - 1.9.5** | Root cause detection | ✅ Current |
---
## 🔗 Links
- **GitHub**: [flow-debugger](https://github.com/sannuk79/PROJECTS-AND-NPM-PACKAGES-)
- **NPM**: [flow-debugger](https://www.npmjs.com/package/flow-debugger)
- **Issues**: [Report a bug](https://github.com/sannuk79/debugerpackages/issues)