@runtime-digital-twin/sdk 1.0.0

package/dist/replay-logger.js

@@ -0,0 +1,434 @@
+"use strict";
+/**
+ * Structured Replay Logger
+ *
+ * Provides structured logging for replay execution with stable keys.
+ * Supports JSON and human-readable output modes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReplayLogger = void 0;
+exports.getReplayLogger = getReplayLogger;
+exports.resetReplayLogger = resetReplayLogger;
+exports.createReplayLogger = createReplayLogger;
+// ============================================================================
+// Logger Implementation
+// ============================================================================
+const LOG_LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+const LEVEL_COLORS = {
+    debug: "\x1b[90m", // gray
+    info: "\x1b[36m", // cyan
+    warn: "\x1b[33m", // yellow
+    error: "\x1b[31m", // red
+};
+const CATEGORY_ICONS = {
+    http: "🌐",
+    db: "💾",
+    trace: "📦",
+    lifecycle: "⚙️",
+    system: "🔧",
+};
+const RESET = "\x1b[0m";
+/**
+ * Replay Logger instance
+ */
+class ReplayLogger {
+    config;
+    events = [];
+    startTime = Date.now();
+    constructor(config = {}) {
+        this.config = {
+            format: config.format ?? "human",
+            minLevel: config.minLevel ?? "info",
+            output: config.output ?? {
+                write: (msg) => process.stderr.write(msg + "\n"),
+            },
+            timestamps: config.timestamps ?? true,
+            includeTrace: config.includeTrace ?? false,
+            colors: config.colors ?? process.stdout.isTTY,
+        };
+    }
+    /**
+     * Get all logged events
+     */
+    getEvents() {
+        return [...this.events];
+    }
+    /**
+     * Clear all logged events
+     */
+    clear() {
+        this.events = [];
+        this.startTime = Date.now();
+    }
+    /**
+     * Check if a log level should be emitted
+     */
+    shouldLog(level) {
+        return LOG_LEVELS[level] >= LOG_LEVELS[this.config.minLevel];
+    }
+    /**
+     * Log an event
+     */
+    log(event) {
+        const fullEvent = {
+            ...event,
+            timestamp: Date.now(),
+        };
+        this.events.push(fullEvent);
+        if (!this.shouldLog(event.level)) {
+            return;
+        }
+        const output = this.config.format === "json"
+            ? this.formatJson(fullEvent)
+            : this.formatHuman(fullEvent);
+        this.config.output.write(output);
+    }
+    /**
+     * Format event as JSON
+     */
+    formatJson(event) {
+        return JSON.stringify(event);
+    }
+    /**
+     * Format event as human-readable
+     */
+    formatHuman(event) {
+        const parts = [];
+        // Timestamp
+        if (this.config.timestamps) {
+            const elapsed = event.timestamp - this.startTime;
+            parts.push(`[+${elapsed.toString().padStart(6)}ms]`);
+        }
+        // Category icon
+        parts.push(CATEGORY_ICONS[event.category] || "•");
+        // Level with color
+        const levelStr = event.level.toUpperCase().padEnd(5);
+        if (this.config.colors) {
+            parts.push(`${LEVEL_COLORS[event.level]}${levelStr}${RESET}`);
+        }
+        else {
+            parts.push(levelStr);
+        }
+        // Event type
+        parts.push(`[${event.event}]`);
+        // Event-specific message
+        parts.push(this.formatEventMessage(event));
+        // Trace context
+        if (this.config.includeTrace && event.trace) {
+            parts.push(`(trace:${event.trace.traceId.substring(0, 16)}...)`);
+        }
+        return parts.join(" ");
+    }
+    /**
+     * Format event-specific message
+     */
+    formatEventMessage(event) {
+        switch (event.event) {
+            // HTTP events
+            case "http.outbound.match":
+                return `#${event.data.callIndex} ${event.data.method} ${event.data.normalizedUrl} → matched span:${event.data.matchedSpanId}`;
+            case "http.outbound.return":
+                return `#${event.data.callIndex} ${event.data.method} ${event.data.url} → ${event.data.statusCode}`;
+            case "http.outbound.mismatch":
+                return `#${event.data.callIndex} expected ${event.data.expected.method} ${event.data.expected.url} got ${event.data.actual.method} ${event.data.actual.url}`;
+            case "http.outbound.unexpected":
+                return `#${event.data.callIndex} unexpected call ${event.data.method} ${event.data.url} (only ${event.data.expectedCallCount} recorded)`;
+            case "http.outbound.missing":
+                return `#${event.data.callIndex} missing call ${event.data.method} ${event.data.url} (span:${event.data.spanId})`;
+            case "http.outbound.blocked":
+                return `BLOCKED ${event.data.method} ${event.data.url}: ${event.data.reason}`;
+            // DB events
+            case "db.query.match":
+                return `#${event.data.queryIndex} ${event.data.operation} → matched span:${event.data.matchedSpanId} (${event.data.rowCount} rows)`;
+            case "db.query.return":
+                return `#${event.data.queryIndex} ${event.data.operation} → ${event.data.rowCount} rows`;
+            case "db.query.mismatch":
+                return `#${event.data.queryIndex} expected ${event.data.expected.operation}: "${event.data.expected.sql.substring(0, 40)}..." got "${event.data.actual.sql.substring(0, 40)}..."`;
+            case "db.query.unexpected":
+                return `#${event.data.queryIndex} unexpected query ${event.data.operation}: "${event.data.sql.substring(0, 50)}..." (only ${event.data.expectedQueryCount} recorded)`;
+            case "db.query.missing":
+                return `#${event.data.queryIndex} missing query ${event.data.operation}: "${event.data.sql.substring(0, 50)}..." (span:${event.data.spanId})`;
+            case "db.query.blocked":
+                return `BLOCKED ${event.data.operation}: ${event.data.reason}`;
+            // Trace events
+            case "trace.load":
+                return `loaded ${event.data.traceId} from ${event.data.traceDir} (v${event.data.formatVersion}, ${event.data.httpCallCount || 0} HTTP, ${event.data.dbQueryCount || 0} DB)`;
+            case "trace.load.warning":
+                return `${event.data.warning}`;
+            case "trace.load.error":
+                return `${event.data.errorType}: ${event.data.message}`;
+            // Lifecycle events
+            case "replay.start":
+                return `starting replay of ${event.data.traceId} in ${event.data.mode} mode`;
+            case "replay.complete":
+                const status = event.data.success ? "✓ SUCCESS" : "✗ FAILED";
+                return `${status} in ${event.data.durationMs}ms (HTTP: ${event.data.httpCallsMatched}/${event.data.httpCallsTotal}, DB: ${event.data.dbQueriesMatched}/${event.data.dbQueriesTotal}, ${event.data.divergenceCount} divergences, ${event.data.errorCount} errors)`;
+            case "replay.error":
+                return `${event.data.errorType}: ${event.data.message}${event.data.location ? ` at ${event.data.location}` : ""}`;
+            case "replay.divergence":
+                return `[${event.data.source}] ${event.data.message} (${event.data.recoverable ? "recoverable" : "fatal"})`;
+            default:
+                return JSON.stringify(event.data || {});
+        }
+    }
+    // ============================================================================
+    // Convenience Methods
+    // ============================================================================
+    /**
+     * Log HTTP outbound match
+     */
+    httpMatch(data, trace) {
+        this.log({
+            event: "http.outbound.match",
+            category: "http",
+            level: "info",
+            data,
+            trace,
+        });
+    }
+    /**
+     * Log HTTP outbound return
+     */
+    httpReturn(data, trace) {
+        this.log({
+            event: "http.outbound.return",
+            category: "http",
+            level: "debug",
+            data,
+            trace,
+        });
+    }
+    /**
+     * Log HTTP outbound mismatch
+     */
+    httpMismatch(data, trace) {
+        this.log({
+            event: "http.outbound.mismatch",
+            category: "http",
+            level: "error",
+            data,
+            trace,
+        });
+    }
+    /**
+     * Log HTTP outbound unexpected
+     */
+    httpUnexpected(data, trace) {
+        this.log({
+            event: "http.outbound.unexpected",
+            category: "http",
+            level: "error",
+            data,
+            trace,
+        });
+    }
+    /**
+     * Log HTTP outbound missing
+     */
+    httpMissing(data, trace) {
+        this.log({
+            event: "http.outbound.missing",
+            category: "http",
+            level: "error",
+            data,
+            trace,
+        });
+    }
+    /**
+     * Log HTTP outbound blocked
+     */
+    httpBlocked(data, trace) {
+        this.log({
+            event: "http.outbound.blocked",
+            category: "http",
+            level: "error",
+            data,
+            trace,
+        });
+    }
+    /**
+     * Log DB query match
+     */
+    dbMatch(data, trace) {
+        this.log({
+            event: "db.query.match",
+            category: "db",
+            level: "info",
+            data,
+            trace,
+        });
+    }
+    /**
+     * Log DB query return
+     */
+    dbReturn(data, trace) {
+        this.log({
+            event: "db.query.return",
+            category: "db",
+            level: "debug",
+            data,
+            trace,
+        });
+    }
+    /**
+     * Log DB query mismatch
+     */
+    dbMismatch(data, trace) {
+        this.log({
+            event: "db.query.mismatch",
+            category: "db",
+            level: "error",
+            data,
+            trace,
+        });
+    }
+    /**
+     * Log DB query unexpected
+     */
+    dbUnexpected(data, trace) {
+        this.log({
+            event: "db.query.unexpected",
+            category: "db",
+            level: "error",
+            data,
+            trace,
+        });
+    }
+    /**
+     * Log DB query missing
+     */
+    dbMissing(data, trace) {
+        this.log({
+            event: "db.query.missing",
+            category: "db",
+            level: "error",
+            data,
+            trace,
+        });
+    }
+    /**
+     * Log DB query blocked
+     */
+    dbBlocked(data, trace) {
+        this.log({
+            event: "db.query.blocked",
+            category: "db",
+            level: "error",
+            data,
+            trace,
+        });
+    }
+    /**
+     * Log trace load
+     */
+    traceLoad(data) {
+        this.log({
+            event: "trace.load",
+            category: "trace",
+            level: "info",
+            data,
+            trace: { traceId: data.traceId },
+        });
+    }
+    /**
+     * Log trace load warning
+     */
+    traceLoadWarning(data) {
+        this.log({
+            event: "trace.load.warning",
+            category: "trace",
+            level: "warn",
+            data,
+        });
+    }
+    /**
+     * Log trace load error
+     */
+    traceLoadError(data) {
+        this.log({
+            event: "trace.load.error",
+            category: "trace",
+            level: "error",
+            data,
+        });
+    }
+    /**
+     * Log replay start
+     */
+    replayStart(data) {
+        this.log({
+            event: "replay.start",
+            category: "lifecycle",
+            level: "info",
+            data,
+            trace: { traceId: data.traceId },
+        });
+    }
+    /**
+     * Log replay complete
+     */
+    replayComplete(data) {
+        this.log({
+            event: "replay.complete",
+            category: "lifecycle",
+            level: "info",
+            data,
+            trace: { traceId: data.traceId },
+        });
+    }
+    /**
+     * Log replay error
+     */
+    replayError(data) {
+        this.log({
+            event: "replay.error",
+            category: "lifecycle",
+            level: "error",
+            data,
+            trace: { traceId: data.traceId },
+        });
+    }
+    /**
+     * Log replay divergence
+     */
+    replayDivergence(data, trace) {
+        this.log({
+            event: "replay.divergence",
+            category: "lifecycle",
+            level: "warn",
+            data,
+            trace,
+        });
+    }
+}
+exports.ReplayLogger = ReplayLogger;
+// ============================================================================
+// Global Logger Instance
+// ============================================================================
+let globalLogger = null;
+/**
+ * Get or create the global replay logger
+ */
+function getReplayLogger(config) {
+    if (!globalLogger || config) {
+        globalLogger = new ReplayLogger(config);
+    }
+    return globalLogger;
+}
+/**
+ * Reset the global replay logger
+ */
+function resetReplayLogger() {
+    globalLogger = null;
+}
+/**
+ * Create a new replay logger instance
+ */
+function createReplayLogger(config) {
+    return new ReplayLogger(config);
+}

