peekinside 0.0.0-stage → 1.2.1

package/src/runtime/loop-monitor.js

@@ -0,0 +1,162 @@
+/**
+ * Watches the event loop with a light timer that measures how late it fires. A late timer means
+ * the loop was blocked by synchronous work (a large JSON.parse, a slow regular expression, a sync
+ * file read, a CPU-heavy loop), and every request in flight waited for it. Blocks long enough are
+ * recorded on the timelines of those requests (Timeline#block); every delay feeds the process
+ * samples (see RuntimeSampler).
+ *
+ * One monitor serves the whole process. Its timer is unref'd, never keeps the process alive, and
+ * runs outside any request; the work per tick is a subtraction and a write into a fixed buffer.
+ */
+
+import { performance } from 'perf_hooks';
+import { RequestContext } from '../exceptions/request-context.js';
+
+// How often the timer fires: a block is measured within TICK_MS.
+export const TICK_MS = 20;
+// Delays kept for the samples: two minutes of ticks.
+const MAX_DELAYS = Math.ceil(120_000 / TICK_MS);
+// Shorter delays are scheduling noise, never a block worth showing.
+const MIN_BLOCK_MS = 50;
+
+/**
+ * The process's event-loop monitor.
+ */
+export class LoopMonitor {
+  /**
+   * Starts the shared monitor (or counts one more user of it).
+   *
+   * @returns {LoopMonitor}
+   */
+  static acquire() {
+    if (!LoopMonitor.shared) LoopMonitor.shared = new LoopMonitor();
+    LoopMonitor.shared.users++;
+    LoopMonitor.shared.start();
+    return LoopMonitor.shared;
+  }
+
+  /**
+   * One user is done; the monitor stops with the last one.
+   *
+   * @returns {void}
+   */
+  static release() {
+    const monitor = LoopMonitor.shared;
+    if (!monitor) return;
+    monitor.users = Math.max(0, monitor.users - 1);
+    if (monitor.users === 0) monitor.stop();
+  }
+
+  /**
+   * Follows a timeline until it is untracked: blocks that happen meanwhile are recorded on it.
+   * Does nothing while no monitor runs.
+   *
+   * @param {{ block: (start: number, duration: number) => void }} timeline
+   * @returns {void}
+   */
+  static track(timeline) {
+    if (LoopMonitor.shared && LoopMonitor.shared.timer) LoopMonitor.shared.timelines.add(timeline);
+  }
+
+  /**
+   * @param {Object} timeline
+   * @returns {void}
+   */
+  static untrack(timeline) {
+    if (LoopMonitor.shared) LoopMonitor.shared.timelines.delete(timeline);
+  }
+
+  /**
+   * The block in progress, if the timer is late right now: a request that blocked the loop itself
+   * often finishes before the timer can fire, and asks when its timeline closes.
+   *
+   * @param {number} [now=performance.now()]
+   * @returns {{ start: number, duration: number }|null}
+   */
+  static pending(now = performance.now()) {
+    const monitor = LoopMonitor.shared;
+    if (!monitor || !monitor.timer) return null;
+    const due = monitor.last + TICK_MS;
+    return now - due >= MIN_BLOCK_MS ? { start: due, duration: now - due } : null;
+  }
+
+  constructor() {
+    this.users = 0;
+    this.timer = null;
+    this.last = 0;
+    this.timelines = new Set();
+    // Ring buffer of (performance.now(), delay ms) per tick.
+    this.times = new Float64Array(MAX_DELAYS);
+    this.delays = new Float64Array(MAX_DELAYS);
+    this.next = 0;
+    this.size = 0;
+  }
+
+  /**
+   * @returns {void}
+   */
+  start() {
+    if (this.timer) return;
+    this.last = performance.now();
+    this.timer = RequestContext.outside(() => setInterval(() => this.tick(), TICK_MS));
+    if (typeof this.timer.unref === 'function') this.timer.unref();
+  }
+
+  /**
+   * @returns {void}
+   */
+  stop() {
+    clearInterval(this.timer);
+    this.timer = null;
+    this.timelines.clear();
+  }
+
+  /**
+   * One tick of the timer: how late it fired is how long the loop was blocked.
+   *
+   * @param {number} [now=performance.now()]
+   * @returns {void}
+   */
+  tick(now = performance.now()) {
+    const delay = Math.max(0, now - this.last - TICK_MS);
+    this.last = now;
+    this.times[this.next] = now;
+    this.delays[this.next] = delay;
+    this.next = (this.next + 1) % MAX_DELAYS;
+    this.size = Math.min(MAX_DELAYS, this.size + 1);
+    if (delay < MIN_BLOCK_MS) return;
+    // The loop was blocked from when the tick was due until now.
+    for (const timeline of this.timelines) {
+      try {
+        timeline.block(now - delay, delay);
+      } catch (error) {
+        // One timeline's failure never affects the others.
+      }
+    }
+  }
+
+  /**
+   * The event-loop delay since a moment: its median, 99th percentile and maximum, in ms.
+   *
+   * @param {number} since - performance.now() at the start of the window
+   * @returns {{ p50: number, p99: number, max: number }|null} null without ticks in the window
+   */
+  delaySince(since) {
+    const window = [];
+    for (let i = 0; i < this.size; i++) {
+      const index = (this.next - 1 - i + MAX_DELAYS) % MAX_DELAYS;
+      if (this.times[index] < since) break;
+      window.push(this.delays[index]);
+    }
+    if (!window.length) return null;
+    window.sort((a, b) => a - b);
+    const at = (fraction) => window[Math.min(window.length - 1, Math.floor(fraction * window.length))];
+    return { p50: round(at(0.5)), p99: round(at(0.99)), max: round(window[window.length - 1]) };
+  }
+}
+
+LoopMonitor.shared = null;
+
+function round(value) {
+  return Math.round(value * 10) / 10;
+}

