peekinside 1.2.5 → 1.3.0

package/src/instrumentation/jobs.js

@@ -1,8 +1,9 @@
 /**
  * Job runs from the common job libraries, without code changes: node-cron and cron (scheduled
- * tasks, with their cron expression, so PeekInside can tell when one misses its run) and BullMQ
+ * tasks, with their cron expression, so PeekInside can tell when one misses its run), BullMQ
  * (queue workers, with the queue, the attempt and the job's data, and the schedule of repeatable
- * jobs). Each run goes through JobRunner, exactly as PeekInside.job() would run it.
+ * jobs) and @nestjs/schedule (@Cron, @Interval and @Timeout methods, named after their class and
+ * method). Each run goes through JobRunner, exactly as PeekInside.job() would run it.
  *
  * A schedule is recorded with its time zone: the one given to the library, else the process's
  * own, which is the one these libraries read a cron expression in without one.
@@ -20,6 +21,10 @@ import { JobRunner } from '../jobs/job-runner.js';
 const kWrapped = Symbol('peekInside.job');
 // node-cron tasks created through named imports are found by looking again now and then.
 const RESCAN_MS = 30_000;
+// @nestjs/schedule's SchedulerType.
+const NEST_CRON = 1;
+const NEST_TIMEOUT = 2;
+const NEST_INTERVAL = 3;
 
 /**
  * Patches job libraries.
@@ -113,6 +118,67 @@ export class JobInstrumentation {
     return true;
   }
 
+  /**
+   * @nestjs/schedule: every @Cron, @Interval and @Timeout method runs as a job run, named after the
+   * name given to the decorator, else its class and method ("ReportsService.sendDigest"), with its
+   * schedule. The scheduler catches what a method throws and only logs it, so a failing method would
+   * otherwise look like one that ran fine: the run records the error, then the scheduler logs it as
+   * before. Methods are wrapped as the scheduler registers them, when the app initializes.
+   *
+   * @param {*} explorer - The ScheduleExplorer class, or the app's instance of it
+   * @returns {boolean}
+   */
+  static nestSchedule(explorer) {
+    const proto = typeof explorer === 'function' ? explorer.prototype : explorer && typeof explorer === 'object' ? Object.getPrototypeOf(explorer) : null;
+    if (!proto || typeof proto.wrapFunctionInTryCatchBlocks !== 'function') return false;
+    if (proto[kWrapped]) return true;
+    const original = proto.wrapFunctionInTryCatchBlocks;
+    proto.wrapFunctionInTryCatchBlocks = function (methodRef, instance) {
+      let job = null;
+      try {
+        job = typeof methodRef === 'function' ? nestJob(this, methodRef, instance) : null;
+      } catch (error) {
+        job = null;
+      }
+      if (!job) return original.apply(this, arguments);
+      const run = function () {
+        const args = arguments;
+        return JobRunner.run(job.name, () => methodRef.apply(this, args), job.options);
+      };
+      // cron fires the wrapper as a CronJob callback: it is a run already.
+      return JobInstrumentation.markRun(original.call(this, run, instance));
+    };
+    Object.defineProperty(proto, kWrapped, { value: true });
+    return true;
+  }
+
+  /**
+   * Whether a function records its own job runs (see markRun()).
+   *
+   * @param {*} fn
+   * @returns {boolean}
+   */
+  static isRun(fn) {
+    return typeof fn === 'function' && Boolean(fn[kWrapped]);
+  }
+
+  /**
+   * Marks a function that records its own job runs, so the cron patch doesn't record it again.
+   *
+   * @param {*} fn
+   * @returns {*} fn
+   */
+  static markRun(fn) {
+    if (typeof fn === 'function' && !fn[kWrapped]) {
+      try {
+        Object.defineProperty(fn, kWrapped, { value: true });
+      } catch (error) {
+        // A frozen function is recorded by both, which costs a run, never the job.
+      }
+    }
+    return fn;
+  }
+
   /**
    * Patches the ES module build of a package installed in the project, when it has one.
    *
@@ -175,6 +241,31 @@ function wrapCronJobCallback(job, callback) {
   return wrapped;
 }
 
+// What a @nestjs/schedule method runs as: its name, and its schedule from the decorator's
+// metadata (a cron expression, or "@every <ms>ms" for an interval; a timeout runs once).
+function nestJob(explorer, methodRef, instance) {
+  const metadata = explorer.metadataAccessor;
+  const read = (method) => (metadata && typeof metadata[method] === 'function' ? metadata[method](methodRef) : undefined);
+  const owner = instance && instance.constructor && typeof instance.constructor.name === 'string' ? instance.constructor.name : '';
+  const method = typeof methodRef.name === 'string' ? methodRef.name : '';
+  const fallback = owner && method ? `${owner}.${method}` : method || owner || 'job';
+  const named = (value) => (typeof value === 'string' && value.trim() ? value : fallback);
+  const type = read('getSchedulerType');
+  if (type === NEST_CRON) {
+    const cron = read('getCronMetadata') || {};
+    const schedule = typeof cron.cronTime === 'string' && cron.cronTime.trim() ? cron.cronTime : undefined;
+    const timezone = typeof cron.timeZone === 'string' && cron.timeZone ? cron.timeZone : schedule && cron.utcOffset === undefined ? localTimeZone() : undefined;
+    return { name: named(cron.name), options: { schedule, timezone, trigger: 'cron' } };
+  }
+  if (type === NEST_INTERVAL) {
+    const interval = read('getIntervalMetadata') || {};
+    const every = Number.isFinite(interval.timeout) && interval.timeout > 0 ? `@every ${interval.timeout}ms` : undefined;
+    return { name: named(read('getSchedulerName')), options: { schedule: every, trigger: 'cron' } };
+  }
+  if (type === NEST_TIMEOUT) return { name: named(read('getSchedulerName')), options: { trigger: 'cron' } };
+  return { name: fallback, options: { trigger: 'cron' } };
+}
+
 // The process's time zone (TZ, else the system's).
 function localTimeZone() {
   try {

package/src/instrumentation/loggers.js

@@ -1,12 +1,18 @@
 /**
- * Lines written with pino and winston, like console lines: on the timeline of the request (or job
- * run) they belong to, and on the Logs page. Only lines the logger actually writes are recorded
- * (a level it has turned off is skipped), and what the logger writes is untouched.
+ * Lines written with pino, winston and NestJS's Logger, like console lines: on the timeline of the
+ * request (or job run) they belong to, and on the Logs page. Only lines the logger actually writes
+ * are recorded (a level it has turned off is skipped), and what the logger writes is untouched.
  *
- * Both are patched on a prototype every logger shares, so loggers created before PeekInside, child
+ * Each is patched on a prototype every logger shares, so loggers created before PeekInside, child
  * loggers and loggers imported as ES modules are all covered.
+ *
+ * Nest's default logger (ConsoleLogger) writes to process.stdout itself, past the console. Its
+ * lines keep the class that wrote them ("[OrdersService] Charging card"), and the redaction the
+ * app set up applies to them too. Nest's own startup lines (modules loaded, routes mapped) are
+ * left out; its warnings and errors are not.
  */
 