package/dist/root-cause-analyzer.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Multi-service root cause analyzer
+ *
+ * Analyzes distributed traces to determine which upstream service
+ * most likely caused a failure.
+ */
+import { type TraceEvent } from './multi-service-edge-builder';
+export interface RootCauseAnalysis {
+    culprit: {
+        serviceName: string;
+        spanId: string;
+        operationName: string;
+        evidence: {
+            kind: 'http' | 'error';
+            statusCode?: number;
+            peerService?: string;
+            message?: string;
+            invariants?: Array<{
+                name: string;
+                paths?: string[];
+            }>;
+            responseShapeDigest?: {
+                hash?: string;
+                nullPaths?: string[];
+            };
+        };
+        confidence: number;
+    };
+    propagationPath: string[];
+    rankedFindings: Array<{
+        score: number;
+        reason: string;
+        serviceName: string;
+        spanId: string;
+    }>;
+}
+/**
+ * Analyze multi-service root cause
+ *
+ * @param traceId - The trace ID
+ * @param events - All events for this traceId
+ * @returns Root cause analysis result
+ */
+export declare function analyzeMultiServiceRootCause(traceId: string, events: TraceEvent[]): RootCauseAnalysis;
+//# sourceMappingURL=root-cause-analyzer.d.ts.map

package/dist/root-cause-analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-cause-analyzer.d.ts","sourceRoot":"","sources":["../src/root-cause-analyzer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAc,KAAK,UAAU,EAAoB,MAAM,8BAA8B,CAAC;AAE7F,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE;QACP,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,EAAE,MAAM,CAAC;QACtB,QAAQ,EAAE;YACR,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;YACvB,UAAU,CAAC,EAAE,MAAM,CAAC;YACpB,WAAW,CAAC,EAAE,MAAM,CAAC;YACrB,OAAO,CAAC,EAAE,MAAM,CAAC;YAEjB,UAAU,CAAC,EAAE,KAAK,CAAC;gBACjB,IAAI,EAAE,MAAM,CAAC;gBACb,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;aAClB,CAAC,CAAC;YACH,mBAAmB,CAAC,EAAE;gBACpB,IAAI,CAAC,EAAE,MAAM,CAAC;gBACd,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;aACtB,CAAC;SACH,CAAC;QACF,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,EAAE,KAAK,CAAC;QACpB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC,CAAC;CACJ;AAwcD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,UAAU,EAAE,GACnB,iBAAiB,CAoSnB"}