package/src/runtime/sampler.js

@@ -0,0 +1,93 @@
+/**
+ * Samples the process now and then: memory (to spot leaks, as growth over hours), CPU and the
+ * event-loop delay. Samples are numbers only, and go to the dashboard with the other records:
+ * every 10 seconds to the local dashboard, every minute to PeekInside Cloud.
+ */
+
+import { performance } from 'perf_hooks';
+import { RequestContext } from '../exceptions/request-context.js';
+
+/**
+ * @typedef {Object} RuntimeSample
+ * @property {number} at - When it was taken (ms since the epoch)
+ * @property {number} rss - Bytes of memory the process holds
+ * @property {number} heapUsed - Bytes of JavaScript objects
+ * @property {number} heapTotal - Bytes of the JavaScript heap
+ * @property {number} external - Bytes of memory outside the heap (buffers)
+ * @property {number} cpu - Percent of one core used since the last sample
+ * @property {number|null} loopP50 - Event-loop delay since the last sample, ms
+ * @property {number|null} loopP99
+ * @property {number|null} loopMax
+ */
+
+/**
+ * Takes a sample every `intervalMs` and hands it over.
+ */
+export class RuntimeSampler {
+  /**
+   * @param {Object} options
+   * @param {number} options.intervalMs
+   * @param {(sample: RuntimeSample) => void} options.onSample
+   * @param {import('./loop-monitor.js').LoopMonitor} options.monitor - Measures the delay
+   */
+  constructor({ intervalMs, onSample, monitor }) {
+    this.intervalMs = intervalMs;
+    this.onSample = onSample;
+    this.monitor = monitor;
+    this.timer = null;
+    this.lastAt = performance.now();
+    this.lastCpu = process.cpuUsage();
+  }
+
+  /**
+   * @returns {this}
+   */
+  start() {
+    if (this.timer) return this;
+    this.lastAt = performance.now();
+    this.lastCpu = process.cpuUsage();
+    this.timer = RequestContext.outside(() => setInterval(() => this.take(), this.intervalMs));
+    if (typeof this.timer.unref === 'function') this.timer.unref();
+    return this;
+  }
+
+  /**
+   * @returns {void}
+   */
+  stop() {
+    clearInterval(this.timer);
+    this.timer = null;
+  }
+
+  /**
+   * Takes a sample now and hands it over. Never throws.
+   *
+   * @returns {RuntimeSample|null}
+   */
+  take() {
+    try {
+      const now = performance.now();
+      const elapsed = Math.max(1, now - this.lastAt);
+      const cpu = process.cpuUsage(this.lastCpu);
+      const delay = this.monitor ? this.monitor.delaySince(this.lastAt) : null;
+      this.lastAt = now;
+      this.lastCpu = process.cpuUsage();
+      const memory = process.memoryUsage();
+      const sample = {
+        at: Date.now(),
+        rss: memory.rss,
+        heapUsed: memory.heapUsed,
+        heapTotal: memory.heapTotal,
+        external: memory.external,
+        cpu: Math.round(((cpu.user + cpu.system) / 1000 / elapsed) * 1000) / 10,
+        loopP50: delay ? delay.p50 : null,
+        loopP99: delay ? delay.p99 : null,
+        loopMax: delay ? delay.max : null
+      };
+      this.onSample(sample);
+      return sample;
+    } catch (error) {
+      return null;
+    }
+  }
+}

