flow-debugger 1.0.0

package/src/core/TraceEngine.ts

@@ -0,0 +1,266 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Trace Engine
+// Manages trace lifecycle: create → add steps → end
+// ─────────────────────────────────────────────────────────────
+
+import { EventEmitter } from 'events';
+import {
+    Trace,
+    TraceStep,
+    StepOptions,
+    StepStatus,
+    ClassificationLevel,
+    DebuggerConfig,
+    DEFAULT_CONFIG,
+    ServiceTag,
+} from './types';
+import { classify, classifyTrace } from './Classifier';
+import { detectRootCause } from './RootCause';
+import { renderTimeline } from './Timeline';
+
+let idCounter = 0;
+
+/** Generate a unique trace ID */
+function generateTraceId(): string {
+    const ts = Date.now().toString(36);
+    const rand = Math.random().toString(36).substring(2, 8);
+    idCounter++;
+    return `req_${ts}_${rand}_${idCounter}`;
+}
+
+/**
+ * Extract file and line number from stack trace for dashboard preview.
+ * Example: "at Object.<anonymous> (d:\\project\\auth.service.ts:42:15)"
+ * Returns: { file: "auth.service.ts", line: 42 }
+ */
+function extractErrorLocation(stackTrace?: string): { file?: string; line?: number } {
+    if (!stackTrace) return {};
+
+    try {
+        // Match patterns like:
+        // at functionName (file.ts:42:15)
+        // at file.ts:42:15
+        const match = stackTrace.match(/\(([^)]+):(\d+):\d+\)/) || stackTrace.match(/at\s+([^:]+):(\d+):\d+/);
+        if (match) {
+            const fullPath = match[1];
+            const lineNum = parseInt(match[2], 10);
+
+            // Extract just the filename from full path
+            const fileName = fullPath.split(/[/\\]/).pop() || fullPath;
+
+            return { file: fileName, line: lineNum };
+        }
+    } catch (_) {
+        // ignore parse errors
+    }
+
+    return {};
+}
+
+
+/**
+ * TraceEngine — manages the lifecycle of a single request trace.
+ * 
+ * Usage:
+ *   const engine = new TraceEngine(config);
+ *   const tracer = engine.startTrace('/login', 'POST');
+ *   await tracer.step('DB find user', async () => User.findOne(), { service: 'mongo' });
+ *   tracer.end(200);
+ */
+export class TraceEngine extends EventEmitter {
+    private config: Required<DebuggerConfig>;
+
+    constructor(config?: DebuggerConfig) {
+        super();
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+
+    /** Update config at runtime */
+    updateConfig(patch: Partial<DebuggerConfig>): void {
+        Object.assign(this.config, patch);
+    }
+
+    getConfig(): Required<DebuggerConfig> {
+        return { ...this.config };
+    }
+
+    /** Start a new request trace */
+    startTrace(endpoint: string, method: string): RequestTracer {
+        const tracer = new RequestTracer(endpoint, method, this.config, this);
+        this.safeEmit('trace:start', { traceId: tracer.getTraceId(), endpoint, method });
+        return tracer;
+    }
+
+    /** Safe emit — never throws */
+    safeEmit(event: string, data: unknown): void {
+        try {
+            this.emit(event, data);
+        } catch (_) {
+            // debugger never crashes the app
+        }
+    }
+}
+
+/**
+ * RequestTracer — the object attached to a single request.
+ * Provides `step()` for manual instrumentation and `addStep()` for auto-instrumentation.
+ */
+export class RequestTracer {
+    private traceId: string;
+    private endpoint: string;
+    private method: string;
+    private steps: TraceStep[] = [];
+    private startTime: number;
+    private config: Required<DebuggerConfig>;
+    private engine: TraceEngine;
+    private ended = false;
+
+    constructor(
+        endpoint: string,
+        method: string,
+        config: Required<DebuggerConfig>,
+        engine: TraceEngine,
+    ) {
+        this.traceId = generateTraceId();
+        this.endpoint = endpoint;
+        this.method = method;
+        this.startTime = performance.now();
+        this.config = config;
+        this.engine = engine;
+    }
+
+    getTraceId(): string {
+        return this.traceId;
+    }
+
+    getSteps(): TraceStep[] {
+        return [...this.steps];
+    }
+
+    /** Manually run & trace an async step */
+    async step<T>(name: string, fn: () => Promise<T> | T, options?: StepOptions): Promise<T> {
+        const service: ServiceTag = options?.service ?? 'internal';
+        const timeout = options?.timeout ?? this.config.defaultTimeout;
+        const stepStart = performance.now();
+        let status: StepStatus = 'success';
+        let error: string | undefined;
+        let stackTrace: string | undefined;
+        let result: T;
+
+        try {
+            // Race the function against a timeout
+            result = await Promise.race([
+                Promise.resolve(fn()),
+                new Promise<never>((_, reject) =>
+                    setTimeout(() => reject(new Error(`Step "${name}" timed out after ${timeout}ms`)), timeout),
+                ),
+            ]);
+        } catch (err: unknown) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            if (e.message.includes('timed out')) {
+                status = 'timeout';
+            } else {
+                status = 'error';
+            }
+            error = e.message;
+            stackTrace = e.stack;
+            const { file: errorFile, line: errorLine } = extractErrorLocation(stackTrace);
+
+            // Re-throw so the caller can handle the error
+            const stepEnd = performance.now();
+            const duration = stepEnd - stepStart;
+            const classification = classify(duration, status, this.config);
+
+            this.steps.push({
+                name,
+                service,
+                status,
+                classification,
+                startTime: stepStart - this.startTime,
+                endTime: stepEnd - this.startTime,
+                duration,
+                error,
+                stackTrace,
+                errorFile,
+                errorLine,
+                metadata: options?.metadata,
+            });
+
+            throw err;
+        }
+
+        const stepEnd = performance.now();
+        const duration = stepEnd - stepStart;
+        const classification = classify(duration, status, this.config);
+        const { file: errorFile, line: errorLine } = error ? extractErrorLocation(stackTrace) : {};
+
+        this.steps.push({
+            name,
+            service,
+            status,
+            classification,
+            startTime: stepStart - this.startTime,
+            endTime: stepEnd - this.startTime,
+            duration,
+            error,
+            stackTrace,
+            errorFile,
+            errorLine,
+            metadata: options?.metadata,
+        });
+
+        return result;
+    }
+
+    /** Add a pre-recorded step (used by auto-integrations) */
+    addStep(step: TraceStep): void {
+        try {
+            this.steps.push(step);
+        } catch (_) {
+            // never crash
+        }
+    }
+
+    /** End the trace and produce the final result */
+    end(statusCode?: number): Trace {
+        if (this.ended) {
+            return this.buildTrace(statusCode);
+        }
+        this.ended = true;
+
+        const trace = this.buildTrace(statusCode);
+
+        // Render timeline to console
+        if (this.config.enableTimeline) {
+            try {
+                renderTimeline(trace, this.config.logger);
+            } catch (_) {
+                // never crash
+            }
+        }
+
+        this.engine.safeEmit('trace:end', trace);
+        return trace;
+    }
+
+    private buildTrace(statusCode?: number): Trace {
+        const endTime = performance.now();
+        const totalDuration = endTime - this.startTime;
+        const traceClassification = classifyTrace(this.steps, totalDuration, this.config);
+        const rootCause = detectRootCause(this.steps, statusCode, this.config);
+
+        return {
+            traceId: this.traceId,
+            endpoint: this.endpoint,
+            method: this.method,
+            statusCode,
+            steps: [...this.steps],
+            totalDuration,
+            classification: traceClassification,
+            rootCause,
+            startTime: 0,
+            endTime: totalDuration,
+            timestamp: new Date(),
+        };
+    }
+}

