peekinside 1.2.4 → 1.3.0

package/src/exceptions/exception-record.js

@@ -62,7 +62,9 @@ export class ExceptionRecord {
 
   /**
    * The sealed form, for PeekInside Cloud: the summary and the detail are encrypted, bound to this
-   * exception's id so they can't be swapped with another record's.
+   * exception's id so they can't be swapped with another record's. The fingerprint (a hash of the
+   * error's name and where it was thrown, see fingerprint.js) goes alongside: it tells Cloud a new
+   * error from a known one, for alerts, without saying what either is.
    *
    * @param {import('../crypto.js').Sealer} sealer - Sealer of the batch
    * @returns {Promise<Object>}
@@ -71,6 +73,7 @@ export class ExceptionRecord {
     const { summary, detail, ...meta } = this.toJSON();
     return {
       ...meta,
+      ...this._fingerprint(),
       summary: await sealer.seal(JSON.stringify(summary), ExceptionRecord.summaryAad(this.id)),
       detail: await sealer.seal(JSON.stringify(detail), ExceptionRecord.detailAad(this.id))
     };
@@ -86,11 +89,18 @@ export class ExceptionRecord {
     const { summary, detail, ...meta } = this.toJSON();
     return {
       ...meta,
+      ...this._fingerprint(),
       summary: sealer.seal(JSON.stringify(summary), ExceptionRecord.summaryAad(this.id)),
       detail: sealer.seal(JSON.stringify(detail), ExceptionRecord.detailAad(this.id))
     };
   }
 
+  // The fingerprint field of the sealed form; none when there isn't a valid one.
+  _fingerprint() {
+    const fingerprint = this.summary?.fingerprint;
+    return typeof fingerprint === 'string' && /^[0-9a-f]{16}$/.test(fingerprint) ? { fingerprint } : {};
+  }
+
   /**
    * How the record of the request it happened in lists it, so the request inspector can link to it.
    *

package/src/exceptions/request-context.js

@@ -14,15 +14,24 @@
  * The context also keeps the request's exception bookkeeping: which errors were already recorded
  * (each error object is recorded once per request), the records whose outcome is still open (see
  * ExceptionCapture), and the count and links that go into the request's record.
+ *
+ * Integrations that know what the framework matched the request to note it here (noteRoute()):
+ * the route pattern, the code that handles it and the route parameters. The request's record and
+ * its exceptions carry them.
  */
 
 import { AsyncLocalStorage } from 'async_hooks';
 import { BodyDecoder } from '../capture/body-decoder.js';
-import { parseQuery, splitUrl } from '../capture/http-message.js';
-import { LIMITS } from './limits.js';
+import { parseQuery, splitUrl, stringParams } from '../capture/http-message.js';
+import { LIMITS, truncate } from './limits.js';
 
 const storage = new AsyncLocalStorage();
 const kContext = Symbol('peekInside.context');
+// What a route pattern and a handler name may take up.
+const MAX_ROUTE = 512;
+const MAX_HANDLER = 256;
+// Dumps listed in a request's record (the Dumps page has them all).
+const MAX_DUMP_LINKS = 20;
 // The request an exception last escaped from, until the current job ends.
 let escaped = null;
 
@@ -83,7 +92,7 @@ export class RequestContext {
    * @param {boolean} [fields.blocked=false] - The request reached a server in local mode: neither
    *   it nor its exceptions are recorded
    * @param {string} [fields.integration='custom'] - Where tracking started: "express", "koa",
-   *   "fastify", "http" (a server's emit()) or "custom" (intercept())
+   *   "fastify", "nest", "hono", "http" (a server's emit()) or "custom" (intercept())
    */
   constructor({ capture, req, recorder = null, target, blocked = false, integration = 'custom' }) {
     this.capture = capture;
@@ -119,8 +128,26 @@ export class RequestContext {
      * @type {import('../user.js').User|null}
      */
     this.user = null;
+    /**
+     * The route pattern the framework matched ("/users/:id"), once an integration noted it
+     * @type {string|null}
+     */
+    this.route = null;
+    /**
+     * The code that handles the request ("UsersController.findOne"), once an integration noted it
+     * @type {string|null}
+     */
+    this.handler = null;
+    /**
+     * Dumps made during the request (PeekInside.dump()), for its record
+     * @type {{ id: string, label: string|null, type: string, preview: string }[]}
+     */
+    this.dumps = [];
 
     this._req = req;
+    // Route parameters an integration noted (or a function returning them), for frameworks that
+    // don't put them on the Node.js request.
+    this._params = undefined;
     // What remains for exceptions after the request finished (see release()).
     this._after = null;
 
@@ -169,12 +196,81 @@ export class RequestContext {
   }
 
   /**
-   * For the exception list: the request's method and path.
+   * Notes what the framework matched the request to, as an integration learns it. Each part that is
+   * given replaces the one noted before; null forgets it, and parts left out stay as they are.
+   *
+   * @param {Object} match
+   * @param {string|null} [match.route] - The route pattern, such as "/users/:id"
+   * @param {string|null} [match.handler] - The code that handles it, such as "UsersController.findOne"
+   * @param {Object|(() => Object)|null} [match.params] - The route parameters, or a function that
+   *   returns them when they are needed, for frameworks that keep them off the Node.js request
+   * @returns {void}
+   */
+  noteRoute({ route, handler, params } = {}) {
+    if (route !== undefined) this.route = typeof route === 'string' && route ? truncate(route, MAX_ROUTE) : null;
+    if (handler !== undefined) this.handler = typeof handler === 'string' && handler ? truncate(handler, MAX_HANDLER) : null;
+    if (params !== undefined) this._params = params;
+  }
+
+  /**
+   * The route parameters an integration noted, as strings.
+   *
+   * @returns {Object<string, string>|null} null when none were noted
+   */
+  routeParams() {
+    let params = this._params;
+    if (typeof params === 'function') {
+      try {
+        params = params();
+      } catch (error) {
+        params = null;
+      }
+    }
+    return params && typeof params === 'object' ? stringParams(params) : null;
+  }
+
+  /**
+   * For the exception list: the request's method and path, and its route and handler when known.
    *
-   * @returns {{ method: string, path: string }}
+   * @returns {{ method: string, path: string, route?: string, handler?: string }}
    */
   requestLine() {
-    return { method: this.method, path: this.path };
+    return {
+      method: this.method,
+      path: this.path,
+      ...(this.route ? { route: this.route } : {}),
+      ...(this.handler ? { handler: this.handler } : {})
+    };
+  }
+
+  /**
+   * Counts a dump made during the request: listed on its record, and placed on its timeline.
+   *
+   * @param {import('../dumps/dump-record.js').DumpRecord} record
+   * @returns {void}
+   */
+  noteDump(record) {
+    if (this.dumps.length < MAX_DUMP_LINKS) this.dumps.push(record.link());
+    if (this.timeline) this.timeline.dump(record);
+  }
+
+  /**
+   * Adds what the request's record shows of the request beyond the exchange itself: who it was for,
+   * its route and handler, the dumps made during it, and route parameters the Node.js request
+   * didn't carry.
+   *
+   * @param {import('../capture/exchange-recorder.js').Exchange} exchange - Changed in place
+   * @returns {void}
+   */
+  describe(exchange) {
+    if (this.user) exchange.user = this.user;
+    if (this.route) exchange.route = this.route;
+    if (this.handler) exchange.handler = this.handler;
+    if (this.dumps.length) exchange.dumps = this.dumps.slice();
+    if (this._params !== undefined && (!exchange.params || !Object.keys(exchange.params).length)) {
+      const params = this.routeParams();
+      if (params) exchange.params = params;
+    }
   }
 
   /**
@@ -185,9 +281,11 @@ export class RequestContext {
    */
   snapshot() {
     if (this.recorder && !this.recorder.recorded) {
-      return { id: this.requestId, ...this.recorder.snapshot(LIMITS.requestBody) };
+      const snapshot = { id: this.requestId, ...this.recorder.snapshot(LIMITS.requestBody) };
+      if (this._params !== undefined && !Object.keys(snapshot.params).length) snapshot.params = this.routeParams() || {};
+      return snapshot;
     }
-    const after = this._after || RequestSnapshot.partsOf(this._req);
+    const after = this._after || this._parts();
     return {
       id: this.requestId,
       method: this.method,
@@ -223,7 +321,7 @@ export class RequestContext {
   complete(exchange) {
     if (this.capture) this.capture.finish(this, exchange);
     this.completeTimeline(exchange);
-    if (this.user) exchange.user = this.user;
+    this.describe(exchange);
     this.release();
   }
 
@@ -253,11 +351,21 @@ export class RequestContext {
    */
   release() {
     this.finished = true;
-    this._after = RequestSnapshot.partsOf(this._req);
+    this._after = this._parts();
+    // A function returning the parameters may hold the framework's request.
+    if (typeof this._params === 'function') this._params = this.routeParams();
     this._req = null;
     this.recorder = null;
     this.timeline = null;
   }
+
+  // The small parts of the request a snapshot keeps, with the parameters an integration noted when
+  // the request has none of its own.
+  _parts() {
+    const parts = RequestSnapshot.partsOf(this._req);
+    if (this._params !== undefined && !Object.keys(parts.params).length) parts.params = this.routeParams() || {};
+    return parts;
+  }
 }
 
 /**

package/src/hub/ingest-payload.js

@@ -13,9 +13,10 @@ import { PROJECT_ID } from './store.js';
 export const MAX_BATCH = 1000;
 // Exceptions per batch.
 export const MAX_EXCEPTIONS_BATCH = 500;
-// Job runs and log lines per batch.
+// Job runs, log lines and dumps per batch.
 export const MAX_JOBS_BATCH = 1000;
 export const MAX_LOGS_BATCH = 2000;
+export const MAX_DUMPS_BATCH = 1000;
 // Request ids are UUIDs in practice. They appear in URLs and index files, so only safe
 // characters are accepted.
 export const REQUEST_ID = /^[A-Za-z0-9_-]{1,64}$/;
@@ -27,19 +28,38 @@ const FINGERPRINT = /^[0-9a-f]{16}$/;
 const STAT_KEYS = ['queries', 'queryTime', 'slowQueries', 'nPlusOne', 'duplicates', 'http', 'httpTime', 'logs', 'loopBlock'];
 const STAT_TIMES = new Set(['queryTime', 'httpTime', 'loopBlock']);
 const MAX_STAT = 1e9;
-const MECHANISMS = new Set(['express', 'koa', 'fastify', 'http', 'uncaught', 'unhandledRejection', 'report', 'job']);
+const MECHANISMS = new Set(['express', 'koa', 'fastify', 'nest', 'hono', 'http', 'uncaught', 'unhandledRejection', 'report', 'job']);
 const JOB_STATUSES = new Set(['ok', 'failed']);
 const JOB_TRIGGERS = new Set(['cron', 'queue', 'manual']);
 const LOG_LEVELS = new Set(['debug', 'info', 'warn', 'error']);
-const LOG_SOURCES = new Set(['console', 'pino', 'winston']);
+const LOG_SOURCES = new Set(['console', 'pino', 'winston', 'nest']);
+// What the SDK keeps of a route pattern and a handler name.
+const MAX_ROUTE = 512;
+const MAX_HANDLER = 256;
 // What the index keeps of a log line; the line in full is its detail.
 const LOG_PREVIEW = 500;
+// What the index keeps of a dump: its label, the type and a one-line preview of its value.
+const DUMP_LABEL = 120;
+const DUMP_TYPE = 64;
+const DUMP_PREVIEW = 200;
 // What release.js produces.
 const RELEASE = /^[A-Za-z0-9._:@/+-]{1,64}$/;
 // Process samples per batch (the SDK sends one every 10 seconds, more after the hub was down).
 const MAX_SAMPLES = 120;
 const SAMPLE_BYTES = ['rss', 'heapUsed', 'heapTotal', 'external'];
 const SAMPLE_DELAYS = ['loopP50', 'loopP99', 'loopMax'];
+// Later additions, each optional (older SDKs don't send them): the field, and its largest value.
+const SAMPLE_EXTRAS = [
+  ['arrayBuffers', 1e13],
+  ['heapLimit', 1e13],
+  ['elu', 100],
+  ['gcCount', 1e7],
+  ['gcMs', 1e7],
+  ['gcMax', 1e7],
+  ['handles', 1e7],
+  ['requests', 1e9],
+  ['inFlight', 1e7]
+];
 
 /**
  * A validated ingest batch: `{ project, instance, requests, exceptions, samples, blocked }`.
@@ -65,10 +85,14 @@ export class IngestPayload {
     }
     const jobs = body.jobs != null ? body.jobs : [];
     const logs = body.logs != null ? body.logs : [];
+    const dumps = body.dumps != null ? body.dumps : [];
     if (!Array.isArray(jobs) || jobs.length > MAX_JOBS_BATCH || !Array.isArray(logs) || logs.length > MAX_LOGS_BATCH) {
       return null;
     }
-    return new IngestPayload({ project, instance, requests, exceptions, jobs, logs, samples: body.samples, blocked: body.blocked, hasExceptions: Array.isArray(body.exceptions) });
+    if (!Array.isArray(dumps) || dumps.length > MAX_DUMPS_BATCH) {
+      return null;
+    }
+    return new IngestPayload({ project, instance, requests, exceptions, jobs, logs, dumps, samples: body.samples, blocked: body.blocked, hasExceptions: Array.isArray(body.exceptions) });
   }
 
   /**
@@ -81,12 +105,13 @@ export class IngestPayload {
    * @param {Array} [parts.exceptions] - Exception records as sent
    * @param {Array} [parts.jobs] - Job runs as sent
    * @param {Array} [parts.logs] - Log lines as sent
+   * @param {Array} [parts.dumps] - Dumps as sent
    * @param {*} [parts.samples] - Process samples (memory, CPU, event-loop delay), as sent
    * @param {*} parts.blocked - Counts of unrecorded server requests, as sent
    * @param {boolean} [parts.hasExceptions=false] - Whether the batch had an exception list (SDKs
    *   from before exceptions don't send one)
    */
-  constructor({ project, instance, requests, exceptions = [], jobs = [], logs = [], samples, blocked, hasExceptions = false }) {
+  constructor({ project, instance, requests, exceptions = [], jobs = [], logs = [], dumps = [], samples, blocked, hasExceptions = false }) {
     this.project = project;
     this.instance = instance;
     /**
@@ -127,6 +152,12 @@ export class IngestPayload {
     this.logs = logs.map(readLog).filter(Boolean);
     this.rejectedJobs = jobs.length - this.jobs.length;
     this.rejectedLogs = logs.length - this.logs.length;
+    /**
+     * The valid dumps, flattened into what the store keeps (the value's tree is the detail)
+     * @type {Object[]}
+     */
+    this.dumps = dumps.map(readDump).filter(Boolean);
+    this.rejectedDumps = dumps.length - this.dumps.length;
     /**
      * The valid counts of server requests the SDK didn't record
      * @type {{ kind: 'host'|'client', value: string, count: number }[]}
@@ -184,6 +215,8 @@ function readRecord(value) {
     url: text(summary.url, 16384),
     path: text(summary.path, 16384),
     contentType: text(summary.contentType, 256),
+    route: text(summary.route, MAX_ROUTE) || null,
+    handler: text(summary.handler, MAX_HANDLER) || null,
     user: readUser(summary.user),
     detail
   };
@@ -287,6 +320,43 @@ function readLog(value) {
   };
 }
 
+// A dump: its fields, the start of its value for the list, and the value's tree as its detail. The
+// tree is the dashboard's to read; the hub only keeps it.
+function readDump(value) {
+  if (!value || typeof value !== 'object') return null;
+  if (typeof value.id !== 'string' || !REQUEST_ID.test(value.id) || !Number.isFinite(value.occurredAt)) return null;
+  if (!optionalId(value.requestId) || !optionalId(value.jobRunId)) return null;
+  const summary = value.summary && typeof value.summary === 'object' ? value.summary : {};
+  const detail = value.detail && typeof value.detail === 'object' && !Array.isArray(value.detail) ? value.detail : {};
+  const tree = detail.value && typeof detail.value === 'object' && !Array.isArray(detail.value) && typeof detail.value.t === 'string' ? detail.value : { t: 'undef' };
+  return {
+    id: value.id,
+    occurredAt: value.occurredAt,
+    environment: text(value.environment, 32) || 'development',
+    release: release(value.release),
+    requestId: value.requestId || null,
+    jobRunId: value.jobRunId || null,
+    label: text(value.label, DUMP_LABEL) || null,
+    location: readCaller(value.location),
+    type: text(summary.type, DUMP_TYPE) || 'value',
+    preview: text(summary.preview, DUMP_PREVIEW),
+    truncated: summary.truncated === true,
+    detail: { value: tree }
+  };
+}
+
+// Where in the app something happened: an absolute file, the same relative to the project, a line.
+function readCaller(value) {
+  if (!value || typeof value !== 'object' || typeof value.file !== 'string' || !value.file) return null;
+  return {
+    file: value.file.slice(0, 4096),
+    relativeFile: typeof value.relativeFile === 'string' ? value.relativeFile.slice(0, 4096) : null,
+    line: positiveInt(value.line),
+    column: positiveInt(value.column),
+    function: typeof value.function === 'string' ? value.function.slice(0, 1024) : null
+  };
+}
+
 function optionalId(value) {
   return value === null || value === undefined || (typeof value === 'string' && REQUEST_ID.test(value));
 }
@@ -307,6 +377,10 @@ function readSamples(value) {
       const number = sample[key];
       clean[key] = Number.isFinite(number) && number >= 0 && number <= 1e7 ? number : null;
     }
+    for (const [key, max] of SAMPLE_EXTRAS) {
+      const number = sample[key];
+      clean[key] = Number.isFinite(number) && number >= 0 && number <= max ? number : null;
+    }
     return [clean];
   });
 }
@@ -324,13 +398,20 @@ function readLocation(value) {
 // Who a request or exception was for: short strings only, null when it names nobody.
 function readUser(value) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
-  const user = { id: text(value.id, 128) || null, email: text(value.email, 254) || null, name: text(value.name, 128) || null };
-  return user.id || user.email || user.name ? user : null;
+  const user = {
+    id: text(value.id, 128) || null,
+    email: text(value.email, 254) || null,
+    name: text(value.name, 128) || null,
+    phone: text(value.phone, 32) || null
+  };
+  return user.id || user.email || user.name || user.phone ? user : null;
 }
 
 function readRequestLine(value) {
   if (!value || typeof value !== 'object' || typeof value.method !== 'string' || typeof value.path !== 'string') return null;
-  return { method: value.method.slice(0, 16), path: value.path.slice(0, 16384) };
+  const route = text(value.route, MAX_ROUTE);
+  const handler = text(value.handler, MAX_HANDLER);
+  return { method: value.method.slice(0, 16), path: value.path.slice(0, 16384), ...(route ? { route } : {}), ...(handler ? { handler } : {}) };
 }
 
 function positiveInt(value) {

package/src/hub/project-log.js

@@ -8,6 +8,7 @@
  *   exception-state.json     fingerprints the dashboard marked resolved
  *   jobs/00000001.*          job runs, in the same format
  *   logs/00000001.*          log lines: the index keeps the start of each line, the details the rest
+ *   dumps/00000001.*         dumps: the index keeps a preview of each value, the details its tree
  *
  * Process samples (memory, CPU, event-loop delay) are kept in memory only, for the Runtime page:
  * the last six hours of each of the project's recent processes.
@@ -33,13 +34,15 @@ const MAX_BLOCKED_ENTRIES = 10;
 const MAX_RUNTIME_SAMPLES = 2160;
 const MAX_RUNTIME_PROCESSES = 8;
 // Fields a summary may contain, in the order they are written.
-const SUMMARY_FIELDS = ['seq', 'id', 'occurredAt', 'environment', 'release', 'method', 'status', 'duration', 'requestSize', 'responseSize', 'aborted', 'exceptionCount', 'stats', 'url', 'path', 'contentType', 'user'];
+const SUMMARY_FIELDS = ['seq', 'id', 'occurredAt', 'environment', 'release', 'method', 'status', 'duration', 'requestSize', 'responseSize', 'aborted', 'exceptionCount', 'stats', 'url', 'path', 'contentType', 'route', 'handler', 'user'];
 const EXCEPTION_FIELDS = ['seq', 'id', 'occurredAt', 'environment', 'release', 'handled', 'fatal', 'requestId', 'jobRunId', 'name', 'message', 'code', 'fingerprint', 'mechanism', 'location', 'request', 'job', 'user'];
 const JOB_FIELDS = ['seq', 'id', 'occurredAt', 'environment', 'release', 'name', 'queue', 'schedule', 'timezone', 'trigger', 'status', 'duration', 'attempt', 'exceptionCount', 'stats', 'error', 'user'];
 const LOG_FIELDS = ['seq', 'id', 'occurredAt', 'environment', 'release', 'level', 'source', 'requestId', 'jobRunId', 'message'];
+const DUMP_FIELDS = ['seq', 'id', 'occurredAt', 'environment', 'release', 'requestId', 'jobRunId', 'label', 'location', 'type', 'preview', 'truncated'];
 const EXCEPTIONS_FOLDER = 'exceptions';
 const JOBS_FOLDER = 'jobs';
 const LOGS_FOLDER = 'logs';
+const DUMPS_FOLDER = 'dumps';
 
 /**
  * @typedef {Object} ProjectInfo
@@ -71,7 +74,8 @@ export class ProjectLog {
    * @param {number} limits.exceptionSegmentSize - Exceptions per segment file
    * @param {number} limits.maxJobs - Job runs kept
    * @param {number} limits.maxLogs - Log lines kept
-   * @param {{ requests?: SegmentLog, exceptions?: SegmentLog, jobs?: SegmentLog, logs?: SegmentLog }} [logs] - Logs
+   * @param {number} limits.maxDumps - Dumps kept
+   * @param {{ requests?: SegmentLog, exceptions?: SegmentLog, jobs?: SegmentLog, logs?: SegmentLog, dumps?: SegmentLog }} [logs] - Logs
    *   read from disk
    */
   constructor(dir, info, limits, logs = {}) {
@@ -82,6 +86,7 @@ export class ProjectLog {
     this.exceptions = logs.exceptions || new SegmentLog(path.join(dir, EXCEPTIONS_FOLDER), ProjectLog._exceptionOptions(info, limits));
     this.jobs = logs.jobs || new SegmentLog(path.join(dir, JOBS_FOLDER), ProjectLog._jobOptions(info, limits));
     this.logs = logs.logs || new SegmentLog(path.join(dir, LOGS_FOLDER), ProjectLog._logOptions(info, limits));
+    this.dumps = logs.dumps || new SegmentLog(path.join(dir, DUMPS_FOLDER), ProjectLog._dumpOptions(info, limits));
     this.exceptionState = new ExceptionState(dir);
     // Processes running the project, by pid. In memory only: they check in again after a restart.
     this.instances = new Map();
@@ -111,7 +116,8 @@ export class ProjectLog {
       seqBase: 1,
       exceptionSeqBase: 1,
       jobSeqBase: 1,
-      logSeqBase: 1
+      logSeqBase: 1,
+      dumpSeqBase: 1
     }, limits);
     project.save();
     return project;
@@ -138,13 +144,15 @@ export class ProjectLog {
       exceptionSeqBase: Number(saved.exceptionSeqBase) || 1,
       jobSeqBase: Number(saved.jobSeqBase) || 1,
       logSeqBase: Number(saved.logSeqBase) || 1,
+      dumpSeqBase: Number(saved.dumpSeqBase) || 1,
       ...(isBlockedInfo(saved.blocked) ? { blocked: saved.blocked } : {})
     };
     return new ProjectLog(dir, info, limits, {
       requests: SegmentLog.load(dir, ProjectLog._requestOptions(info, limits)),
       exceptions: SegmentLog.load(path.join(dir, EXCEPTIONS_FOLDER), ProjectLog._exceptionOptions(info, limits)),
       jobs: SegmentLog.load(path.join(dir, JOBS_FOLDER), ProjectLog._jobOptions(info, limits)),
-      logs: SegmentLog.load(path.join(dir, LOGS_FOLDER), ProjectLog._logOptions(info, limits))
+      logs: SegmentLog.load(path.join(dir, LOGS_FOLDER), ProjectLog._logOptions(info, limits)),
+      dumps: SegmentLog.load(path.join(dir, DUMPS_FOLDER), ProjectLog._dumpOptions(info, limits))
     });
   }
 
@@ -416,6 +424,48 @@ export class ProjectLog {
     this.save();
   }
 
+  /**
+   * Stores new dumps; ones already stored (same id) are skipped.
+   *
+   * @param {Object[]} records - Validated dumps, with their detail (the value's tree)
+   * @returns {Object[]}
+   */
+  appendDumps(records) {
+    return this.dumps.append(records);
+  }
+
+  /**
+   * Dump summaries, newest first; oldest first when `after` is given.
+   *
+   * @param {{ after?: number, before?: number, limit: number }} query
+   * @returns {{ dumps: Object[], hasMore: boolean }}
+   */
+  listDumps(query) {
+    const { entries, hasMore } = this.dumps.list(query);
+    return { dumps: entries, hasMore };
+  }
+
+  /**
+   * One dump's value (its tree).
+   *
+   * @param {string} dumpId
+   * @returns {Object|null}
+   */
+  dumpDetail(dumpId) {
+    return this.dumps.detail(dumpId);
+  }
+
+  /**
+   * Deletes all dumps.
+   *
+   * @returns {void}
+   */
+  clearDumps() {
+    this.dumps.clear();
+    this.info.dumpSeqBase = this.dumps.seqBase;
+    this.save();
+  }
+
   /**
    * Deletes the project's folder.
    *
@@ -444,6 +494,7 @@ export class ProjectLog {
     const newest = this.requests.newest;
     const newestException = this.exceptions.newest;
     const newestJob = this.jobs.newest;
+    const newestDump = this.dumps.newest;
     return {
       id: this.info.id,
       name: this.info.name,
@@ -457,6 +508,8 @@ export class ProjectLog {
       jobCount: this.jobs.size,
       lastJobAt: newestJob ? newestJob.occurredAt : null,
       logCount: this.logs.size,
+      dumpCount: this.dumps.size,
+      lastDumpAt: newestDump ? newestDump.occurredAt : null,
       online: instances.length > 0,
       instances,
       blocked: this.info.blocked && now - this.info.blocked.lastAt < BLOCKED_NOTICE_MS ? this.info.blocked : null
@@ -495,6 +548,7 @@ export class ProjectLog {
     this.exceptions.enforceRetention();
     this.jobs.enforceRetention();
     this.logs.enforceRetention();
+    this.dumps.enforceRetention();
   }
 
   static _requestOptions(info, limits) {
@@ -509,6 +563,10 @@ export class ProjectLog {
     return { maxEntries: limits.maxLogs, segmentSize: Math.max(10, Math.ceil(limits.maxLogs / 4)), seqBase: info.logSeqBase || 1, pick: pickLog };
   }
 
+  static _dumpOptions(info, limits) {
+    return { maxEntries: limits.maxDumps, segmentSize: Math.max(10, Math.ceil(limits.maxDumps / 4)), seqBase: info.dumpSeqBase || 1, pick: pickDump };
+  }
+
   static _exceptionOptions(info, limits) {
     return {
       maxEntries: limits.maxExceptions,
@@ -533,6 +591,9 @@ function pickSummary(source) {
   // Stored before releases (or users) were recorded.
   if (summary.release === undefined) summary.release = null;
   if (summary.user === undefined) summary.user = null;
+  // Stored before route patterns were recorded, or from a framework that doesn't name them.
+  if (summary.route === undefined) summary.route = null;
+  if (summary.handler === undefined) summary.handler = null;
   return summary;
 }
 
@@ -552,6 +613,12 @@ function pickJob(source) {
   return summary;
 }
 
+function pickDump(source) {
+  const summary = {};
+  for (const field of DUMP_FIELDS) summary[field] = source[field] === undefined ? null : source[field];
+  return summary;
+}
+
 function pickLog(source) {
   const summary = {};
   for (const field of LOG_FIELDS) summary[field] = source[field] === undefined ? null : source[field];

package/src/hub/server.js

@@ -1,8 +1,8 @@
 /**
  * The local hub's HTTP server, on 127.0.0.1 only.
  *
- *   GET    /                                   Dashboard page (also /p/<project id>,
- *                                              /p/<project id>/exceptions and /p/<project id>/queries)
+ *   GET    /                                   Dashboard page (also /p/<project id>, and its
+ *                                              /exceptions, /routes, /queries, /logs, /jobs, /dumps and /runtime)
  *   POST   /api/ingest                         Requests and exceptions from the SDK in each app, and
  *                                              counts of server requests it didn't record (free plan)
  *   GET    /api/status                         Hub version and settings
@@ -20,6 +20,9 @@
  *   GET    /api/projects/:id/logs              Log lines (their start), paged like requests
  *   GET    /api/projects/:id/logs/:lid         One log line in full
  *   DELETE /api/projects/:id/logs              Delete a project's log lines
+ *   GET    /api/projects/:id/dumps             Dumps (a preview of each value), paged like requests
+ *   GET    /api/projects/:id/dumps/:did        One dump's value
+ *   DELETE /api/projects/:id/dumps             Delete a project's dumps
  *   GET    /api/projects/:id/exception-state   Resolved issues, with a version
  *   PUT    /api/projects/:id/exception-state   Save them, if the version is still the current one
  *   DELETE /api/projects/:id                   Forget a project
@@ -38,7 +41,7 @@ import { readFileSync } from 'fs';
 import { HUB_API_VERSION, HUB_APP_ID } from '../config.js';
 import { ExceptionState } from './exception-state.js';
 import { IngestPayload, REQUEST_ID } from './ingest-payload.js';
-import { PROJECT_ID } from './store.js';
+import { DEFAULT_MAX_DUMPS, PROJECT_ID } from './store.js';
 
 const MAX_INGEST_BYTES = 32 * 1024 * 1024;
 // 5000 fingerprints with their timestamps take about 200 KB.
@@ -46,9 +49,9 @@ const MAX_STATE_BYTES = 1024 * 1024;
 const DEFAULT_PAGE = 500;
 const MAX_PAGE = 1000;
 // /api/projects/:id, then optionally a collection and an item.
-const PROJECT_ROUTE = /^\/api\/projects\/([^/]+)(?:\/(requests|exceptions|exception-state|runtime|jobs|logs)(?:\/([^/]+))?)?$/;
+const PROJECT_ROUTE = /^\/api\/projects\/([^/]+)(?:\/(requests|exceptions|exception-state|runtime|jobs|logs|dumps)(?:\/([^/]+))?)?$/;
 // The dashboard page: the project list, a project's requests, its exceptions and its queries.
-const SHELL_ROUTE = /^\/p\/[a-z0-9-]{1,64}(?:\/(?:exceptions|queries|runtime|logs|jobs))?\/?$/;
+const SHELL_ROUTE = /^\/p\/[a-z0-9-]{1,64}(?:\/(?:exceptions|routes|queries|runtime|logs|jobs|dumps))?\/?$/;
 
 const BASE_HEADERS = {
   'X-Content-Type-Options': 'nosniff',
@@ -150,7 +153,9 @@ export class HubServer {
       dataDir: this.dataDir,
       siteUrl: this.siteUrl,
       maxRequests: this.store.maxRequests,
-      maxExceptions: this.store.maxExceptions
+      maxExceptions: this.store.maxExceptions,
+      // Also tells the dashboard this hub keeps dumps (older ones don't).
+      maxDumps: DEFAULT_MAX_DUMPS
     };
   }
 
@@ -243,6 +248,7 @@ export class HubServer {
     this.store.addSamples(payload.project.id, payload.instance, payload.samples);
     const addedJobs = this.store.appendJobs(payload.project.id, payload.jobs);
     const addedLogs = this.store.appendLogs(payload.project.id, payload.logs);
+    const addedDumps = this.store.appendDumps(payload.project.id, payload.dumps);
     // SDKs from before exceptions get the answer they know.
     return sendJson(res, 200, payload.hasExceptions
       ? {
@@ -251,9 +257,10 @@ export class HubServer {
         acceptedExceptions: addedExceptions.length,
         rejectedExceptions: payload.rejectedExceptions,
         acceptedJobs: addedJobs.length,
-        acceptedLogs: addedLogs.length
+        acceptedLogs: addedLogs.length,
+        acceptedDumps: addedDumps.length
       }
-      : { accepted: added.length, rejected: payload.rejected, acceptedJobs: addedJobs.length, acceptedLogs: addedLogs.length });
+      : { accepted: added.length, rejected: payload.rejected, acceptedJobs: addedJobs.length, acceptedLogs: addedLogs.length, acceptedDumps: addedDumps.length });
   }
 
   // Every /api/ route except ingest; the caller has checked the origin.
@@ -299,6 +306,10 @@ export class HubServer {
       if (item !== undefined) return this._item(req, res, decode(item), (id) => this.store.logDetail(projectId, id), 'This log line is no longer stored.');
       return this._collection(req, res, query, () => this.store.listLogs(projectId, pageOf(query)), () => this.store.clearLogs(projectId));
     }
+    if (collection === 'dumps') {
+      if (item !== undefined) return this._item(req, res, decode(item), (id) => this.store.dumpDetail(projectId, id), 'This dump is no longer stored.');
+      return this._collection(req, res, query, () => this.store.listDumps(projectId, pageOf(query)), () => this.store.clearDumps(projectId));
+    }
     if (collection === 'runtime') {
       if (item !== undefined) return sendJson(res, 404, { error: 'Not found' });
       return read ? sendJson(res, 200, this.store.runtime(projectId)) : methodNotAllowed(res, 'GET, HEAD');