package/src/spool.js

@@ -0,0 +1,195 @@
+/**
+ * Spool folders: records written to disk by a process that may exit at any moment (it is
+ * crashing), for someone else to deliver later.
+ *
+ *   <data dir>/spool/<project id>/<uuid>.json         Local hub batches ({ project, instance,
+ *                                                     requests, exceptions }), which the hub
+ *                                                     ingests at startup and every second
+ *   <data dir>/spool/cloud/<project id>/<uuid>.json   Sealed PeekInside Cloud batches, which the
+ *                                                     SDK resends when the app starts again
+ *
+ * Writing is synchronous and atomic (a temporary file, then a rename), so a reader never sees half
+ * a file. Folders are private to the user (0700, files 0600), like the rest of the data folder.
+ */
+
+import { randomUUID } from 'crypto';
+import fs from 'fs';
+import path from 'path';
+
+// The "project" folder that holds cloud batches; local project ids always contain a dash.
+export const CLOUD_FOLDER = 'cloud';
+// A temporary file this old was left by a writer that died mid-write.
+const STALE_TEMP_MS = 60_000;
+
+/**
+ * One spool folder.
+ */
+export class Spool {
+  /**
+   * The folder of a local hub project.
+   *
+   * @param {string} dataDir
+   * @param {string} projectId
+   * @returns {Spool}
+   */
+  static local(dataDir, projectId) {
+    return new Spool(path.join(Spool.root(dataDir), projectId));
+  }
+
+  /**
+   * The folder of a PeekInside Cloud project.
+   *
+   * @param {string} dataDir
+   * @param {string} projectId
+   * @returns {Spool}
+   */
+  static cloud(dataDir, projectId) {
+    return new Spool(path.join(Spool.root(dataDir), CLOUD_FOLDER, projectId));
+  }
+
+  /**
+   * @param {string} dataDir
+   * @returns {string} The folder that holds every spool folder
+   */
+  static root(dataDir) {
+    return path.join(dataDir, 'spool');
+  }
+
+  /**
+   * @param {string} dir
+   */
+  constructor(dir) {
+    this.dir = dir;
+  }
+
+  /**
+   * Writes one file, synchronously.
+   *
+   * @param {*} content - Saved as JSON
+   * @returns {string} The file's name
+   * @throws {Error} When the folder can't be written (callers decide whether that matters)
+   */
+  write(content) {
+    fs.mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+    const name = `${randomUUID()}.json`;
+    const file = path.join(this.dir, name);
+    const temp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(temp, JSON.stringify(content), { mode: 0o600 });
+    fs.renameSync(temp, file);
+    return name;
+  }
+
+  /**
+   * The files waiting, oldest first. Files older than `maxAgeMs` are deleted instead, as are
+   * temporary files left by writers that died.
+   *
+   * @param {Object} [options]
+   * @param {number} [options.maxAgeMs=Infinity]
+   * @returns {string[]} File names
+   */
+  list({ maxAgeMs = Infinity } = {}) {
+    let names;
+    try {
+      names = fs.readdirSync(this.dir);
+    } catch (error) {
+      return [];
+    }
+
+    const now = Date.now();
+    const files = [];
+    for (const name of names) {
+      const file = path.join(this.dir, name);
+      let stat;
+      try {
+        stat = fs.statSync(file);
+      } catch (error) {
+        continue;
+      }
+      if (!stat.isFile()) continue;
+
+      if (name.endsWith('.tmp')) {
+        if (now - stat.mtimeMs > STALE_TEMP_MS) fs.rmSync(file, { force: true });
+        continue;
+      }
+      const claimed = /^(.+\.json)\.(\d+)\.sending$/.exec(name);
+      if (claimed) {
+        // A process that died while sending: the file is up for grabs again.
+        if (!isRunning(Number(claimed[2])) && this._rename(name, claimed[1])) files.push({ name: claimed[1], at: stat.mtimeMs });
+        continue;
+      }
+      if (!name.endsWith('.json')) continue;
+      if (now - stat.mtimeMs > maxAgeMs) {
+        fs.rmSync(file, { force: true });
+        continue;
+      }
+      files.push({ name, at: stat.mtimeMs });
+    }
+    return files.sort((a, b) => a.at - b.at).map((entry) => entry.name);
+  }
+
+  /**
+   * Reads a file.
+   *
+   * @param {string} name
+   * @returns {*} The parsed content, or undefined when it is missing or not JSON
+   */
+  read(name) {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(this.dir, name), 'utf8'));
+    } catch (error) {
+      return undefined;
+    }
+  }
+
+  /**
+   * Deletes a file.
+   *
+   * @param {string} name
+   * @returns {void}
+   */
+  remove(name) {
+    fs.rmSync(path.join(this.dir, name), { force: true });
+  }
+
+  /**
+   * Claims a file for this process, so that processes starting together (cluster workers) don't
+   * send it twice: the rename succeeds for one of them only.
+   *
+   * @param {string} name - From list()
+   * @returns {string|null} The claimed file's name, or null when another process has it
+   */
+  claim(name) {
+    const claimed = `${name}.${process.pid}.sending`;
+    return this._rename(name, claimed) ? claimed : null;
+  }
+
+  /**
+   * Gives a claimed file back, to be sent another time.
+   *
+   * @param {string} claimed - From claim()
+   * @returns {void}
+   */
+  release(claimed) {
+    this._rename(claimed, claimed.replace(/\.\d+\.sending$/, ''));
+  }
+
+  _rename(from, to) {
+    try {
+      fs.renameSync(path.join(this.dir, from), path.join(this.dir, to));
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+}
+
+// A process that exists but belongs to another user (EPERM) is running too.
+function isRunning(pid) {
+  if (pid === process.pid) return true;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === 'EPERM';
+  }
+}

