peekinside 1.2.4 → 1.3.0

package/src/hub/spool-ingester.js

@@ -104,6 +104,7 @@ export class SpoolIngester {
     const exceptions = this.store.appendExceptions(payload.project.id, payload.exceptions).length;
     this.store.appendJobs(payload.project.id, payload.jobs);
     this.store.appendLogs(payload.project.id, payload.logs);
+    this.store.appendDumps(payload.project.id, payload.dumps);
     spool.remove(name);
     return { requests, exceptions };
   }

package/src/hub/store.js

@@ -16,6 +16,7 @@ export const DEFAULT_MAX_REQUESTS = 1000;
 export const DEFAULT_MAX_EXCEPTIONS = 500;
 export const DEFAULT_MAX_JOBS = 2000;
 export const DEFAULT_MAX_LOGS = 10000;
+export const DEFAULT_MAX_DUMPS = 1000;
 
 /**
  * All projects on this machine.
@@ -206,6 +207,47 @@ export class Store {
     if (project) project.clearLogs();
   }
 
+  /**
+   * Stores new dumps of a project.
+   *
+   * @param {string} projectId
+   * @param {Object[]} records
+   * @returns {Object[]}
+   */
+  appendDumps(projectId, records) {
+    const project = this.projects.get(projectId);
+    return project && records.length ? project.appendDumps(records) : [];
+  }
+
+  /**
+   * @param {string} projectId
+   * @param {{ after?: number, before?: number, limit: number }} query
+   * @returns {{ dumps: Object[], hasMore: boolean }|null}
+   */
+  listDumps(projectId, query) {
+    const project = this.projects.get(projectId);
+    return project ? project.listDumps(query) : null;
+  }
+
+  /**
+   * @param {string} projectId
+   * @param {string} dumpId
+   * @returns {Object|null}
+   */
+  dumpDetail(projectId, dumpId) {
+    const project = this.projects.get(projectId);
+    return project ? project.dumpDetail(dumpId) : null;
+  }
+
+  /**
+   * @param {string} projectId
+   * @returns {void}
+   */
+  clearDumps(projectId) {
+    const project = this.projects.get(projectId);
+    if (project) project.clearDumps();
+  }
+
   /**
    * Adds process samples of a project's process (kept in memory, for the Runtime page).
    *
@@ -398,7 +440,8 @@ export class Store {
       maxExceptions: this.maxExceptions,
       exceptionSegmentSize: this.exceptionSegmentSize,
       maxJobs: DEFAULT_MAX_JOBS,
-      maxLogs: DEFAULT_MAX_LOGS
+      maxLogs: DEFAULT_MAX_LOGS,
+      maxDumps: DEFAULT_MAX_DUMPS
     };
   }
 }

package/src/instrumentation/index.js

@@ -12,12 +12,14 @@
  *
  * Outgoing HTTP and console capture are process-wide subscriptions; they record only for code
  * running inside a request (log lines go to the Logs page from anywhere). Loggers (pino, winston)
- * and job libraries (node-cron, cron, BullMQ) are found and patched like the drivers.
+ * and job libraries (node-cron, cron, BullMQ) are found and patched like the drivers; NestJS's
+ * Logger and @nestjs/schedule are reached through the app instead (see integrations/nest.js).
  */
 
 import { createRequire } from 'module';
 import fs from 'fs';
 import path from 'path';
+import { pathToFileURL } from 'url';
 import { ConsoleInstrumentation } from './console.js';
 import { HttpInstrumentation } from './http.js';
 import { JobInstrumentation } from './jobs.js';
@@ -71,6 +73,10 @@ export class Instrumentation {
     if (!fromRoot) return patched;
     if (patchWith(fromRoot, 'pino', LoggerInstrumentation.pino)) patched.push('pino');
     if (patchWith(fromRoot, 'winston', LoggerInstrumentation.winston)) patched.push('winston');
+    // NestJS's ConsoleLogger, for a NestJS project.
+    if (declares(root, '@nestjs/common')) {
+      void importInstalled(fromRoot, '@nestjs/common', null, (common) => LoggerInstrumentation.nest(exported(common, 'ConsoleLogger')));
+    }
     return patched;
   }
 
@@ -92,6 +98,11 @@ export class Instrumentation {
       const directory = packageDirectory(main, name);
       if (directory) void JobInstrumentation.patchModuleBuild(directory, patch);
     }
+    // @nestjs/schedule registers a NestJS app's scheduled methods as the app initializes, which a
+    // worker (NestFactory.createApplicationContext()) does before it can be attached.
+    if (declares(root, '@nestjs/schedule')) {
+      void importInstalled(fromRoot, '@nestjs/schedule', path.join('dist', 'schedule.explorer.js'), (explorer) => JobInstrumentation.nestSchedule(exported(explorer, 'ScheduleExplorer')));
+    }
     return patched;
   }
 
@@ -217,14 +228,48 @@ function resolve(fromSomewhere, name) {
   }
 }
 
