trickle-observe 0.2.114 → 0.2.116

package/dist/call-trace.js

@@ -51,7 +51,7 @@ let traceFile = null;
 let callCounter = 0;
 let currentCallId = 0; // 0 = top level
 const callStack = [0];
-const MAX_TRACE_EVENTS = 500;
+const MAX_TRACE_EVENTS = 1000;
 let eventCount = 0;
 function getTraceFile() {
     if (traceFile)
@@ -62,12 +62,17 @@ function getTraceFile() {
     }
     catch { }
     traceFile = path.join(dir, 'calltrace.jsonl');
+    // Only create the file if it doesn't already exist — another module instance
+    // (e.g. the observe hook) may have already initialised it.
     try {
-        fs.writeFileSync(traceFile, '');
+        fs.writeFileSync(traceFile, '', { flag: 'wx' });
+    }
+    catch {
+        // File already exists — that's fine
     }
-    catch { }
     return traceFile;
 }
+let _initialized = false;
 function writeEvent(event) {
     if (eventCount >= MAX_TRACE_EVENTS)
         return;
@@ -93,6 +98,13 @@ function traceCall(functionName, moduleName) {
 function traceReturn(callId, functionName, moduleName, durationMs, error) {
     const parentId = callStack.length >= 2 ? callStack[callStack.length - 2] : 0;
     const depth = callStack.length - 1;
+    // Get request ID from async context (if inside an Express request)
+    let requestId;
+    try {
+        const { getRequestId } = require('./request-context');
+        requestId = getRequestId();
+    }
+    catch { }
     writeEvent({
         kind: 'call',
         function: functionName,
@@ -103,6 +115,7 @@ function traceReturn(callId, functionName, moduleName, durationMs, error) {
         timestamp: Date.now(),
         durationMs: Math.round(durationMs * 100) / 100,
         ...(error ? { error } : {}),
+        ...(requestId ? { requestId } : {}),
     });
     // Pop from stack
     if (callStack[callStack.length - 1] === callId) {
@@ -110,6 +123,18 @@ function traceReturn(callId, functionName, moduleName, durationMs, error) {
     }
 }
 function initCallTrace() {
-    // Ensure trace file is initialized
-    getTraceFile();
+    if (_initialized)
+        return;
+    _initialized = true;
+    // Truncate the file on explicit init (only the observe hook calls this)
+    const dir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch { }
+    traceFile = path.join(dir, 'calltrace.jsonl');
+    try {
+        fs.writeFileSync(traceFile, '');
+    }
+    catch { }
 }

package/dist/db-observer.js

@@ -80,6 +80,14 @@ function writeQuery(record) {
     if (queryCount >= MAX_QUERIES)
         return;
     queryCount++;
+    // Add request ID from async context
+    try {
+        const { getRequestId } = require('./request-context');
+        const reqId = getRequestId();
+        if (reqId)
+            record.requestId = reqId;
+    }
+    catch { }
     try {
         fs.appendFileSync(getQueriesFile(), JSON.stringify(record) + '\n');
     }

package/dist/express.js

@@ -1,12 +1,49 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.instrumentExpress = instrumentExpress;
 exports.trickleMiddleware = trickleMiddleware;
+const fs = __importStar(require("fs"));
+const pathMod = __importStar(require("path"));
 const type_inference_1 = require("./type-inference");
 const type_hash_1 = require("./type-hash");
 const cache_1 = require("./cache");
 const transport_1 = require("./transport");
 const env_detect_1 = require("./env-detect");
+const request_context_1 = require("./request-context");
+const call_trace_1 = require("./call-trace");
 const expressCache = new cache_1.TypeCache();
 /**
  * Extract the interesting parts of an Express request as a plain object
@@ -91,10 +128,55 @@ function sanitizeSample(value, depth = 3) {
     }
     return String(value);
 }
+/**
+ * Write an error record to .trickle/errors.jsonl so that `trickle monitor`
+ * and `trickle heal` can detect runtime errors from Express handlers.
+ */
+function writeErrorToFile(error, input, routeName) {
+    try {
+        const err = error instanceof Error ? error : new Error(String(error));
+        const isLambda = !!process.env.AWS_LAMBDA_FUNCTION_NAME;
+        const defaultDir = isLambda ? '/tmp/.trickle' : pathMod.join(process.cwd(), '.trickle');
+        const dir = process.env.TRICKLE_LOCAL_DIR || defaultDir;
+        try {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        catch { }
+        // Extract file and line from stack trace
+        const stackLines = (err.stack || '').split('\n');
+        let errorFile;
+        let errorLine;
+        for (const sl of stackLines.slice(1)) {
+            const m = sl.match(/\((.+):(\d+):\d+\)/) || sl.match(/at (.+):(\d+):\d+/);
+            if (m && !m[1].includes('node_modules') && !m[1].includes('node:') && !m[1].includes('trickle')) {
+                errorFile = m[1];
+                errorLine = parseInt(m[2]);
+                break;
+            }
+        }
+        const record = {
+            kind: 'error',
+            error: err.message,
+            type: err.constructor?.name || 'Error',
+            message: err.message,
+            file: errorFile,
+            line: errorLine,
+            stack: stackLines.slice(0, 6).join('\n'),
+            route: routeName,
+            request: input,
+            timestamp: new Date().toISOString(),
+        };
+        const errorsFile = pathMod.join(dir, 'errors.jsonl');
+        fs.appendFileSync(errorsFile, JSON.stringify(record) + '\n');
+    }
+    catch {
+        // Never crash the user's app
+    }
+}
 /**
  * Emit a type payload for a single Express route invocation.
  */
-function emitExpressPayload(functionName, environment, maxDepth, input, output, error) {
+function emitExpressPayload(functionName, environment, maxDepth, input, output, error, durationMs) {
     try {
         const functionKey = `express::${functionName}`;
         const argsType = (0, type_inference_1.inferType)(input, maxDepth);
@@ -118,6 +200,9 @@ function emitExpressPayload(functionName, environment, maxDepth, input, output,
             sampleInput: sanitizeSample(input),
             sampleOutput: error ? undefined : sanitizeSample(output),
         };
+        if (durationMs !== undefined) {
+            payload.durationMs = Math.round(durationMs * 100) / 100;
+        }
         if (error) {
             const err = error instanceof Error ? error : new Error(String(error));
             payload.error = {
@@ -126,6 +211,8 @@ function emitExpressPayload(functionName, environment, maxDepth, input, output,
                 stackTrace: err.stack,
                 argsSnapshot: sanitizeSample(input),
             };
+            // Also write to errors.jsonl for monitor/heal detection
+            writeErrorToFile(error, input, functionName);
         }
         (0, transport_1.enqueue)(payload);
     }
@@ -143,15 +230,28 @@ function wrapExpressHandler(handler, routeName, opts) {
         if (opts.sampleRate < 1 && Math.random() > opts.sampleRate) {
             return handler.call(this, req, res, next);
         }
+        const self = this;
+        // Wrap entire handler execution in request context so downstream calls get a request ID
+        let returnValue;
+        (0, request_context_1.withRequestContext)(req, () => {
+            returnValue = _executeHandler(self, handler, req, res, next, routeName, opts);
+        });
+        return returnValue;
+    };
+    function _executeHandler(self, handler, req, res, next, routeName, opts) {
         const input = extractRequestInput(req);
         let captured = false;
+        const startTime = performance.now();
+        const callId = (0, call_trace_1.traceCall)(routeName, 'express');
         // Intercept res.json()
         const originalJson = res.json;
         if (typeof originalJson === 'function') {
             res.json = function (data) {
                 if (!captured) {
                     captured = true;
-                    emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, data);
+                    const durationMs = performance.now() - startTime;
+                    (0, call_trace_1.traceReturn)(callId, routeName, 'express', durationMs);
+                    emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, data, undefined, durationMs);
                 }
                 res.json = originalJson; // restore
                 return originalJson.call(res, data);
@@ -163,9 +263,11 @@ function wrapExpressHandler(handler, routeName, opts) {
             res.send = function (data) {
                 if (!captured) {
                     captured = true;
+                    const durationMs = performance.now() - startTime;
+                    (0, call_trace_1.traceReturn)(callId, routeName, 'express', durationMs);
                     // Only capture non-string data as typed output; strings are usually HTML
                     const output = typeof data === 'string' ? { __html: true } : data;
-                    emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, output);
+                    emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, output, undefined, durationMs);
                 }
                 res.send = originalSend; // restore
                 return originalSend.call(res, data);
@@ -175,20 +277,24 @@ function wrapExpressHandler(handler, routeName, opts) {
         const wrappedNext = function (err) {
             if (err && !captured) {
                 captured = true;
-                emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, undefined, err);
+                const durationMs = performance.now() - startTime;
+                (0, call_trace_1.traceReturn)(callId, routeName, 'express', durationMs, (err instanceof Error ? err : new Error(String(err))).message);
+                emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, undefined, err, durationMs);
             }
             if (typeof next === 'function') {
                 return next(err);
             }
         };
         try {
-            const result = handler.call(this, req, res, wrappedNext);
+            const result = handler.call(self, req, res, wrappedNext);
             // Handle async handlers that return a promise
             if (result && typeof result === 'object' && typeof result.then === 'function') {
                 return result.catch((err) => {
                     if (!captured) {
                         captured = true;
-                        emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, undefined, err);
+                        const durationMs = performance.now() - startTime;
+                        (0, call_trace_1.traceReturn)(callId, routeName, 'express', durationMs, (err instanceof Error ? err : new Error(String(err))).message);
+                        emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, undefined, err, durationMs);
                     }
                     // Re-throw so Express error handling picks it up
                     throw err;
@@ -199,11 +305,13 @@ function wrapExpressHandler(handler, routeName, opts) {
         catch (err) {
             if (!captured) {
                 captured = true;
-                emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, undefined, err);
+                const durationMs = performance.now() - startTime;
+                (0, call_trace_1.traceReturn)(callId, routeName, 'express', durationMs, (err instanceof Error ? err : new Error(String(err))).message);
+                emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, undefined, err, durationMs);
             }
             throw err;
         }
-    };
+    }
     // Preserve function metadata
     Object.defineProperty(wrapped, 'name', { value: handler.name || routeName, configurable: true });
     Object.defineProperty(wrapped, 'length', { value: handler.length, configurable: true });
@@ -293,63 +401,76 @@ function trickleMiddleware(userOpts) {
             next();
             return;
         }
-        if (debug) {
-            console.log(`[trickle/middleware] Intercepting ${req.method} ${req.originalUrl || req.url}`);
-        }
-        let captured = false;
-        // We derive the route name lazily once the response is being sent,
-        // because req.route is only populated after the handler matches.
-        function getRouteName() {
-            try {
-                if (req.route && req.route.path) {
-                    return `${req.method} ${req.baseUrl || ''}${req.route.path}`;
-                }
-            }
-            catch {
-                // ignore
+        // Wrap in request context for per-request correlation
+        (0, request_context_1.withRequestContext)(req, () => {
+            _handleRequest(req, res, next, opts, debug);
+        });
+    };
+}
+function _handleRequest(req, res, next, opts, debug) {
+    if (debug) {
+        console.log(`[trickle/middleware] Intercepting ${req.method} ${req.originalUrl || req.url}`);
+    }
+    let captured = false;
+    const startTime = performance.now();
+    const prelimRouteName = `${req.method || 'UNKNOWN'} ${req.originalUrl || req.url || '/'}`;
+    const callId = (0, call_trace_1.traceCall)(prelimRouteName, 'express');
+    // We derive the route name lazily once the response is being sent,
+    // because req.route is only populated after the handler matches.
+    function getRouteName() {
+        try {
+            if (req.route && req.route.path) {
+                return `${req.method} ${req.baseUrl || ''}${req.route.path}`;
             }
-            return `${req.method || 'UNKNOWN'} ${req.originalUrl || req.url || '/'}`;
         }
-        const input = extractRequestInput(req);
-        // Intercept res.json()
-        const originalJson = res.json;
-        if (typeof originalJson === 'function') {
-            res.json = function (data) {
-                if (!captured) {
-                    captured = true;
-                    const routeName = getRouteName();
-                    if (debug) {
-                        console.log(`[trickle/middleware] Captured res.json for ${routeName}`);
-                    }
-                    // Re-extract input here because body parsers may have run since middleware was entered
-                    const latestInput = extractRequestInput(req);
-                    emitExpressPayload(routeName, opts.environment, opts.maxDepth, latestInput, data);
-                }
-                res.json = originalJson;
-                return originalJson.call(res, data);
-            };
-        }
-        else if (debug) {
-            console.log(`[trickle/middleware] res.json is not a function: ${typeof originalJson}`);
+        catch {
+            // ignore
         }
-        // Intercept res.send()
-        const originalSend = res.send;
-        if (typeof originalSend === 'function') {
-            res.send = function (data) {
-                if (!captured) {
-                    captured = true;
-                    const routeName = getRouteName();
-                    if (debug) {
-                        console.log(`[trickle/middleware] Captured res.send for ${routeName}`);
-                    }
-                    const latestInput = extractRequestInput(req);
-                    const output = typeof data === 'string' ? { __html: true } : data;
-                    emitExpressPayload(routeName, opts.environment, opts.maxDepth, latestInput, output);
+        return prelimRouteName;
+    }
+    const input = extractRequestInput(req);
+    // Intercept res.json()
+    const originalJson = res.json;
+    if (typeof originalJson === 'function') {
+        res.json = function (data) {
+            if (!captured) {
+                captured = true;
+                const routeName = getRouteName();
+                const durationMs = performance.now() - startTime;
+                (0, call_trace_1.traceReturn)(callId, routeName, 'express', durationMs);
+                if (debug) {
+                    console.log(`[trickle/middleware] Captured res.json for ${routeName}`);
                 }
-                res.send = originalSend;
-                return originalSend.call(res, data);
-            };
-        }
-        next();
-    };
+                // Re-extract input here because body parsers may have run since middleware was entered
+                const latestInput = extractRequestInput(req);
+                emitExpressPayload(routeName, opts.environment, opts.maxDepth, latestInput, data, undefined, durationMs);
+            }
+            res.json = originalJson;
+            return originalJson.call(res, data);
+        };
+    }
+    else if (debug) {
+        console.log(`[trickle/middleware] res.json is not a function: ${typeof originalJson}`);
+    }
+    // Intercept res.send()
+    const originalSend = res.send;
+    if (typeof originalSend === 'function') {
+        res.send = function (data) {
+            if (!captured) {
+                captured = true;
+                const routeName = getRouteName();
+                const durationMs = performance.now() - startTime;
+                (0, call_trace_1.traceReturn)(callId, routeName, 'express', durationMs);
+                if (debug) {
+                    console.log(`[trickle/middleware] Captured res.send for ${routeName}`);
+                }
+                const latestInput = extractRequestInput(req);
+                const output = typeof data === 'string' ? { __html: true } : data;
+                emitExpressPayload(routeName, opts.environment, opts.maxDepth, latestInput, output, undefined, durationMs);
+            }
+            res.send = originalSend;
+            return originalSend.call(res, data);
+        };
+    }
+    next();
 }

package/dist/request-context.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Request context — propagates a request ID through async call chains.
+ *
+ * Uses Node.js AsyncLocalStorage so that all functions, queries, and logs
+ * within a single HTTP request share the same requestId, enabling
+ * per-request tracing (like Jaeger but with trickle's richer data).
+ *
+ * Usage:
+ *   import { withRequestContext, getRequestId } from './request-context';
+ *   // In Express middleware:
+ *   app.use((req, res, next) => withRequestContext(req, next));
+ *   // Anywhere in the call chain:
+ *   const id = getRequestId(); // returns the current request's ID
+ */
+export interface RequestContext {
+    requestId: string;
+    method?: string;
+    path?: string;
+    startTime: number;
+}
+/**
+ * Run a callback within a request context.
+ */
+export declare function withRequestContext(req: any, callback: () => void): void;
+/**
+ * Get the current request ID (if inside a request context).
+ */
+export declare function getRequestId(): string | undefined;
+/**
+ * Get the full request context.
+ */
+export declare function getRequestContext(): RequestContext | undefined;

package/dist/request-context.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * Request context — propagates a request ID through async call chains.
+ *
+ * Uses Node.js AsyncLocalStorage so that all functions, queries, and logs
+ * within a single HTTP request share the same requestId, enabling
+ * per-request tracing (like Jaeger but with trickle's richer data).
+ *
+ * Usage:
+ *   import { withRequestContext, getRequestId } from './request-context';
+ *   // In Express middleware:
+ *   app.use((req, res, next) => withRequestContext(req, next));
+ *   // Anywhere in the call chain:
+ *   const id = getRequestId(); // returns the current request's ID
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRequestContext = withRequestContext;
+exports.getRequestId = getRequestId;
+exports.getRequestContext = getRequestContext;
+let als = null;
+let counter = 0;
+try {
+    const { AsyncLocalStorage } = require('async_hooks');
+    als = new AsyncLocalStorage();
+}
+catch {
+    // AsyncLocalStorage not available (older Node versions)
+}
+/**
+ * Run a callback within a request context.
+ */
+function withRequestContext(req, callback) {
+    if (!als) {
+        callback();
+        return;
+    }
+    const ctx = {
+        requestId: `req-${++counter}-${Date.now().toString(36)}`,
+        method: req?.method,
+        path: req?.path || req?.url,
+        startTime: Date.now(),
+    };
+    als.run(ctx, callback);
+}
+/**
+ * Get the current request ID (if inside a request context).
+ */
+function getRequestId() {
+    if (!als)
+        return undefined;
+    const ctx = als.getStore();
+    return ctx?.requestId;
+}
+/**
+ * Get the full request context.
+ */
+function getRequestContext() {
+    if (!als)
+        return undefined;
+    return als.getStore();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trickle-observe",
-  "version": "0.2.114",
+  "version": "0.2.116",
   "description": "Runtime type observability for JavaScript applications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/call-trace.ts

@@ -21,13 +21,14 @@ interface CallEvent {
   timestamp: number;
   durationMs: number;
   error?: string;
+  requestId?: string;
 }
 
 let traceFile: string | null = null;
 let callCounter = 0;
 let currentCallId = 0; // 0 = top level
 const callStack: number[] = [0];
-const MAX_TRACE_EVENTS = 500;
+const MAX_TRACE_EVENTS = 1000;
 let eventCount = 0;
 
 function getTraceFile(): string {
@@ -35,10 +36,18 @@ function getTraceFile(): string {
   const dir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
   try { fs.mkdirSync(dir, { recursive: true }); } catch {}
   traceFile = path.join(dir, 'calltrace.jsonl');
-  try { fs.writeFileSync(traceFile, ''); } catch {}
+  // Only create the file if it doesn't already exist — another module instance
+  // (e.g. the observe hook) may have already initialised it.
+  try {
+    fs.writeFileSync(traceFile, '', { flag: 'wx' });
+  } catch {
+    // File already exists — that's fine
+  }
   return traceFile;
 }
 
+let _initialized = false;
+
 function writeEvent(event: CallEvent): void {
   if (eventCount >= MAX_TRACE_EVENTS) return;
   eventCount++;
@@ -71,6 +80,13 @@ export function traceReturn(
   const parentId = callStack.length >= 2 ? callStack[callStack.length - 2] : 0;
   const depth = callStack.length - 1;
 
+  // Get request ID from async context (if inside an Express request)
+  let requestId: string | undefined;
+  try {
+    const { getRequestId } = require('./request-context');
+    requestId = getRequestId();
+  } catch {}
+
   writeEvent({
     kind: 'call',
     function: functionName,
@@ -81,6 +97,7 @@ export function traceReturn(
     timestamp: Date.now(),
     durationMs: Math.round(durationMs * 100) / 100,
     ...(error ? { error } : {}),
+    ...(requestId ? { requestId } : {}),
   });
 
   // Pop from stack
@@ -90,6 +107,11 @@ export function traceReturn(
 }
 
 export function initCallTrace(): void {
-  // Ensure trace file is initialized
-  getTraceFile();
+  if (_initialized) return;
+  _initialized = true;
+  // Truncate the file on explicit init (only the observe hook calls this)
+  const dir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+  traceFile = path.join(dir, 'calltrace.jsonl');
+  try { fs.writeFileSync(traceFile, ''); } catch {}
 }

package/src/db-observer.ts

@@ -21,6 +21,7 @@ interface QueryRecord {
   columns?: string[];
   error?: string;
   timestamp: number;
+  requestId?: string;
 }
 
 let queriesFile: string | null = null;
@@ -42,6 +43,12 @@ function getQueriesFile(): string {
 function writeQuery(record: QueryRecord): void {
   if (queryCount >= MAX_QUERIES) return;
   queryCount++;
+  // Add request ID from async context
+  try {
+    const { getRequestId } = require('./request-context');
+    const reqId = getRequestId();
+    if (reqId) record.requestId = reqId;
+  } catch {}
   try {
     fs.appendFileSync(getQueriesFile(), JSON.stringify(record) + '\n');
   } catch {}

package/src/express.ts

@@ -1,9 +1,13 @@
+import * as fs from 'fs';
+import * as pathMod from 'path';
 import { TypeNode, IngestPayload, WrapOptions } from './types';
 import { inferType } from './type-inference';
 import { hashType } from './type-hash';
 import { TypeCache } from './cache';
 import { enqueue } from './transport';
 import { detectEnvironment } from './env-detect';
+import { withRequestContext } from './request-context';
+import { traceCall, traceReturn } from './call-trace';
 
 const expressCache = new TypeCache();
 
@@ -94,6 +98,51 @@ function sanitizeSample(value: unknown, depth: number = 3): unknown {
   return String(value);
 }
 
+/**
+ * Write an error record to .trickle/errors.jsonl so that `trickle monitor`
+ * and `trickle heal` can detect runtime errors from Express handlers.
+ */
+function writeErrorToFile(error: unknown, input: Record<string, unknown>, routeName: string): void {
+  try {
+    const err = error instanceof Error ? error : new Error(String(error));
+    const isLambda = !!process.env.AWS_LAMBDA_FUNCTION_NAME;
+    const defaultDir = isLambda ? '/tmp/.trickle' : pathMod.join(process.cwd(), '.trickle');
+    const dir = process.env.TRICKLE_LOCAL_DIR || defaultDir;
+    try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+
+    // Extract file and line from stack trace
+    const stackLines = (err.stack || '').split('\n');
+    let errorFile: string | undefined;
+    let errorLine: number | undefined;
+    for (const sl of stackLines.slice(1)) {
+      const m = sl.match(/\((.+):(\d+):\d+\)/) || sl.match(/at (.+):(\d+):\d+/);
+      if (m && !m[1].includes('node_modules') && !m[1].includes('node:') && !m[1].includes('trickle')) {
+        errorFile = m[1];
+        errorLine = parseInt(m[2]);
+        break;
+      }
+    }
+
+    const record = {
+      kind: 'error',
+      error: err.message,
+      type: err.constructor?.name || 'Error',
+      message: err.message,
+      file: errorFile,
+      line: errorLine,
+      stack: stackLines.slice(0, 6).join('\n'),
+      route: routeName,
+      request: input,
+      timestamp: new Date().toISOString(),
+    };
+
+    const errorsFile = pathMod.join(dir, 'errors.jsonl');
+    fs.appendFileSync(errorsFile, JSON.stringify(record) + '\n');
+  } catch {
+    // Never crash the user's app
+  }
+}
+
 /**
  * Emit a type payload for a single Express route invocation.
  */
@@ -104,6 +153,7 @@ function emitExpressPayload(
   input: Record<string, unknown>,
   output: unknown,
   error?: unknown,
+  durationMs?: number,
 ): void {
   try {
     const functionKey = `express::${functionName}`;
@@ -132,6 +182,10 @@ function emitExpressPayload(
       sampleOutput: error ? undefined : sanitizeSample(output),
     };
 
+    if (durationMs !== undefined) {
+      payload.durationMs = Math.round(durationMs * 100) / 100;
+    }
+
     if (error) {
       const err = error instanceof Error ? error : new Error(String(error));
       payload.error = {
@@ -140,6 +194,8 @@ function emitExpressPayload(
         stackTrace: err.stack,
         argsSnapshot: sanitizeSample(input),
       };
+      // Also write to errors.jsonl for monitor/heal detection
+      writeErrorToFile(error, input, functionName);
     }
 
     enqueue(payload);
@@ -163,8 +219,29 @@ function wrapExpressHandler(
       return handler.call(this, req, res, next);
     }
 
+    const self = this;
+
+    // Wrap entire handler execution in request context so downstream calls get a request ID
+    let returnValue: any;
+    withRequestContext(req, () => {
+      returnValue = _executeHandler(self, handler, req, res, next, routeName, opts);
+    });
+    return returnValue;
+  };
+
+  function _executeHandler(
+    self: any,
+    handler: Function,
+    req: any,
+    res: any,
+    next: any,
+    routeName: string,
+    opts: ExpressInstrumentOpts,
+  ): any {
     const input = extractRequestInput(req);
     let captured = false;
+    const startTime = performance.now();
+    const callId = traceCall(routeName, 'express');
 
     // Intercept res.json()
     const originalJson = res.json;
@@ -172,7 +249,9 @@ function wrapExpressHandler(
       res.json = function (data: any) {
         if (!captured) {
           captured = true;
-          emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, data);
+          const durationMs = performance.now() - startTime;
+          traceReturn(callId, routeName, 'express', durationMs);
+          emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, data, undefined, durationMs);
         }
         res.json = originalJson; // restore
         return originalJson.call(res, data);
@@ -185,9 +264,11 @@ function wrapExpressHandler(
       res.send = function (data: any) {
         if (!captured) {
           captured = true;
+          const durationMs = performance.now() - startTime;
+          traceReturn(callId, routeName, 'express', durationMs);
           // Only capture non-string data as typed output; strings are usually HTML
           const output = typeof data === 'string' ? { __html: true } : data;
-          emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, output);
+          emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, output, undefined, durationMs);
         }
         res.send = originalSend; // restore
         return originalSend.call(res, data);
@@ -198,7 +279,9 @@ function wrapExpressHandler(
     const wrappedNext = function (err?: any) {
       if (err && !captured) {
         captured = true;
-        emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, undefined, err);
+        const durationMs = performance.now() - startTime;
+        traceReturn(callId, routeName, 'express', durationMs, (err instanceof Error ? err : new Error(String(err))).message);
+        emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, undefined, err, durationMs);
       }
       if (typeof next === 'function') {
         return next(err);
@@ -206,14 +289,16 @@ function wrapExpressHandler(
     };
 
     try {
-      const result = handler.call(this, req, res, wrappedNext);
+      const result = handler.call(self, req, res, wrappedNext);
 
       // Handle async handlers that return a promise
       if (result && typeof result === 'object' && typeof result.then === 'function') {
         return result.catch((err: unknown) => {
           if (!captured) {
             captured = true;
-            emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, undefined, err);
+            const durationMs = performance.now() - startTime;
+            traceReturn(callId, routeName, 'express', durationMs, (err instanceof Error ? err : new Error(String(err))).message);
+            emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, undefined, err, durationMs);
           }
           // Re-throw so Express error handling picks it up
           throw err;
@@ -224,11 +309,13 @@ function wrapExpressHandler(
     } catch (err) {
       if (!captured) {
         captured = true;
-        emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, undefined, err);
+        const durationMs = performance.now() - startTime;
+        traceReturn(callId, routeName, 'express', durationMs, (err instanceof Error ? err : new Error(String(err))).message);
+        emitExpressPayload(routeName, opts.environment, opts.maxDepth, input, undefined, err, durationMs);
       }
       throw err;
     }
-  };
+  }
 
   // Preserve function metadata
   Object.defineProperty(wrapped, 'name', { value: handler.name || routeName, configurable: true });
@@ -334,11 +421,22 @@ export function trickleMiddleware(
       return;
     }
 
+    // Wrap in request context for per-request correlation
+    withRequestContext(req, () => {
+      _handleRequest(req, res, next, opts, debug);
+    });
+  };
+}
+
+function _handleRequest(req: any, res: any, next: any, opts: any, debug: boolean): void {
     if (debug) {
       console.log(`[trickle/middleware] Intercepting ${req.method} ${req.originalUrl || req.url}`);
     }
 
     let captured = false;
+    const startTime = performance.now();
+    const prelimRouteName = `${req.method || 'UNKNOWN'} ${req.originalUrl || req.url || '/'}`;
+    const callId = traceCall(prelimRouteName, 'express');
 
     // We derive the route name lazily once the response is being sent,
     // because req.route is only populated after the handler matches.
@@ -350,7 +448,7 @@ export function trickleMiddleware(
       } catch {
         // ignore
       }
-      return `${req.method || 'UNKNOWN'} ${req.originalUrl || req.url || '/'}`;
+      return prelimRouteName;
     }
 
     const input = extractRequestInput(req);
@@ -362,12 +460,14 @@ export function trickleMiddleware(
         if (!captured) {
           captured = true;
           const routeName = getRouteName();
+          const durationMs = performance.now() - startTime;
+          traceReturn(callId, routeName, 'express', durationMs);
           if (debug) {
             console.log(`[trickle/middleware] Captured res.json for ${routeName}`);
           }
           // Re-extract input here because body parsers may have run since middleware was entered
           const latestInput = extractRequestInput(req);
-          emitExpressPayload(routeName, opts.environment, opts.maxDepth, latestInput, data);
+          emitExpressPayload(routeName, opts.environment, opts.maxDepth, latestInput, data, undefined, durationMs);
         }
         res.json = originalJson;
         return originalJson.call(res, data);
@@ -383,12 +483,14 @@ export function trickleMiddleware(
         if (!captured) {
           captured = true;
           const routeName = getRouteName();
+          const durationMs = performance.now() - startTime;
+          traceReturn(callId, routeName, 'express', durationMs);
           if (debug) {
             console.log(`[trickle/middleware] Captured res.send for ${routeName}`);
           }
           const latestInput = extractRequestInput(req);
           const output = typeof data === 'string' ? { __html: true } : data;
-          emitExpressPayload(routeName, opts.environment, opts.maxDepth, latestInput, output);
+          emitExpressPayload(routeName, opts.environment, opts.maxDepth, latestInput, output, undefined, durationMs);
         }
         res.send = originalSend;
         return originalSend.call(res, data);
@@ -396,5 +498,4 @@ export function trickleMiddleware(
     }
 
     next();
-  };
 }

package/src/request-context.ts

@@ -0,0 +1,64 @@
+/**
+ * Request context — propagates a request ID through async call chains.
+ *
+ * Uses Node.js AsyncLocalStorage so that all functions, queries, and logs
+ * within a single HTTP request share the same requestId, enabling
+ * per-request tracing (like Jaeger but with trickle's richer data).
+ *
+ * Usage:
+ *   import { withRequestContext, getRequestId } from './request-context';
+ *   // In Express middleware:
+ *   app.use((req, res, next) => withRequestContext(req, next));
+ *   // Anywhere in the call chain:
+ *   const id = getRequestId(); // returns the current request's ID
+ */
+
+let als: any = null;
+let counter = 0;
+
+try {
+  const { AsyncLocalStorage } = require('async_hooks');
+  als = new AsyncLocalStorage();
+} catch {
+  // AsyncLocalStorage not available (older Node versions)
+}
+
+export interface RequestContext {
+  requestId: string;
+  method?: string;
+  path?: string;
+  startTime: number;
+}
+
+/**
+ * Run a callback within a request context.
+ */
+export function withRequestContext(req: any, callback: () => void): void {
+  if (!als) { callback(); return; }
+
+  const ctx: RequestContext = {
+    requestId: `req-${++counter}-${Date.now().toString(36)}`,
+    method: req?.method,
+    path: req?.path || req?.url,
+    startTime: Date.now(),
+  };
+
+  als.run(ctx, callback);
+}
+
+/**
+ * Get the current request ID (if inside a request context).
+ */
+export function getRequestId(): string | undefined {
+  if (!als) return undefined;
+  const ctx = als.getStore() as RequestContext | undefined;
+  return ctx?.requestId;
+}
+
+/**
+ * Get the full request context.
+ */
+export function getRequestContext(): RequestContext | undefined {
+  if (!als) return undefined;
+  return als.getStore() as RequestContext | undefined;
+}