package/src/core/types.ts

@@ -0,0 +1,170 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Core Type Definitions
+// ─────────────────────────────────────────────────────────────
+
+/** Classification severity levels */
+export type ClassificationLevel = 'INFO' | 'WARN' | 'ERROR' | 'CRITICAL';
+
+/** Known service/dependency types for tagging */
+export type ServiceTag =
+    | 'mongo'
+    | 'mysql'
+    | 'postgres'
+    | 'redis'
+    | 'axios'
+    | 'fetch'
+    | 'stripe'
+    | 'razorpay'
+    | 'sendgrid'
+    | 'twilio'
+    | 'external'
+    | 'internal'
+    | 'unknown';
+
+/** Health status for a dependency */
+export type HealthState = 'healthy' | 'degraded' | 'down';
+
+/** Status of a single traced step */
+export type StepStatus = 'success' | 'error' | 'timeout';
+
+// ─── Step & Trace ────────────────────────────────────────────
+
+/** A single measured step within a trace */
+export interface TraceStep {
+    name: string;
+    service: ServiceTag;
+    status: StepStatus;
+    classification: ClassificationLevel;
+    startTime: number;       // high-res timestamp (ms)
+    endTime: number;
+    duration: number;        // ms
+    error?: string;
+    stackTrace?: string;
+    errorFile?: string;      // extracted from stack trace
+    errorLine?: number;      // extracted from stack trace
+    metadata?: Record<string, unknown>;
+}
+
+/** Options passed to `step()` */
+export interface StepOptions {
+    /** Service tag for grouping  (e.g. 'postgres', 'redis') */
+    service?: ServiceTag;
+    /** Timeout in ms — triggers StepStatus.timeout if exceeded */
+    timeout?: number;
+    /** Arbitrary metadata attached to the step */
+    metadata?: Record<string, unknown>;
+}
+
+/** A complete request trace */
+export interface Trace {
+    traceId: string;
+    endpoint: string;
+    method: string;
+    statusCode?: number;
+    steps: TraceStep[];
+    totalDuration: number;
+    classification: ClassificationLevel;
+    rootCause: RootCauseResult | null;
+    startTime: number;
+    endTime: number;
+    timestamp: Date;
+    environment?: string;     // dev / staging / production
+    payloadSize?: number;     // request body size in bytes
+}
+
+// ─── Root Cause ──────────────────────────────────────────────
+
+export interface RootCauseResult {
+    cause: string;
+    step: string;
+    service: ServiceTag;
+    confidence: 'high' | 'medium' | 'low';
+}
+
+// ─── Analytics ───────────────────────────────────────────────
+
+export interface ServiceFailureStats {
+    service: ServiceTag;
+    count: number;
+    percentage: number;
+}
+
+export interface EndpointStats {
+    path: string;
+    method: string;
+    totalRequests: number;
+    errorCount: number;
+    slowCount: number;
+    avgDuration: number;
+    p95Duration: number;
+    maxDuration: number;
+    commonIssues: string[];
+    serviceFailures: ServiceFailureStats[];
+    recentTraces: Trace[];
+}
+
+export interface AnalyticsReport {
+    totalRequests: number;
+    totalErrors: number;
+    totalSlow: number;
+    uptime: number;
+    endpoints: EndpointStats[];
+    serviceHealth: HealthStatus[];
+    topFailures: ServiceFailureStats[];
+    recentTraces: Trace[];
+}
+
+// ─── Health ──────────────────────────────────────────────────
+
+export interface HealthStatus {
+    service: ServiceTag;
+    name: string;
+    status: HealthState;
+    lastCheck: Date;
+    successRate: number;
+    totalChecks: number;
+}
+
+// ─── Config ──────────────────────────────────────────────────
+
+export interface DebuggerConfig {
+    /** Enable/disable the debugger (default: true) */
+    enabled?: boolean;
+    /** Environment tag (dev / staging / production) */
+    environment?: string;
+    /** Threshold in ms to mark a step as slow (default: 300) */
+    slowThreshold?: number;
+    /** Threshold in ms for slow SQL/DB query detection (default: 300) */
+    slowQueryThreshold?: number;
+    /** Default step timeout in ms (default: 30000) */
+    defaultTimeout?: number;
+    /** Sampling rate 0-1 (default: 1 = 100%) */
+    samplingRate?: number;
+    /** Always sample errors even if sampling drops the request (default: true) */
+    alwaysSampleErrors?: boolean;
+    /** Max traces to keep in memory for analytics (default: 1000) */
+    maxTraces?: number;
+    /** Enable console timeline output (default: true) */
+    enableTimeline?: boolean;
+    /** Enable the /__debugger dashboard (default: true) */
+    enableDashboard?: boolean;
+    /** Payload size threshold in bytes to warn (default: 1MB) */
+    largePayloadThreshold?: number;
+    /** Custom logger function */
+    logger?: (...args: unknown[]) => void;
+}
+
+export const DEFAULT_CONFIG: Required<DebuggerConfig> = {
+    enabled: true,
+    environment: process.env.NODE_ENV || 'development',
+    slowThreshold: 300,
+    slowQueryThreshold: 300,
+    defaultTimeout: 30000,
+    samplingRate: 1,
+    alwaysSampleErrors: true,
+    maxTraces: 1000,
+    enableTimeline: true,
+    enableDashboard: true,
+    largePayloadThreshold: 1024 * 1024, // 1MB
+    logger: console.log,
+};