-// The folder of the package `name` that contains `file`.
+// The folder of the package `name` (scoped or not) that contains `file`.
 function packageDirectory(file, name) {
+  const [scope, base] = name.includes('/') ? name.split('/') : [null, name];
   for (let directory = path.dirname(file); ; directory = path.dirname(directory)) {
-    if (path.basename(directory) === name && fs.existsSync(path.join(directory, 'package.json'))) return directory;
+    const named = path.basename(directory) === base && (!scope || path.basename(path.dirname(directory)) === scope);
+    if (named && fs.existsSync(path.join(directory, 'package.json'))) return directory;
     if (path.dirname(directory) === directory) return null;
   }
 }
 
+// Whether the project's package.json depends on a package. Frameworks are only loaded for projects
+// that use them: a monorepo's shared node_modules may hold another app's.
+function declares(root, name) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    return ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'].some((field) => Boolean(pkg[field] && pkg[field][name]));
+  } catch (error) {
+    return false;
+  }
+}
+
+// Loads a package installed in the project (or one of its files) the way an import does, which
+// gives the module instance the app runs whether the package ships CommonJS or ES modules, and
+// patches it.
+async function importInstalled(fromRoot, name, file, patch) {
+  const main = resolve(fromRoot, name);
+  const directory = main && file ? packageDirectory(main, name) : null;
+  const target = file ? directory && path.join(directory, file) : main;
+  if (!target || !fs.existsSync(target)) return false;
+  try {
+    return patch(await import(pathToFileURL(target).href));
+  } catch (error) {
+    return false;
+  }
+}
+
+// An export of a module, imported as an ES module or as CommonJS (under `default`).
+function exported(module, name) {
+  if (!module) return undefined;
+  return module[name] || (module.default && module.default[name]);
+}
+
 // The file a module object was loaded from, found in the CommonJS cache.
 function fileOf(exports) {
   for (const module of Object.values(requireHere.cache)) {

package/src/instrumentation/jobs.js

@@ -1,8 +1,12 @@
 /**
  * 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.
  *
  * Libraries that ship separate CommonJS and ES module builds (node-cron, BullMQ) are patched in
  * both: the CommonJS one right away, the ES module one as soon as it is imported here, which is
@@ -17,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.
@@ -91,7 +99,8 @@ export class JobInstrumentation {
     proto.callProcessJob = function (job) {
       const args = arguments;
       const repeat = job && job.opts && job.opts.repeat;
-      const schedule = repeat ? repeat.pattern || repeat.cron || (Number.isFinite(repeat.every) ? `@every ${repeat.every}ms` : undefined) : undefined;
+      const pattern = repeat ? repeat.pattern || repeat.cron : undefined;
+      const schedule = repeat ? pattern || (Number.isFinite(repeat.every) ? `@every ${repeat.every}ms` : undefined) : undefined;
       return JobRunner.run(
         job && job.name && job.name !== '__default__' ? job.name : this.name,
         () => original.apply(this, args),
@@ -100,7 +109,7 @@ export class JobInstrumentation {
           attempt: job && Number.isInteger(job.attemptsMade) ? job.attemptsMade + 1 : 1,
           data: job ? job.data : undefined,
           schedule,
-          timezone: repeat && typeof repeat.tz === 'string' ? repeat.tz : undefined,
+          timezone: repeat && typeof repeat.tz === 'string' && repeat.tz ? repeat.tz : pattern ? localTimeZone() : undefined,
           trigger: schedule ? 'cron' : 'queue'
         }
       );
@@ -109,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.
    *
@@ -146,7 +216,11 @@ function wrapCronTask(task) {
   const name = task.name && task.name !== task.id ? task.name : `cron ${expression || 'task'}`;
   const wrapped = function () {
     const args = arguments;
-    return JobRunner.run(name, () => original.apply(this, args), { schedule: expression || undefined, timezone: task.timezone, trigger: 'cron' });
+    return JobRunner.run(name, () => original.apply(this, args), {
+      schedule: expression || undefined,
+      timezone: (typeof task.timezone === 'string' && task.timezone) || localTimeZone(),
+      trigger: 'cron'
+    });
   };
   wrapped[kWrapped] = true;
   runner.onMatch = wrapped;
@@ -159,7 +233,7 @@ function wrapCronJobCallback(job, callback) {
     const args = arguments;
     return JobRunner.run(job.name || `cron ${source || 'job'}`, () => callback.apply(this, args), {
       schedule: source || undefined,
-      timezone: job.cronTime && typeof job.cronTime.timeZone === 'string' ? job.cronTime.timeZone : undefined,
+      timezone: (job.cronTime && typeof job.cronTime.timeZone === 'string' && job.cronTime.timeZone) || localTimeZone(),
       trigger: 'cron'
     });
   };
@@ -167,6 +241,40 @@ 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 {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || undefined;
+  } catch (error) {
+    return undefined;
+  }
+}
+
 // The file an `import` of the package loads, when it differs from what require() loads.
 function esmEntry(packageDir) {
   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);