flow-debugger 1.0.0

package/src/core/Analytics.ts

@@ -0,0 +1,209 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Analytics Engine
+// Per-endpoint aggregation + service failure grouping
+// ─────────────────────────────────────────────────────────────
+
+import {
+    Trace,
+    EndpointStats,
+    AnalyticsReport,
+    ServiceFailureStats,
+    ServiceTag,
+    HealthStatus,
+} from './types';
+import { HealthMonitor } from './HealthMonitor';
+
+export class Analytics {
+    private traces: Trace[] = [];
+    private maxTraces: number;
+    private startTime: Date;
+    private healthMonitor: HealthMonitor;
+
+    constructor(maxTraces = 1000) {
+        this.maxTraces = maxTraces;
+        this.startTime = new Date();
+        this.healthMonitor = new HealthMonitor();
+    }
+
+    /** Record a completed trace */
+    record(trace: Trace): void {
+        try {
+            this.traces.push(trace);
+
+            // Trim if over limit (keep most recent)
+            if (this.traces.length > this.maxTraces) {
+                this.traces = this.traces.slice(-this.maxTraces);
+            }
+
+            // Update health monitor with step results
+            for (const step of trace.steps) {
+                this.healthMonitor.recordStep(step);
+            }
+        } catch (_) {
+            // never crash
+        }
+    }
+
+    /** Get full analytics report */
+    getReport(): AnalyticsReport {
+        const endpoints = this.getEndpointStats();
+        const totalRequests = this.traces.length;
+        const totalErrors = this.traces.filter(t => t.classification === 'ERROR' || t.classification === 'CRITICAL').length;
+        const totalSlow = this.traces.filter(t => t.classification === 'WARN').length;
+        const uptime = Date.now() - this.startTime.getTime();
+
+        return {
+            totalRequests,
+            totalErrors,
+            totalSlow,
+            uptime,
+            endpoints,
+            serviceHealth: this.healthMonitor.getAllHealth(),
+            topFailures: this.getTopFailures(),
+            recentTraces: this.traces.slice(-20).reverse(),
+        };
+    }
+
+    /** Get stats for a specific endpoint */
+    getEndpointReport(path: string): EndpointStats | null {
+        const stats = this.getEndpointStats();
+        return stats.find(s => s.path === path) || null;
+    }
+
+    /** Get aggregated stats per endpoint */
+    private getEndpointStats(): EndpointStats[] {
+        const grouped = new Map<string, Trace[]>();
+
+        for (const trace of this.traces) {
+            const key = `${trace.method}:${trace.endpoint}`;
+            if (!grouped.has(key)) grouped.set(key, []);
+            grouped.get(key)!.push(trace);
+        }
+
+        const stats: EndpointStats[] = [];
+        for (const [key, traces] of grouped) {
+            const [method, path] = key.split(':');
+            const durations = traces.map(t => t.totalDuration).sort((a, b) => a - b);
+            const errorCount = traces.filter(t => t.classification === 'ERROR' || t.classification === 'CRITICAL').length;
+            const slowCount = traces.filter(t => t.classification === 'WARN').length;
+
+            // Common issues
+            const issues = new Map<string, number>();
+            for (const t of traces) {
+                if (t.rootCause) {
+                    const key = t.rootCause.cause;
+                    issues.set(key, (issues.get(key) || 0) + 1);
+                }
+            }
+            const commonIssues = [...issues.entries()]
+                .sort((a, b) => b[1] - a[1])
+                .slice(0, 5)
+                .map(([issue, count]) => `${issue} (${count}x)`);
+
+            // Service failure breakdown
+            const serviceFailures = this.getServiceFailures(traces);
+
+            stats.push({
+                path,
+                method,
+                totalRequests: traces.length,
+                errorCount,
+                slowCount,
+                avgDuration: durations.reduce((a, b) => a + b, 0) / durations.length,
+                p95Duration: durations[Math.floor(durations.length * 0.95)] || 0,
+                maxDuration: durations[durations.length - 1] || 0,
+                commonIssues,
+                serviceFailures,
+                recentTraces: traces.slice(-5).reverse(),
+            });
+        }
+
+        return stats.sort((a, b) => b.totalRequests - a.totalRequests);
+    }
+
+    /** Get service failure breakdown across all traces */
+    private getTopFailures(): ServiceFailureStats[] {
+        return this.getServiceFailures(this.traces);
+    }
+
+    /** Calculate service failure stats from a set of traces */
+    private getServiceFailures(traces: Trace[]): ServiceFailureStats[] {
+        const failures = new Map<ServiceTag, number>();
+        let totalFailures = 0;
+
+        for (const trace of traces) {
+            for (const step of trace.steps) {
+                if (step.status === 'error' || step.status === 'timeout') {
+                    failures.set(step.service, (failures.get(step.service) || 0) + 1);
+                    totalFailures++;
+                }
+            }
+        }
+
+        return [...failures.entries()]
+            .map(([service, count]) => ({
+                service,
+                count,
+                percentage: totalFailures > 0 ? Math.round((count / totalFailures) * 100) : 0,
+            }))
+            .sort((a, b) => b.count - a.count);
+    }
+
+    /** Clear all stored traces */
+    clear(): void {
+        this.traces = [];
+    }
+
+    /** Get raw trace count */
+    getTraceCount(): number {
+        return this.traces.length;
+    }
+
+    /**
+     * Search traces by traceId, endpoint, or error message.
+     * Returns matching traces sorted by most recent first.
+     */
+    searchTraces(query: string, options?: { env?: string; limit?: number }): Trace[] {
+        if (!query) return [];
+
+        const lowerQuery = query.toLowerCase();
+        const limit = options?.limit || 50;
+
+        const matches = this.traces.filter(trace => {
+            // Filter by environment if specified
+            if (options?.env && trace.environment !== options.env) {
+                return false;
+            }
+
+            // Match traceId
+            if (trace.traceId.toLowerCase().includes(lowerQuery)) {
+                return true;
+            }
+
+            // Match endpoint
+            if (trace.endpoint.toLowerCase().includes(lowerQuery)) {
+                return true;
+            }
+
+            // Match error message in steps
+            for (const step of trace.steps) {
+                if (step.error && step.error.toLowerCase().includes(lowerQuery)) {
+                    return true;
+                }
+            }
+
+            // Match root cause
+            if (trace.rootCause && trace.rootCause.cause.toLowerCase().includes(lowerQuery)) {
+                return true;
+            }
+
+            return false;
+        });
+
+        return matches.slice(-limit).reverse();
+    }
+
+    getHealthMonitor(): HealthMonitor {
+        return this.healthMonitor;
+    }
+}

