trickle-observe 0.2.125 → 0.2.127

package/dist/fastify.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Instrument a Fastify instance by monkey-patching route registration methods.
+ *
+ * Must be called BEFORE routes are defined:
+ *
+ *   import Fastify from 'fastify';
+ *   import { instrumentFastify } from 'trickle';
+ *
+ *   const app = Fastify();
+ *   instrumentFastify(app);
+ *
+ *   app.get('/api/users', async (request, reply) => { ... });
+ *
+ * Each registered handler is wrapped to capture:
+ * - Input: `{ body, params, query }` from the request
+ * - Output: the data returned or passed to `reply.send()`
+ * - Errors: exceptions thrown in async handlers
+ */
+export declare function instrumentFastify(fastify: any, userOpts?: {
+    enabled?: boolean;
+    environment?: string;
+    sampleRate?: number;
+    maxDepth?: number;
+}): void;
+/**
+ * Fastify plugin-style instrumentation using onRequest/onResponse hooks.
+ *
+ * Use this as an alternative to monkey-patching:
+ *
+ *   import Fastify from 'fastify';
+ *   import { tricklePlugin } from 'trickle';
+ *
+ *   const app = Fastify();
+ *   app.register(tricklePlugin);
+ */
+export declare function tricklePlugin(fastify: any, userOpts: any, done: () => void): void;

package/dist/fastify.js