package/src/index.ts

@@ -0,0 +1,42 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Main Entry Point
+// ─────────────────────────────────────────────────────────────
+
+// Core
+export { TraceEngine, RequestTracer } from './core/TraceEngine';
+export { classify, classifyTrace, classifyQuery } from './core/Classifier';
+export { detectRootCause } from './core/RootCause';
+export { Analytics } from './core/Analytics';
+export { HealthMonitor } from './core/HealthMonitor';
+export { Sampler } from './core/Sampler';
+export { renderTimeline, renderCompact } from './core/Timeline';
+
+// Types
+export type {
+    ClassificationLevel,
+    ServiceTag,
+    HealthState,
+    StepStatus,
+    TraceStep,
+    StepOptions,
+    Trace,
+    RootCauseResult,
+    ServiceFailureStats,
+    EndpointStats,
+    AnalyticsReport,
+    HealthStatus,
+    DebuggerConfig,
+} from './core/types';
+export { DEFAULT_CONFIG } from './core/types';
+
+// Integrations
+export { mongoTracer, removeMongoTracer } from './integrations/mongo';
+export { mysqlTracer } from './integrations/mysql';
+export { pgTracer } from './integrations/postgres';
+export { redisTracer } from './integrations/redis';
+export { fetchTracer, removeFetchTracer } from './integrations/fetch';
+export { axiosTracer } from './integrations/axios';
+
+// Middleware
+export { flowDebugger } from './middleware/express';
+export type { FlowDebuggerMiddleware } from './middleware/express';