package/src/core/Classifier.ts

@@ -0,0 +1,82 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Classifier
+// Classifies steps and traces into severity levels
+// ─────────────────────────────────────────────────────────────
+
+import {
+    ClassificationLevel,
+    StepStatus,
+    TraceStep,
+    DebuggerConfig,
+} from './types';
+
+/**
+ * Classify a single step based on its duration and status.
+ *
+ *  INFO     → normal, <slowThreshold ms
+ *  WARN     → slow (>slowThreshold ms)
+ *  ERROR    → step failed
+ *  CRITICAL → dependency down / timeout
+ */
+export function classify(
+    duration: number,
+    status: StepStatus,
+    config: Pick<DebuggerConfig, 'slowThreshold'>,
+): ClassificationLevel {
+    const threshold = config.slowThreshold ?? 300;
+
+    if (status === 'timeout') return 'CRITICAL';
+    if (status === 'error') return 'ERROR';
+    if (duration > threshold) return 'WARN';
+    return 'INFO';
+}
+
+/**
+ * Classify an entire trace based on its steps.
+ * The trace gets the highest severity from any of its steps.
+ */
+export function classifyTrace(
+    steps: TraceStep[],
+    _totalDuration: number,
+    config: Pick<DebuggerConfig, 'slowThreshold'>,
+): ClassificationLevel {
+    const threshold = config.slowThreshold ?? 300;
+    let maxLevel: ClassificationLevel = 'INFO';
+
+    const priority: Record<ClassificationLevel, number> = {
+        INFO: 0,
+        WARN: 1,
+        ERROR: 2,
+        CRITICAL: 3,
+    };
+
+    for (const step of steps) {
+        if (priority[step.classification] > priority[maxLevel]) {
+            maxLevel = step.classification;
+        }
+    }
+
+    // Also check total duration
+    if (maxLevel === 'INFO' && _totalDuration > threshold) {
+        maxLevel = 'WARN';
+    }
+
+    return maxLevel;
+}
+
+/**
+ * Classify a database query specifically — used by integrations
+ * to detect slow queries with a dedicated threshold.
+ */
+export function classifyQuery(
+    duration: number,
+    status: StepStatus,
+    config: Pick<DebuggerConfig, 'slowQueryThreshold'>,
+): ClassificationLevel {
+    const threshold = config.slowQueryThreshold ?? 300;
+
+    if (status === 'timeout') return 'CRITICAL';
+    if (status === 'error') return 'ERROR';
+    if (duration > threshold) return 'WARN';
+    return 'INFO';
+}