package/src/timeline/caller.js

@@ -0,0 +1,129 @@
+/**
+ * Where the app ran a query: the first frame of the app's own code on the stack.
+ *
+ * Read once per statement and request, at its first execution, so an N+1 loop of a thousand
+ * queries reads the stack once. The stack is read with a higher Error.stackTraceLimit for that
+ * moment only: drivers sit several frames deep between the app and the point where they are
+ * hooked.
+ *
+ * Some calls reach the hooked method after the app's frame is gone: a pool runs the query from a
+ * callback on a later tick. For those, the integration reads the caller where the app called the
+ * pool and hands it down as a hint (AsyncLocalStorage), checked against the statement it was taken
+ * for.
+ */
+
+import { AsyncLocalStorage } from 'async_hooks';
+import { fileURLToPath } from 'url';
+import { FrameClassifier } from '../exceptions/frame-classifier.js';
+import { StackParser } from '../exceptions/stack-parser.js';
+
+const STACK_LIMIT = 25;
+// PeekInside's own files are never the caller, even when they are inside the project (PeekInside's
+// own tests, a checkout used through npm link).
+const SDK_DIR = fileURLToPath(new URL('../', import.meta.url));
+const hints = new AsyncLocalStorage();
+
+/**
+ * @typedef {Object} CallerInfo
+ * @property {string} file - Absolute path
+ * @property {string|null} relativeFile - Relative to the project folder, forward slashes
+ * @property {number|null} line
+ * @property {number|null} column
+ * @property {string|null} function
+ */
+
+/**
+ * Finds the app's frame for statements.
+ */
+export class Caller {
+  /**
+   * @param {string} root - The project folder
+   */
+  constructor(root) {
+    this.classifier = new FrameClassifier(root);
+  }
+
+  /**
+   * The app's frame on the current stack.
+   *
+   * @returns {CallerInfo|null}
+   */
+  capture() {
+    const saved = Error.stackTraceLimit;
+    const holder = {};
+    try {
+      Error.stackTraceLimit = STACK_LIMIT;
+      Error.captureStackTrace(holder, Caller.prototype.capture);
+    } catch (error) {
+      return null;
+    } finally {
+      Error.stackTraceLimit = saved;
+    }
+    try {
+      return this.fromStack(holder.stack);
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * The app's frame in a stack captured elsewhere (by Prisma, for one).
+   *
+   * @param {string} stack
+   * @returns {CallerInfo|null}
+   */
+  fromStack(stack) {
+    if (typeof stack !== 'string') return null;
+    for (const parsed of StackParser.parse(stack, { limit: STACK_LIMIT })) {
+      if (!parsed.file || parsed.file.startsWith(SDK_DIR)) continue;
+      const frame = this.classifier.classify(parsed);
+      if (frame.inApp) return Caller.fromFrame(frame);
+    }
+    return null;
+  }
+
+  /**
+   * A caller from a file position (Prisma's own call site format).
+   *
+   * @param {{ fileName: string, lineNumber?: number, columnNumber?: number }} location
+   * @returns {CallerInfo|null}
+   */
+  fromLocation(location) {
+    if (!location || typeof location.fileName !== 'string') return null;
+    const parsed = StackParser.parseLocation(`${location.fileName}:${location.lineNumber ?? 0}:${location.columnNumber ?? 0}`);
+    if (!parsed.file || parsed.file.startsWith(SDK_DIR)) return null;
+    const frame = this.classifier.classify({ function: null, ...parsed, async: false });
+    return frame.inApp ? Caller.fromFrame(frame) : null;
+  }
+
+  /**
+   * @param {import('../exceptions/frame-classifier.js').Frame} frame
+   * @returns {CallerInfo}
+   */
+  static fromFrame(frame) {
+    return { file: frame.file, relativeFile: frame.relativeFile, line: frame.line, column: frame.column, function: frame.function };
+  }
+
+  /**
+   * Runs `fn` with a caller hint for the statement `key`: code that runs the statement later (from
+   * a pool's callback) finds it with Caller.hinted().
+   *
+   * @param {{ key: string, caller: CallerInfo|null }} hint
+   * @param {Function} fn
+   * @returns {*} What fn returns
+   */
+  static withHint(hint, fn) {
+    return hints.run(hint, fn);
+  }
+
+  /**
+   * The hint for statement `key`, if one was given.
+   *
+   * @param {string} key
+   * @returns {{ caller: CallerInfo|null }|null}
+   */
+  static hinted(key) {
+    const hint = hints.getStore();
+    return hint && hint.key === key ? hint : null;
+  }
+}

package/src/timeline/execution-hash.js

@@ -0,0 +1,110 @@
+/**
+ * Recognizes repeated executions: the same statement with the same parameters, run again in the
+ * same request (the result was already there, the app asked again).
+ *
+ * The parameters are compared through a hash of the unmasked values, so two executions that differ
+ * only in a masked value still differ, and the values themselves are never kept.
+ */
+
+import { createHash } from 'crypto';
+import { types } from 'util';
+
+const MAX_DEPTH = 10;
+// Values larger than this (an insertMany of thousands of documents) aren't compared: hashing them
+// would cost more than the duplicate it might reveal is worth.
+const MAX_NODES = 2000;
+const TOO_LARGE = new Error('too large to compare');
+
+/**
+ * Hashes executions.
+ */
+export class ExecutionHash {
+  /**
+   * @param {string} text - The statement as sent
+   * @param {*} params - Its parameters, as the app passed them
+   * @returns {string} A short hash: equal for equal text and parameters
+   */
+  static of(text, params) {
+    const hash = createHash('sha1');
+    hash.update(String(text));
+    hash.update('\u0000');
+    try {
+      feed(hash, params, 0, [], { nodes: 0 });
+    } catch (error) {
+      // Too large, or a value that can't be read (a proxy, a throwing getter): this execution is
+      // its own.
+      hash.update(`\u0001${Math.random()}`);
+    }
+    return hash.digest('base64').slice(0, 16);
+  }
+}
+
+// Writes a value into the hash with type tags, so 1 and "1" differ, and Buffers go in as bytes.
+function feed(hash, value, depth, ancestors, budget) {
+  if (++budget.nodes > MAX_NODES) throw TOO_LARGE;
+  if (value === null || value === undefined) {
+    hash.update(value === null ? 'n;' : 'u;');
+    return;
+  }
+  switch (typeof value) {
+    case 'string':
+      hash.update(`s${value.length}:`);
+      hash.update(value);
+      return;
+    case 'number':
+    case 'boolean':
+    case 'bigint':
+      hash.update(`${typeof value}:${String(value)};`);
+      return;
+    case 'function':
+    case 'symbol':
+      hash.update(`${typeof value};`);
+      return;
+    default:
+      break;
+  }
+  if (ArrayBuffer.isView(value)) {
+    hash.update(`b${value.byteLength}:`);
+    hash.update(new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
+    return;
+  }
+  if (types.isAnyArrayBuffer(value)) {
+    hash.update(`b${value.byteLength}:`);
+    hash.update(new Uint8Array(value));
+    return;
+  }
+  if (types.isDate(value)) {
+    hash.update(`d${Date.prototype.getTime.call(value)};`);
+    return;
+  }
+  if (depth >= MAX_DEPTH || ancestors.includes(value)) {
+    hash.update('…;');
+    return;
+  }
+  ancestors.push(value);
+  try {
+    if (Array.isArray(value)) {
+      hash.update(`a${value.length}[`);
+      for (const item of value) feed(hash, item, depth + 1, ancestors, budget);
+      hash.update(']');
+      return;
+    }
+    // Driver values (ObjectId, Decimal) compare by what they serialize to.
+    if (typeof value.toJSON === 'function' && Object.getPrototypeOf(value) !== Object.prototype) {
+      const json = value.toJSON();
+      if (json !== value) {
+        hash.update('j');
+        feed(hash, json, depth + 1, ancestors, budget);
+        return;
+      }
+    }
+    hash.update('o{');
+    for (const key of Object.keys(value)) {
+      hash.update(`${key.length}:${key}=`);
+      feed(hash, value[key], depth + 1, ancestors, budget);
+    }
+    hash.update('}');
+  } finally {
+    ancestors.pop();
+  }
+}