@@ -0,0 +1,398 @@
+"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.instrumentFastify = instrumentFastify;
+exports.tricklePlugin = tricklePlugin;
+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 call_trace_1 = require("./call-trace");
+const fastifyCache = new cache_1.TypeCache();
+// ── Input extraction ──
+function extractFastifyInput(request) {
+    const input = {};
+    try {
+        if (request.body !== undefined && request.body !== null && typeof request.body === 'object' && Object.keys(request.body).length > 0) {
+            input.body = request.body;
+        }
+    }
+    catch { }
+    try {
+        if (request.params && typeof request.params === 'object' && Object.keys(request.params).length > 0) {
+            input.params = request.params;
+        }
+    }
+    catch { }
+    try {
+        if (request.query && typeof request.query === 'object' && Object.keys(request.query).length > 0) {
+            input.query = request.query;
+        }
+    }
+    catch { }
+    return input;
+}
+// ── Sample sanitization (local copy) ──
+function sanitizeSample(value, depth = 3) {
+    if (depth <= 0)
+        return '[truncated]';
+    if (value === null || value === undefined)
+        return value;
+    const t = typeof value;
+    if (t === 'string') {
+        const s = value;
+        return s.length > 200 ? s.substring(0, 200) + '...' : s;
+    }
+    if (t === 'number' || t === 'boolean')
+        return value;
+    if (t === 'bigint')
+        return String(value);
+    if (t === 'symbol')
+        return String(value);
+    if (t === 'function')
+        return `[Function: ${value.name || 'anonymous'}]`;
+    if (Array.isArray(value)) {
+        return value.slice(0, 5).map(item => sanitizeSample(item, depth - 1));
+    }
+    if (t === 'object') {
+        if (value instanceof Date)
+            return value.toISOString();
+        if (value instanceof RegExp)
+            return String(value);
+        if (value instanceof Error)
+            return { error: value.message };
+        if (value instanceof Map)
+            return `[Map: ${value.size} entries]`;
+        if (value instanceof Set)
+            return `[Set: ${value.size} items]`;
+        const obj = value;
+        const result = {};
+        const keys = Object.keys(obj).slice(0, 20);
+        for (const key of keys) {
+            try {
+                result[key] = sanitizeSample(obj[key], depth - 1);
+            }
+            catch {
+                result[key] = '[unreadable]';
+            }
+        }
+        return result;
+    }
+    return String(value);
+}
+// ── Error file writing ──
+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 { }
+        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-observe')) {
+                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
+    }
+}
+// ── Payload emission ──
+function emitFastifyPayload(functionName, environment, maxDepth, input, output, error, durationMs) {
+    try {
+        const functionKey = `fastify::${functionName}`;
+        const argsType = (0, type_inference_1.inferType)(input, maxDepth);
+        const returnType = error ? { kind: 'unknown' } : (0, type_inference_1.inferType)(output, maxDepth);
+        const hash = (0, type_hash_1.hashType)(argsType, returnType);
+        if (!error && !fastifyCache.shouldSend(functionKey, hash)) {
+            return;
+        }
+        if (!error) {
+            fastifyCache.markSent(functionKey, hash);
+        }
+        const payload = {
+            functionName,
+            module: 'fastify',
+            language: 'js',
+            environment,
+            typeHash: hash,
+            argsType,
+            returnType,
+            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 = {
+                type: err.constructor?.name || 'Error',
+                message: err.message,
+                stackTrace: err.stack,
+                argsSnapshot: sanitizeSample(input),
+            };
+            writeErrorToFile(error, input, functionName);
+        }
+        (0, transport_1.enqueue)(payload);
+    }
+    catch {
+        // Never crash the user's app
+    }
+}
+// ── Handler wrapping ──
+function wrapFastifyHandler(handler, routeName, opts) {
+    const wrapped = async function (request, reply) {
+        // Sample rate check
+        if (opts.sampleRate < 1 && Math.random() > opts.sampleRate) {
+            return handler.call(this, request, reply);
+        }
+        const input = extractFastifyInput(request);
+        let captured = false;
+        const startTime = performance.now();
+        const callId = (0, call_trace_1.traceCall)(routeName, 'fastify');
+        // Intercept reply.send() to capture output
+        const originalSend = reply.send;
+        if (typeof originalSend === 'function') {
+            reply.send = function (data) {
+                if (!captured) {
+                    captured = true;
+                    const durationMs = performance.now() - startTime;
+                    (0, call_trace_1.traceReturn)(callId, routeName, 'fastify', durationMs);
+                    const output = typeof data === 'string' ? { __html: true } : data;
+                    emitFastifyPayload(routeName, opts.environment, opts.maxDepth, input, output, undefined, durationMs);
+                }
+                reply.send = originalSend; // restore
+                return originalSend.call(reply, data);
+            };
+        }
+        try {
+            const result = await handler.call(this, request, reply);
+            // Fastify allows returning a value directly (auto-serialized)
+            if (result !== undefined && !captured) {
+                captured = true;
+                const durationMs = performance.now() - startTime;
+                (0, call_trace_1.traceReturn)(callId, routeName, 'fastify', durationMs);
+                emitFastifyPayload(routeName, opts.environment, opts.maxDepth, input, result, undefined, durationMs);
+            }
+            return result;
+        }
+        catch (err) {
+            if (!captured) {
+                captured = true;
+                const durationMs = performance.now() - startTime;
+                (0, call_trace_1.traceReturn)(callId, routeName, 'fastify', durationMs, (err instanceof Error ? err : new Error(String(err))).message);
+                emitFastifyPayload(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 });
+    return wrapped;
+}
+// ── Public API ──
+/**
+ * Instrument a Fastify instance by monkey-patching route registration methods.
+ *
+ * Must be called BEFORE routes are defined:
+ *
+ *   import Fastify from 'fastify';
+ *   import { instrumentFastify } from 'trickle';
+ *
+ *   const app = Fastify();
+ *   instrumentFastify(app);
+ *
+ *   app.get('/api/users', async (request, reply) => { ... });
+ *
+ * Each registered handler is wrapped to capture:
+ * - Input: `{ body, params, query }` from the request
+ * - Output: the data returned or passed to `reply.send()`
+ * - Errors: exceptions thrown in async handlers
+ */
+function instrumentFastify(fastify, userOpts) {
+    const opts = {
+        enabled: userOpts?.enabled !== false,
+        environment: userOpts?.environment || (0, env_detect_1.detectEnvironment)(),
+        sampleRate: userOpts?.sampleRate ?? 1,
+        maxDepth: userOpts?.maxDepth ?? 5,
+    };
+    if (!opts.enabled)
+        return;
+    // Fastify shorthand methods: .get(), .post(), .put(), .delete(), .patch(), .all()
+    const methods = ['get', 'post', 'put', 'delete', 'patch', 'head', 'options', 'all'];
+    for (const method of methods) {
+        const original = fastify[method];
+        if (typeof original !== 'function')
+            continue;
+        fastify[method] = function (path, ...args) {
+            const pathStr = typeof path === 'string' ? path : String(path);
+            const routeName = `${method.toUpperCase()} ${pathStr}`;
+            // Fastify shorthand: .get(path, opts?, handler)
+            // args can be [handler] or [opts, handler]
+            const wrapped = args.map((arg) => {
+                if (typeof arg === 'function') {
+                    try {
+                        return wrapFastifyHandler(arg, routeName, opts);
+                    }
+                    catch {
+                        return arg;
+                    }
+                }
+                // If it's an options object with a handler property, wrap that
+                if (arg && typeof arg === 'object' && typeof arg.handler === 'function') {
+                    try {
+                        arg.handler = wrapFastifyHandler(arg.handler, routeName, opts);
+                    }
+                    catch { }
+                }
+                return arg;
+            });
+            return original.call(this, path, ...wrapped);
+        };
+    }
+    // Also wrap fastify.route({ method, url, handler })
+    const originalRoute = fastify.route;
+    if (typeof originalRoute === 'function') {
+        fastify.route = function (routeOptions) {
+            if (routeOptions && typeof routeOptions.handler === 'function') {
+                const method = (Array.isArray(routeOptions.method) ? routeOptions.method[0] : routeOptions.method) || 'ALL';
+                const url = routeOptions.url || routeOptions.path || '/';
+                const routeName = `${method.toUpperCase()} ${url}`;
+                try {
+                    routeOptions.handler = wrapFastifyHandler(routeOptions.handler, routeName, opts);
+                }
+                catch { }
+            }
+            return originalRoute.call(this, routeOptions);
+        };
+    }
+}
+/**
+ * Fastify plugin-style instrumentation using onRequest/onResponse hooks.
+ *
+ * Use this as an alternative to monkey-patching:
+ *
+ *   import Fastify from 'fastify';
+ *   import { tricklePlugin } from 'trickle';
+ *
+ *   const app = Fastify();
+ *   app.register(tricklePlugin);
+ */
+function tricklePlugin(fastify, userOpts, done) {
+    const opts = {
+        enabled: userOpts?.enabled !== false,
+        environment: userOpts?.environment || (0, env_detect_1.detectEnvironment)(),
+        sampleRate: userOpts?.sampleRate ?? 1,
+        maxDepth: userOpts?.maxDepth ?? 5,
+    };
+    if (!opts.enabled) {
+        done();
+        return;
+    }
+    // Use onRequest to start timing and onResponse to capture result
+    fastify.addHook('onRequest', async (request, _reply) => {
+        if (opts.sampleRate < 1 && Math.random() > opts.sampleRate)
+            return;
+        request.__trickleStart = performance.now();
+        request.__trickleInput = extractFastifyInput(request);
+        request.__trickleCallId = (0, call_trace_1.traceCall)(`${request.method} ${request.url}`, 'fastify');
+    });
+    fastify.addHook('onSend', async (request, reply, payload) => {
+        if (!request.__trickleStart)
+            return payload;
+        const durationMs = performance.now() - request.__trickleStart;
+        const routeName = `${request.method} ${request.routeOptions?.url || request.url}`;
+        const input = request.__trickleInput || extractFastifyInput(request);
+        (0, call_trace_1.traceReturn)(request.__trickleCallId, routeName, 'fastify', durationMs);
+        // Parse payload if it's JSON string
+        let output;
+        if (typeof payload === 'string') {
+            try {
+                output = JSON.parse(payload);
+            }
+            catch {
+                output = { __html: true };
+            }
+        }
+        else {
+            output = payload;
+        }
+        emitFastifyPayload(routeName, opts.environment, opts.maxDepth, input, output, undefined, durationMs);
+        delete request.__trickleStart;
+        delete request.__trickleInput;
+        delete request.__trickleCallId;
+        return payload; // Must return payload for Fastify hook chain
+    });
+    fastify.addHook('onError', async (request, _reply, error) => {
+        if (!request.__trickleStart)
+            return;
+        const durationMs = performance.now() - request.__trickleStart;
+        const routeName = `${request.method} ${request.routeOptions?.url || request.url}`;
+        const input = request.__trickleInput || extractFastifyInput(request);
+        (0, call_trace_1.traceReturn)(request.__trickleCallId, routeName, 'fastify', durationMs, error?.message);
+        emitFastifyPayload(routeName, opts.environment, opts.maxDepth, input, undefined, error, durationMs);
+        delete request.__trickleStart;
+    });
+    done();
+}

package/dist/index.d.ts

@@ -42,14 +42,16 @@ export declare function trickleExpress(app: any, opts?: {
     maxDepth?: number;
 }): void;
 /**
- * Auto-instrument a framework app. Currently supports Express.
+ * Auto-instrument a framework app. Supports Express, Fastify, and Koa.
  *
  * Usage:
  *   import { instrument } from 'trickle';
- *   const app = express();
  *   instrument(app);
  *
- * Detects Express by checking for `app.listen` and `app.get` (function) on the object.
+ * Detects the framework automatically:
+ * - Express: has `app.listen`, `app.get`, `app.use`, `app.set`
+ * - Fastify: has `app.route`, `app.register`, `app.addHook`
+ * - Koa: has `app.use`, `app.listen`, `app.context` (but no `app.get` method on the app itself)
  */
 export declare function instrument(app: any, opts?: {
     enabled?: boolean;
@@ -60,6 +62,8 @@ export declare function instrument(app: any, opts?: {
 export type { TypeNode, GlobalOpts, TrickleOpts, IngestPayload } from './types';
 export { flush } from './transport';
 export { instrumentExpress, trickleMiddleware } from './express';
+export { instrumentFastify, tricklePlugin } from './fastify';
+export { instrumentKoa, instrumentKoaRouter } from './koa';
 export { observe, observeFn } from './observe';
 export type { ObserveOpts } from './observe';
 export { wrapFunction } from './wrap';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.wrapFunction = exports.observeFn = exports.observe = exports.trickleMiddleware = exports.instrumentExpress = exports.flush = void 0;
+exports.wrapFunction = exports.observeFn = exports.observe = exports.instrumentKoaRouter = exports.instrumentKoa = exports.tricklePlugin = exports.instrumentFastify = exports.trickleMiddleware = exports.instrumentExpress = exports.flush = void 0;
 exports.configure = configure;
 exports.trickle = trickle;
 exports.trickleHandler = trickleHandler;
@@ -10,6 +10,8 @@ const transport_1 = require("./transport");
 const wrap_1 = require("./wrap");
 const env_detect_1 = require("./env-detect");
 const express_1 = require("./express");
+const fastify_1 = require("./fastify");
+const koa_1 = require("./koa");
 let globalOpts = {
     backendUrl: 'http://localhost:4888',
     batchIntervalMs: 2000,
@@ -108,22 +110,46 @@ function trickleExpress(app, opts) {
     });
 }
 /**
- * Auto-instrument a framework app. Currently supports Express.
+ * Auto-instrument a framework app. Supports Express, Fastify, and Koa.
  *
  * Usage:
  *   import { instrument } from 'trickle';
- *   const app = express();
  *   instrument(app);
  *
- * Detects Express by checking for `app.listen` and `app.get` (function) on the object.
+ * Detects the framework automatically:
+ * - Express: has `app.listen`, `app.get`, `app.use`, `app.set`
+ * - Fastify: has `app.route`, `app.register`, `app.addHook`
+ * - Koa: has `app.use`, `app.listen`, `app.context` (but no `app.get` method on the app itself)
  */
 function instrument(app, opts) {
-    // Detect Express-like app
-    if (app && typeof app.listen === 'function' && typeof app.get === 'function' && typeof app.use === 'function') {
-        trickleExpress(app, opts);
+    if (!app) {
+        if (typeof console !== 'undefined' && console.warn) {
+            console.warn('[trickle] instrument(): received null/undefined app');
+        }
+        return;
+    }
+    const mergedOpts = {
+        enabled: opts?.enabled ?? globalOpts.enabled,
+        environment: opts?.environment ?? globalOpts.environment ?? (0, env_detect_1.detectEnvironment)(),
+        sampleRate: opts?.sampleRate ?? 1,
+        maxDepth: opts?.maxDepth ?? 5,
+    };
+    // Detect Fastify: has .route(), .register(), .addHook()
+    if (typeof app.route === 'function' && typeof app.register === 'function' && typeof app.addHook === 'function') {
+        (0, fastify_1.instrumentFastify)(app, mergedOpts);
+        return;
+    }
+    // Detect Koa: has .use(), .listen(), .context (but NOT .get as a route method on the app object)
+    // Koa apps have a .context property and .use() but .get is only defined on koa-router
+    if (typeof app.use === 'function' && typeof app.listen === 'function' && app.context !== undefined && typeof app.set !== 'function') {
+        (0, koa_1.instrumentKoa)(app, mergedOpts);
+        return;
+    }
+    // Detect Express: has .listen(), .get(), .use(), .set()
+    if (typeof app.listen === 'function' && typeof app.get === 'function' && typeof app.use === 'function') {
+        trickleExpress(app, mergedOpts);
         return;
     }
-    // Future: detect other frameworks here (Koa, Fastify, etc.)
     if (typeof console !== 'undefined' && console.warn) {
         console.warn('[trickle] instrument(): could not detect a supported framework on the provided object');
     }
@@ -167,6 +193,12 @@ Object.defineProperty(exports, "flush", { enumerable: true, get: function () { r
 var express_2 = require("./express");
 Object.defineProperty(exports, "instrumentExpress", { enumerable: true, get: function () { return express_2.instrumentExpress; } });
 Object.defineProperty(exports, "trickleMiddleware", { enumerable: true, get: function () { return express_2.trickleMiddleware; } });
+var fastify_2 = require("./fastify");
+Object.defineProperty(exports, "instrumentFastify", { enumerable: true, get: function () { return fastify_2.instrumentFastify; } });
+Object.defineProperty(exports, "tricklePlugin", { enumerable: true, get: function () { return fastify_2.tricklePlugin; } });
+var koa_2 = require("./koa");
+Object.defineProperty(exports, "instrumentKoa", { enumerable: true, get: function () { return koa_2.instrumentKoa; } });
+Object.defineProperty(exports, "instrumentKoaRouter", { enumerable: true, get: function () { return koa_2.instrumentKoaRouter; } });
 var observe_1 = require("./observe");
 Object.defineProperty(exports, "observe", { enumerable: true, get: function () { return observe_1.observe; } });
 Object.defineProperty(exports, "observeFn", { enumerable: true, get: function () { return observe_1.observeFn; } });

package/dist/koa.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Instrument a Koa application with observability middleware.
+ *
+ * Usage:
+ *   import Koa from 'koa';
+ *   import { instrumentKoa } from 'trickle';
+ *
+ *   const app = new Koa();
+ *   instrumentKoa(app);  // Add BEFORE routes
+ *
+ * Captures:
+ * - Input: `{ body, params, query }` from the request context
+ * - Output: `ctx.body` value set by route handlers
+ * - Errors: exceptions thrown in middleware/handlers
+ * - Timing: request duration in milliseconds
+ *
+ * Works with koa-router and @koa/router for named route paths.
+ */
+export declare function instrumentKoa(app: any, userOpts?: {
+    enabled?: boolean;
+    environment?: string;
+    sampleRate?: number;
+    maxDepth?: number;
+}): void;
+/**
+ * Instrument a koa-router (or @koa/router) instance by monkey-patching route methods.
+ *
+ * Usage:
+ *   import Router from '@koa/router';
+ *   import { instrumentKoaRouter } from 'trickle';
+ *
+ *   const router = new Router();
+ *   instrumentKoaRouter(router);
+ *
+ *   router.get('/api/users', async (ctx) => { ... });
+ *
+ * This provides more precise route names (e.g., "GET /api/users/:id")
+ * compared to the middleware approach.
+ */
+export declare function instrumentKoaRouter(router: any, userOpts?: {
+    enabled?: boolean;
+    environment?: string;
+    sampleRate?: number;
+    maxDepth?: number;
+}): void;