package/src/core/HealthMonitor.ts

@@ -0,0 +1,92 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Health Monitor
+// Tracks dependency health from step results
+// ─────────────────────────────────────────────────────────────
+
+import {
+    TraceStep,
+    HealthStatus,
+    HealthState,
+    ServiceTag,
+} from './types';
+
+interface HealthRecord {
+    service: ServiceTag;
+    name: string;
+    successes: number;
+    failures: number;
+    lastCheck: Date;
+}
+
+export class HealthMonitor {
+    private records = new Map<string, HealthRecord>();
+
+    /** Record a step result to update health tracking */
+    recordStep(step: TraceStep): void {
+        try {
+            const key = step.service;
+            if (key === 'internal' || key === 'unknown') return;
+
+            if (!this.records.has(key)) {
+                this.records.set(key, {
+                    service: step.service,
+                    name: key,
+                    successes: 0,
+                    failures: 0,
+                    lastCheck: new Date(),
+                });
+            }
+
+            const record = this.records.get(key)!;
+            record.lastCheck = new Date();
+
+            if (step.status === 'success') {
+                record.successes++;
+            } else {
+                record.failures++;
+            }
+        } catch (_) {
+            // never crash
+        }
+    }
+
+    /** Get health status for a specific service */
+    getHealth(service: ServiceTag): HealthStatus | null {
+        const record = this.records.get(service);
+        if (!record) return null;
+        return this.toHealthStatus(record);
+    }
+
+    /** Get health status for all tracked services */
+    getAllHealth(): HealthStatus[] {
+        return [...this.records.values()].map(r => this.toHealthStatus(r));
+    }
+
+    private toHealthStatus(record: HealthRecord): HealthStatus {
+        const total = record.successes + record.failures;
+        const successRate = total > 0 ? record.successes / total : 1;
+
+        let status: HealthState;
+        if (successRate >= 0.95) {
+            status = 'healthy';
+        } else if (successRate >= 0.7) {
+            status = 'degraded';
+        } else {
+            status = 'down';
+        }
+
+        return {
+            service: record.service,
+            name: record.name,
+            status,
+            lastCheck: record.lastCheck,
+            successRate: Math.round(successRate * 100),
+            totalChecks: total,
+        };
+    }
+
+    /** Reset all health records */
+    reset(): void {
+        this.records.clear();
+    }
+}

package/src/core/RootCause.ts