package/src/integrations/axios.ts

@@ -0,0 +1,164 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Axios Auto-Instrument
+// Uses interceptors to trace all Axios requests
+// ─────────────────────────────────────────────────────────────
+
+import { RequestTracer } from '../core/TraceEngine';
+import { TraceStep, StepStatus, DebuggerConfig, DEFAULT_CONFIG, ServiceTag } from '../core/types';
+import { classifyQuery } from '../core/Classifier';
+
+type AnyAxios = any;
+
+interface AxiosTracerOptions {
+    config?: Partial<DebuggerConfig>;
+    getTracer?: () => RequestTracer | null;
+    /** Map URL patterns to service tags */
+    serviceMap?: Record<string, ServiceTag>;
+}
+
+const DEFAULT_SERVICE_MAP: Record<string, ServiceTag> = {
+    'stripe.com': 'stripe',
+    'api.stripe.com': 'stripe',
+    'razorpay.com': 'razorpay',
+    'api.razorpay.com': 'razorpay',
+    'sendgrid.com': 'sendgrid',
+    'api.sendgrid.com': 'sendgrid',
+    'twilio.com': 'twilio',
+    'api.twilio.com': 'twilio',
+};
+
+/**
+ * Auto-instrument Axios instance to trace all HTTP requests.
+ *
+ * Usage:
+ *   axiosTracer(axios, { getTracer: () => currentTracer })
+ *
+ * Output:
+ *   Axios POST https://api.stripe.com/v1/charges → 234ms ✔ [stripe]
+ *   Axios GET https://api.razorpay.com/orders → 502 error ❌ [razorpay]
+ */
+export function axiosTracer(axiosInstance: AnyAxios, options?: AxiosTracerOptions): void {
+    try {
+        if (axiosInstance.__flowDebuggerPatched) return;
+        axiosInstance.__flowDebuggerPatched = true;
+
+        const config = { ...DEFAULT_CONFIG, ...options?.config };
+        const serviceMap = { ...DEFAULT_SERVICE_MAP, ...options?.serviceMap };
+
+        // Request interceptor — attach start time
+        axiosInstance.interceptors.request.use(
+            (reqConfig: any) => {
+                reqConfig.__flowDebuggerStartTime = performance.now();
+                return reqConfig;
+            },
+            (error: any) => Promise.reject(error),
+        );
+
+        // Response interceptor — record success
+        axiosInstance.interceptors.response.use(
+            (response: any) => {
+                const tracer = options?.getTracer?.();
+                if (!tracer) return response;
+
+                const reqConfig = response.config;
+                const startTime = reqConfig.__flowDebuggerStartTime || performance.now();
+                const endTime = performance.now();
+                const duration = endTime - startTime;
+
+                const url = reqConfig.url || 'unknown';
+                const method = (reqConfig.method || 'GET').toUpperCase();
+                const service = getServiceFromUrl(url, serviceMap);
+                const stepName = `Axios ${method} ${getDomain(url)}`;
+
+                const classification = classifyQuery(duration, 'success', config);
+
+                tracer.addStep({
+                    name: stepName,
+                    service,
+                    status: 'success',
+                    classification,
+                    startTime,
+                    endTime,
+                    duration,
+                    metadata: { url, method, statusCode: response.status },
+                });
+
+                return response;
+            },
+            (error: any) => {
+                const tracer = options?.getTracer?.();
+                if (!tracer) return Promise.reject(error);
+
+                const reqConfig = error.config || {};
+                const startTime = reqConfig.__flowDebuggerStartTime || performance.now();
+                const endTime = performance.now();
+                const duration = endTime - startTime;
+
+                const url = reqConfig.url || 'unknown';
+                const method = (reqConfig.method || 'GET').toUpperCase();
+                const service = getServiceFromUrl(url, serviceMap);
+                const stepName = `Axios ${method} ${getDomain(url)}`;
+
+                let status: StepStatus = 'error';
+                let errorMsg = error.message || 'Request failed';
+
+                // Detect timeouts
+                if (error.code === 'ECONNABORTED' || error.code === 'ETIMEDOUT' || errorMsg.includes('timeout')) {
+                    status = 'timeout';
+                }
+
+                // HTTP error status
+                if (error.response) {
+                    errorMsg = `HTTP ${error.response.status} ${error.response.statusText || ''}`;
+                }
+
+                const classification = classifyQuery(duration, status, config);
+
+                tracer.addStep({
+                    name: stepName,
+                    service,
+                    status,
+                    classification,
+                    startTime,
+                    endTime,
+                    duration,
+                    error: errorMsg,
+                    stackTrace: error.stack,
+                    metadata: { url, method, statusCode: error.response?.status },
+                });
+
+                return Promise.reject(error);
+            },
+        );
+    } catch (_) {
+        // Production-safe: never crash
+    }
+}
+
+/** Extract service tag from URL */
+function getServiceFromUrl(url: string, serviceMap: Record<string, ServiceTag>): ServiceTag {
+    try {
+        const urlObj = new URL(url);
+        const hostname = urlObj.hostname;
+
+        if (serviceMap[hostname]) return serviceMap[hostname];
+
+        for (const [pattern, service] of Object.entries(serviceMap)) {
+            if (hostname.includes(pattern)) return service;
+        }
+
+        return 'axios';
+    } catch {
+        return 'axios';
+    }
+}
+
+/** Extract domain from URL for display */
+function getDomain(url: string): string {
+    try {
+        const urlObj = new URL(url);
+        return urlObj.hostname + urlObj.pathname.substring(0, 30);
+    } catch {
+        return url.substring(0, 50);
+    }
+}