+import { inspect } from 'util';
 import { LogCapture } from '../logs/log-capture.js';
 import { Timeline } from '../timeline/timeline.js';
 
@@ -16,6 +22,10 @@ const PINO_LEVELS = { trace: 'debug', debug: 'debug', info: 'info', warn: 'warn'
 const WINSTON_LEVELS = { error: 'error', warn: 'warn', info: 'info', http: 'info', verbose: 'debug', debug: 'debug', silly: 'debug' };
 // Keys of a winston `info` that aren't the line's own data.
 const WINSTON_OWN = new Set(['level', 'message', 'timestamp', 'splat']);
+const NEST_LEVELS = { log: 'info', error: 'error', warn: 'warn', debug: 'debug', verbose: 'debug', fatal: 'error' };
+// Nest's own classes that log while the app starts: their info lines are startup noise.
+const NEST_STARTUP = new Set(['NestFactory', 'InstanceLoader', 'RoutesResolver', 'RouterExplorer', 'NestApplication', 'NestMicroservice', 'WebSocketsController']);
+const INSPECT = { depth: 4, breakLength: Infinity, compact: true };
 
 /**
  * Patches logging libraries.
@@ -88,6 +98,70 @@ export class LoggerInstrumentation {
     Object.defineProperty(proto, kPatched, { value: true });
     return true;
   }
+
+  /**
+   * Patches NestJS's ConsoleLogger, the logger behind Nest's Logger unless the app set its own:
+   * every line goes through printMessages(), after the level check.
+   *
+   * @param {*} target - A ConsoleLogger (or subclass) instance or class
+   * @returns {boolean} Whether it is (now) patched
+   */
+  static nest(target) {
+    let proto = typeof target === 'function' ? target.prototype : target;
+    while (proto && !(Object.prototype.hasOwnProperty.call(proto, 'printMessages') && typeof proto.formatPid === 'function')) {
+      proto = Object.getPrototypeOf(proto);
+    }
+    if (!proto || typeof proto.printMessages !== 'function') return false;
+    if (proto[kPatched]) return true;
+    const original = proto.printMessages;
+    proto.printMessages = function (messages) {
+      const args = Array.prototype.slice.call(arguments);
+      try {
+        // Nest 12 resolves lazy messages (functions) while printing: they are resolved once here,
+        // and the logger prints the values.
+        if (Array.isArray(messages) && typeof this.resolveMessage === 'function') {
+          args[0] = messages.map((message) => (typeof message === 'function' ? this.resolveMessage(message) : message));
+        }
+        nestLine(this, args[0], args[1], args[2], args[4], args[5]);
+      } catch (error) {
+        // The line is written all the same.
+      }
+      return original.apply(this, args);
+    };
+    Object.defineProperty(proto, kPatched, { value: true });
+    return true;
+  }
+}
+
+// One call of ConsoleLogger#printMessages(messages, context, logLevel, writeStreamType, errorStack,
+// params): a line per message, as Nest prints them.
+function nestLine(logger, messages, context, logLevel, errorStack, params) {
+  // With forceConsole, Nest prints through the console, which records the lines.
+  if (!Array.isArray(messages) || (logger.options && logger.options.forceConsole)) return;
+  const level = NEST_LEVELS[logLevel] || 'info';
+  const where = typeof context === 'string' ? context : '';
+  if (NEST_STARTUP.has(where) && (level === 'info' || level === 'debug')) return;
+  const timeline = Timeline.current();
+  if (!(timeline && timeline.settings.captureLogs) && !LogCapture.wants(level)) return;
+
+  const redact = logger.redactor && typeof logger.redact === 'function' ? (value) => logger.redact(value) : (value) => value;
+  const fields = {};
+  if (params && typeof params === 'object') Object.assign(fields, redact(params));
+  if (where) fields.context = where;
+  if (typeof errorStack === 'string' && errorStack) fields.stack = errorStack;
+  for (const message of messages) {
+    if (typeof message === 'function') continue;
+    const value = redact(message);
+    const own = value instanceof Error ? { ...fields, err: errorFields(value), ...(fields.stack ? {} : { stack: String(value.stack || '') }) } : fields;
+    const text = nestText(value);
+    capture(level, where ? `[${where}] ${text}` : text, Object.keys(own).length ? own : undefined, 'nest');
+  }
+}
+
+function nestText(value) {
+  if (typeof value === 'string') return value;
+  if (value instanceof Error) return `${value.name}: ${value.message}`;
+  return inspect(value, INSPECT);
 }
 
 function capture(level, message, fields, source) {

package/src/integrations/fastify.js

@@ -10,6 +10,7 @@ import { FrameworkAdapter } from './framework-adapter.js';
  * Records requests from a Fastify onRequest hook, and errors from an onError hook.
  *
  * onRequest runs before Fastify reads the body, so bodies are captured as Fastify parses them.
+ * It runs once Fastify has routed the request, so the route pattern and parameters are known.
  * Hooks must be added before the app is ready, so attach before fastify.listen().
  */
 export class FastifyAdapter extends FrameworkAdapter {
@@ -36,7 +37,10 @@ export class FastifyAdapter extends FrameworkAdapter {
   attach(fastify) {
     fastify.addHook('onRequest', (request, reply, done) => {
       ExchangeRecorder.setBodySource(request.raw, () => request.body);
-      this.peekInside._intercept(request.raw, reply.raw, done, 'fastify');
+      this.peekInside._intercept(request.raw, reply.raw, () => {
+        FastifyAdapter._noteRoute(request);
+        done();
+      }, 'fastify');
     });
     if (this.peekInside.options.captureExceptions !== false) {
       fastify.addHook('onError', (request, reply, error, done) => {
@@ -49,6 +53,19 @@ export class FastifyAdapter extends FrameworkAdapter {
     }
   }
 
+  // The route Fastify matched (routerPath before Fastify 4.10); parameters stay on its request.
+  static _noteRoute(request) {
+    try {
+      const context = RequestContext.of(request.raw);
+      if (!context) return;
+      const options = request.routeOptions;
+      const route = options && typeof options === 'object' ? options.url : request.routerPath;
+      context.noteRoute({ route: typeof route === 'string' ? route : null, params: () => request.params });
+    } catch (error) {
+      // The request is recorded without them.
+    }
+  }
+
   static _noteError(request, error) {
     try {
       const context = RequestContext.of(request.raw);

package/src/integrations/hono.js

@@ -0,0 +1,209 @@
+/**
+ * Hono integration, for Hono apps served on Node.js by @hono/node-server.
+ *
+ * node-server hands each request to app.fetch() along with the Node.js request and response
+ * (`env.incoming` and `env.outgoing`), so app.fetch is wrapped to record them; the rest of the
+ * request runs inside its context. node-server reads app.fetch when serve() is called, so attach
+ * before serve().
+ *
+ * Hono catches what a handler throws and passes it to the app's error handler (app.onError()), or
+ * to its default one, which answers 500 and logs it. The error handler is wrapped, whenever the app
+ * sets it, to see each error: handled when the app set its own handler, unhandled with Hono's. A
+ * sub-app mounted with its own error handler (app.route()) answers its errors itself; they are found
+ * on the context (c.error) once the route's handler returns. HTTPExceptions with a 4xx status are
+ * how an app answers bad requests, and aren't recorded.
+ *
+ * Route patterns ("/users/:id") come from the router: each handler it matches for a request is
+ * wrapped to note its route when it runs, and to forget it when it hands the request on (next()),
+ * so a request's route is the one of the handler that answered it, wherever PeekInside was attached
+ * among the app's routes and middleware.
+ */
+
+import { RequestContext } from '../exceptions/request-context.js';
+import { FrameworkAdapter } from './framework-adapter.js';
+
+const kAttached = Symbol('peekInside.hono');
+
+/**
+ * Records a Hono app's requests from app.fetch(), its errors from its error handler, and its routes
+ * from its router.
+ */
+export class HonoAdapter extends FrameworkAdapter {
+  static framework = 'hono';
+
+  /**
+   * @param {*} app
+   * @returns {boolean} Whether `app` looks like a Hono app
+   */
+  static matches(app) {
+    return Boolean(app) && typeof app.fetch === 'function' && typeof app.route === 'function' && typeof app.onError === 'function' && Array.isArray(app.routes);
+  }
+
+  /**
+   * Wraps app.fetch, the error handler and the router's match(). An app is wrapped once.
+   *
+   * @param {Object} app - Hono app
+   * @returns {void}
+   */
+  attach(app) {
+    if (app[kAttached]) return;
+    Object.defineProperty(app, kAttached, { value: true });
+    if (this.peekInside.options.captureExceptions !== false) wrapErrorHandler(app);
+    wrapRouter(app.router);
+    wrapFetch(app, this.peekInside);
+  }
+}
+
+function wrapFetch(app, peekInside) {
+  const original = app.fetch;
+  app.fetch = function fetch(request, env) {
+    const incoming = env && env.incoming;
+    const outgoing = env && env.outgoing;
+    // Elsewhere than node-server (app.request() in tests, other runtimes): nothing to record.
+    if (!incoming || !outgoing || typeof outgoing.on !== 'function') return original.apply(this, arguments);
+    const args = arguments;
+    return peekInside._intercept(incoming, outgoing, () => dispatch(original, this, args, incoming), 'hono');
+  };
+}
+
+// What escapes app.fetch() is what Hono itself didn't handle: a value thrown that isn't an Error,
+// or an error handler that threw. node-server answers it with a 500.
+function dispatch(original, self, args, incoming) {
+  let result;
+  try {
+    result = original.apply(self, args);
+  } catch (error) {
+    noteError(incoming, error, false);
+    throw error;
+  }
+  if (result && typeof result.then === 'function') {
+    return result.then(undefined, (error) => {
+      noteError(incoming, error, false);
+      throw error;
+    });
+  }
+  return result;
+}
+
+// app.errorHandler becomes an accessor: setting it (app.onError() does) keeps the wrapper in front.
+function wrapErrorHandler(app) {
+  const isDefault = defaultHandlerTest(app);
+  let current = app.errorHandler;
+  if (typeof current !== 'function') return;
+  const wrapper = function (error, c) {
+    noteError(c && c.env && c.env.incoming, error, !isDefault(current));
+    return current.apply(this, arguments);
+  };
+  Object.defineProperty(app, 'errorHandler', {
+    configurable: true,
+    enumerable: true,
+    get() {
+      return wrapper;
+    },
+    set(handler) {
+      current = handler;
+    }
+  });
+}
+
+// Hono's own error handler is the one a new app of the same class has; when one can't be made,
+// it is known by its name.
+function defaultHandlerTest(app) {
+  let fallback = null;
+  try {
+    const probe = typeof app.constructor === 'function' ? new app.constructor() : null;
+    fallback = probe && typeof probe.errorHandler === 'function' ? probe.errorHandler : null;
+  } catch (error) {
+    fallback = null;
+  }
+  return (handler) => (fallback ? handler === fallback : Boolean(handler) && handler.name === 'errorHandler');
+}
+
+// The router's match() becomes an accessor too: Hono's routers replace it on first use (and the
+// RegExpRouter then calls the replacement, whose result is wrapped already).
+function wrapRouter(router) {
+  if (!router || typeof router.match !== 'function') return;
+  let current = router.match;
+  const cache = { tuples: new WeakMap(), lists: new WeakMap(), own: new WeakSet() };
+  const match = function match() {
+    return withRoutes(current.apply(this, arguments), cache);
+  };
+  Object.defineProperty(router, 'match', {
+    configurable: true,
+    get() {
+      return match;
+    },
+    set(fn) {
+      current = fn;
+    }
+  });
+}
+
+// A match result is [[[handler, route], params][], stash?]: the same result, its handlers wrapped.
+// Lists and handlers are wrapped once each (the RegExpRouter returns the same list for a route).
+function withRoutes(result, { tuples, lists, own }) {
+  if (!Array.isArray(result) || !Array.isArray(result[0]) || own.has(result[0])) return result;
+  const handlers = result[0];
+  let wrapped = lists.get(handlers);
+  if (!wrapped) {
+    wrapped = handlers.map((entry) => {
+      const tuple = Array.isArray(entry) ? entry[0] : null;
+      if (!Array.isArray(tuple) || typeof tuple[0] !== 'function') return entry;
+      let routed = tuples.get(tuple);
+      if (!routed) {
+        routed = [routeHandler(tuple[0], tuple[1]), tuple[1]];
+        tuples.set(tuple, routed);
+      }
+      return [routed, entry[1]];
+    });
+    lists.set(handlers, wrapped);
+    own.add(wrapped);
+  }
+  const copy = result.slice();
+  copy[0] = wrapped;
+  return copy;
+}
+
+function routeHandler(handler, route) {
+  const pattern = route && typeof route.path === 'string' ? route.path : null;
+  return function (c, next) {
+    const context = c && c.env ? RequestContext.of(c.env.incoming) : null;
+    if (!context) return handler.apply(this, arguments);
+    context.noteRoute({ route: pattern, params: () => c.req.param() });
+    const args = Array.prototype.slice.call(arguments);
+    if (typeof next === 'function') {
+      args[1] = function () {
+        context.noteRoute({ route: null, params: null });
+        return next.apply(this, arguments);
+      };
+    }
+    const result = handler.apply(this, args);
+    if (result && typeof result.then === 'function') {
+      return result.then((value) => {
+        noteCaught(context, c);
+        return value;
+      });
+    }
+    noteCaught(context, c);
+    return result;
+  };
+}
+
+// A sub-app's own error handler answered an error: Hono leaves it on the context.
+function noteCaught(context, c) {
+  try {
+    if (c.error && context.capture) context.capture.frameworkError(context, c.error, { mechanism: 'hono', handled: true, open: true });
+  } catch (failure) {
+    // Recording must never change the response.
+  }
+}
+
+// An error the app's own handler answers stays open: the handler may still throw it on.
+function noteError(incoming, error, handled) {
+  try {
+    const context = RequestContext.of(incoming) || RequestContext.current();
+    if (context && context.capture) context.capture.frameworkError(context, error, { mechanism: 'hono', handled, open: handled });
+  } catch (failure) {
+    // Recording must never change the error the app sees.
+  }
+}