@@ -0,0 +1,105 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Root Cause Detection
+// Analyzes trace steps to identify the most likely failure origin
+// ─────────────────────────────────────────────────────────────
+
+import {
+    TraceStep,
+    RootCauseResult,
+    DebuggerConfig,
+    ServiceTag,
+} from './types';
+
+/**
+ * Detect the root cause of a trace failure or slowness.
+ *
+ * Algorithm:
+ *  1. If response is 500 and a step failed → root cause = first failed step
+ *  2. If a step timed out → root cause = timeout step (CRITICAL)
+ *  3. If DB/Redis slow and total latency high → root cause = slow dependency
+ *  4. If no failures but overall slow → root cause = slowest step
+ */
+export function detectRootCause(
+    steps: TraceStep[],
+    statusCode: number | undefined,
+    config: Pick<DebuggerConfig, 'slowThreshold' | 'slowQueryThreshold'>,
+): RootCauseResult | null {
+    if (steps.length === 0) return null;
+
+    const slowThreshold = config.slowThreshold ?? 300;
+
+    // 1. Look for timed-out steps (highest priority)
+    const timedOut = steps.find(s => s.status === 'timeout');
+    if (timedOut) {
+        return {
+            cause: `${timedOut.name} timed out`,
+            step: timedOut.name,
+            service: timedOut.service,
+            confidence: 'high',
+        };
+    }
+
+    // 2. Look for failed steps when response is 5xx
+    if (statusCode && statusCode >= 500) {
+        const failedSteps = steps.filter(s => s.status === 'error');
+        if (failedSteps.length > 0) {
+            // First failure is most likely root cause
+            const first = failedSteps[0];
+            return {
+                cause: `${first.name} failed: ${first.error || 'unknown error'}`,
+                step: first.name,
+                service: first.service,
+                confidence: 'high',
+            };
+        }
+    }
+
+    // 3. Look for any failed step (even if response isn't 500)
+    const failedStep = steps.find(s => s.status === 'error');
+    if (failedStep) {
+        return {
+            cause: `${failedStep.name} failed: ${failedStep.error || 'unknown error'}`,
+            step: failedStep.name,
+            service: failedStep.service,
+            confidence: statusCode && statusCode >= 400 ? 'high' : 'medium',
+        };
+    }
+
+    // 4. Look for slow steps
+    const slowSteps = steps.filter(s => s.duration > slowThreshold);
+    if (slowSteps.length > 0) {
+        // Slowest step is the most likely bottleneck
+        const slowest = slowSteps.reduce((a, b) => (a.duration > b.duration ? a : b));
+        const totalDuration = steps.reduce((sum, s) => sum + s.duration, 0);
+        const ratio = slowest.duration / totalDuration;
+
+        return {
+            cause: `Slow ${getServiceLabel(slowest.service)} query: ${slowest.name} (${Math.round(slowest.duration)}ms)`,
+            step: slowest.name,
+            service: slowest.service,
+            confidence: ratio > 0.5 ? 'high' : 'medium',
+        };
+    }
+
+    return null;
+}
+
+function getServiceLabel(service: ServiceTag): string {
+    const labels: Record<ServiceTag, string> = {
+        mongo: 'MongoDB',
+        mysql: 'MySQL',
+        postgres: 'PostgreSQL',
+        redis: 'Redis',
+        axios: 'HTTP',
+        fetch: 'HTTP',
+        stripe: 'Stripe',
+        razorpay: 'Razorpay',
+        sendgrid: 'SendGrid',
+        twilio: 'Twilio',
+        external: 'External',
+        internal: 'Internal',
+        unknown: 'Unknown',
+    };
+    return labels[service] || service;
+}
+

package/src/core/Sampler.ts

@@ -0,0 +1,35 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Sampler
+// Probabilistic sampling for high-traffic environments
+// ─────────────────────────────────────────────────────────────
+
+export class Sampler {
+    private rate: number;
+    private alwaysSampleErrors: boolean;
+
+    constructor(rate = 1, alwaysSampleErrors = true) {
+        this.rate = Math.max(0, Math.min(1, rate));
+        this.alwaysSampleErrors = alwaysSampleErrors;
+    }
+
+    /** Should this request be sampled? */
+    shouldSample(): boolean {
+        if (this.rate >= 1) return true;
+        if (this.rate <= 0) return false;
+        return Math.random() < this.rate;
+    }
+
+    /** Force sample if it's an error (if alwaysSampleErrors is true) */
+    shouldSampleError(): boolean {
+        return this.alwaysSampleErrors;
+    }
+
+    /** Update sampling rate at runtime */
+    setRate(rate: number): void {
+        this.rate = Math.max(0, Math.min(1, rate));
+    }
+
+    getRate(): number {
+        return this.rate;
+    }
+}

package/src/core/Timeline.ts

@@ -0,0 +1,108 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Timeline Renderer
+// Prints a visual timeline of a trace to the console
+// ─────────────────────────────────────────────────────────────
+
+import { Trace, ClassificationLevel } from './types';
+
+const ICONS: Record<string, string> = {
+    success: '✔',
+    error: '❌',
+    timeout: '⏱ TIMEOUT',
+};
+
+const LEVEL_COLORS: Record<ClassificationLevel, string> = {
+    INFO: '\x1b[32m',     // green
+    WARN: '\x1b[33m',     // yellow
+    ERROR: '\x1b[31m',    // red
+    CRITICAL: '\x1b[35m', // magenta
+};
+
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const CYAN = '\x1b[36m';
+
+/**
+ * Render a trace timeline to the console.
+ *
+ * Output example:
+ * ┌─── flow-debugger ── req_abc123 ── POST /login ───
+ * │ [0ms]   Request start
+ * │ [2ms]   DB find user ✔ (14ms) [mongo]
+ * │ [16ms]  Redis cache ❌ (3ms) [redis]
+ * │ [20ms]  Response 200
+ * │
+ * │ ⚠ Root cause: Redis cache failed: connection refused
+ * │ Classification: ERROR
+ * │ Total: 20ms
+ * └────────────────────────────────────────────────────
+ */
+export function renderTimeline(
+    trace: Trace,
+    logger: (...args: unknown[]) => void = console.log,
+): void {
+    const lines: string[] = [];
+    const divider = '─'.repeat(50);
+
+    lines.push('');
+    lines.push(`${CYAN}┌─── flow-debugger ── ${trace.traceId} ── ${trace.method} ${trace.endpoint} ───${RESET}`);
+    lines.push(`${DIM}│ [0ms]    Request start${RESET}`);
+
+    for (const step of trace.steps) {
+        const offset = Math.round(step.startTime);
+        const dur = Math.round(step.duration);
+        const icon = ICONS[step.status] || '?';
+        const levelColor = LEVEL_COLORS[step.classification] || '';
+        const serviceTag = step.service !== 'internal' ? ` ${DIM}[${step.service}]${RESET}` : '';
+
+        const line = `│ [${offset}ms]${' '.repeat(Math.max(1, 5 - String(offset).length))}` +
+            `${levelColor}${step.name} ${icon} (${dur}ms)${RESET}${serviceTag}`;
+
+        lines.push(line);
+
+        if (step.error) {
+            lines.push(`│         ${DIM}└─ ${step.error}${RESET}`);
+        }
+
+        // Slow query warning
+        if (step.classification === 'WARN' && step.duration > 300) {
+            lines.push(`│         ${LEVEL_COLORS.WARN}⚠ Slow ${step.service} query detected (${dur}ms)${RESET}`);
+        }
+    }
+
+    // Response line
+    lines.push(`${DIM}│ [${Math.round(trace.totalDuration)}ms]${' '.repeat(Math.max(1, 5 - String(Math.round(trace.totalDuration)).length))}Response ${trace.statusCode || '—'}${RESET}`);
+    lines.push('│');
+
+    // Root cause
+    if (trace.rootCause) {
+        const rcColor = LEVEL_COLORS.ERROR;
+        lines.push(`${rcColor}│ 🔍 Root cause: ${trace.rootCause.cause}${RESET}`);
+        lines.push(`${DIM}│    Service: ${trace.rootCause.service} | Confidence: ${trace.rootCause.confidence}${RESET}`);
+    }
+
+    // Classification
+    const clsColor = LEVEL_COLORS[trace.classification];
+    lines.push(`${clsColor}│ Classification: ${trace.classification}${RESET}`);
+    lines.push(`${DIM}│ Total: ${Math.round(trace.totalDuration)}ms${RESET}`);
+    lines.push(`${CYAN}└${divider}${RESET}`);
+    lines.push('');
+
+    logger(lines.join('\n'));
+}
+
+/**
+ * Render a compact one-line summary for high-traffic mode.
+ */
+export function renderCompact(
+    trace: Trace,
+    logger: (...args: unknown[]) => void = console.log,
+): void {
+    const icon = trace.classification === 'INFO' ? '✔' :
+        trace.classification === 'WARN' ? '⚠' :
+            trace.classification === 'ERROR' ? '❌' :
+                '🔴';
+    const rc = trace.rootCause ? ` → ${trace.rootCause.cause}` : '';
+    logger(`${icon} ${trace.method} ${trace.endpoint} ${Math.round(trace.totalDuration)}ms [${trace.classification}]${rc}`);
+}