peekinside 0.0.0-stage → 1.2.0

package/src/instrumentation/mongodb.js

@@ -0,0 +1,221 @@
+/**
+ * MongoDB driver (5.x and 6.x) operations on the request's timeline, and so Mongoose's (7 and 8).
+ *
+ * The hook is the driver's internal Connection#command, which every operation goes through
+ * (finds, aggregations, writes, cursor batches), whatever API the app used. Commands the driver
+ * sends for itself (handshakes, authentication, session cleanup) are left out.
+ *
+ * Each command becomes a statement such as `orders.find({ customerId: ?, status: { $in: ? } })`:
+ * the collection, the command and the shape of its main argument, without values. The values
+ * themselves (filter, update, documents, pipeline...) are the span's parameters, masked by key.
+ *
+ * In driver 6 the command is async and the request's context follows its promise chain. In driver
+ * 5 it takes a callback, and the pool's wait queue hands connections out from other requests'
+ * callbacks: queued checkOut callbacks are bound to the context they were queued in.
+ */
+
+import { AsyncResource } from 'async_hooks';
+import { Shape } from '../timeline/shape.js';
+import { Timeline } from '../timeline/timeline.js';
+import { Operation } from './operation.js';
+import { ownerOf, patchMethod } from './patch.js';
+
+// Commands the driver runs for itself, never for the app's queries.
+const INTERNAL = new Set([
+  'hello', 'ismaster', 'saslstart', 'saslcontinue', 'authenticate', 'getnonce', 'logout', 'endsessions',
+  'killcursors', 'buildinfo', 'ping', 'getparameter', 'serverstatus', 'connectionstatus', 'getlasterror'
+]);
+// The fields of each command that carry the app's values.
+const VALUE_FIELDS = ['filter', 'query', 'update', 'updates', 'deletes', 'documents', 'pipeline', 'key', 'sort', 'projection', 'limit', 'skip'];
+
+/**
+ * Patches a MongoDB driver.
+ */
+export class MongoInstrumentation {
+  /**
+   * @param {{ Connection: Function, ConnectionPool?: Function }} internals - The driver's internal
+   *   classes (lib/cmap/connection.js, lib/cmap/connection_pool.js)
+   * @returns {boolean} Whether they were recognized and patched
+   */
+  static patch({ Connection, ConnectionPool }) {
+    try {
+      if (typeof Connection !== 'function' || typeof Connection.prototype.command !== 'function') return false;
+      patchCommand(ownerOf(Connection.prototype, 'command'));
+      if (typeof ConnectionPool === 'function') patchPool(ConnectionPool.prototype);
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * The statement text and parameters of a command, or null for the driver's own commands.
+   *
+   * @param {{ db?: string, collection?: string }} ns - The command's namespace
+   * @param {Object} command - The command document, such as { find: 'orders', filter: {...} }
+   * @returns {{ text: string, params: Object|undefined }|null}
+   */
+  static describe(ns, command) {
+    if (!command || typeof command !== 'object') return null;
+    const name = Object.keys(command)[0];
+    if (!name || INTERNAL.has(name.toLowerCase())) return null;
+    const target = command[name];
+    // Database commands go to the "$cmd" collection: they are named after the database.
+    const nsCollection = ns && ns.collection && ns.collection !== '$cmd' ? ns.collection : null;
+    const collection = typeof target === 'string' ? target
+      : typeof command.collection === 'string' ? command.collection
+        : nsCollection || (ns && ns.db) || 'db';
+
+    let shape = '';
+    switch (name) {
+      case 'find':
+        shape = Shape.of(command.filter || {});
+        break;
+      case 'aggregate':
+        shape = Shape.of(command.pipeline || []);
+        break;
+      case 'count':
+      case 'distinct':
+        shape = Shape.of(command.query || {});
+        break;
+      case 'insert':
+        shape = Shape.of(Array.isArray(command.documents) && command.documents.length ? command.documents[0] : {});
+        break;
+      case 'update': {
+        const first = Array.isArray(command.updates) ? command.updates[0] : null;
+        shape = Shape.of({ q: (first && first.q) || {}, u: (first && first.u) || {} });
+        break;
+      }
+      case 'delete': {
+        const first = Array.isArray(command.deletes) ? command.deletes[0] : null;
+        shape = Shape.of((first && first.q) || {});
+        break;
+      }
+      case 'findAndModify':
+        shape = Shape.of({ query: command.query || {}, update: command.update || {} });
+        break;
+      default:
+        break;
+    }
+
+    let params;
+    for (const field of VALUE_FIELDS) {
+      // { update: 'orders', updates: [...] }: the command's own key names the collection.
+      if (field === name || command[field] === undefined) continue;
+      params = params || {};
+      params[field] = command[field];
+    }
+    return { text: `${collection}.${name}(${shape})`, params };
+  }
+}
+
+function patchCommand(owner) {
+  patchMethod(owner, 'command', (original) => {
+    // Driver 6's command is async and its last parameter is a response class (a function too);
+    // driver 5's takes a callback. The method's kind says which, not the argument's type.
+    const callbackStyle = original.constructor.name !== 'AsyncFunction';
+    return commandWrapper(original, callbackStyle);
+  });
+}
+
+function commandWrapper(original, callbackStyle) {
+  return function command(ns, cmd) {
+    const timeline = Timeline.current();
+    if (!timeline || !timeline.settings.captureQueries) return original.apply(this, arguments);
+    let described;
+    try {
+      described = MongoInstrumentation.describe(ns, cmd);
+    } catch (error) {
+      described = null;
+    }
+    if (!described) return original.apply(this, arguments);
+
+    const span = timeline.query({ system: 'mongodb', client: 'mongodb', text: described.text, sql: false, params: described.params, operation: Operation.noteQuery() });
+    if (!span) return original.apply(this, arguments);
+
+    // Driver 5: command(ns, cmd, options, callback)
+    const last = callbackStyle ? arguments[arguments.length - 1] : undefined;
+    let args = arguments;
+    if (typeof last === 'function') {
+      args = Array.prototype.slice.call(arguments);
+      args[args.length - 1] = function (err, reply) {
+        span.end(err ? { error: err } : outcomeOf(reply));
+        return last.apply(this, arguments);
+      };
+    }
+
+    let result;
+    let returned = false;
+    try {
+      result = original.apply(this, args);
+      returned = true;
+    } finally {
+      if (!returned) span.cancel();
+    }
+    // Driver 6: an internal promise the driver awaits; the app never sees it.
+    if (result && typeof result.then === 'function' && typeof last !== 'function') {
+      return result.then(
+        (reply) => {
+          span.end(outcomeOf(reply));
+          return reply;
+        },
+        (error) => {
+          span.end({ error });
+          throw error;
+        }
+      );
+    }
+    return result;
+  };
+}
+
+// Driver 5's pool queues checkOut callbacks; bind them to the context they were queued in.
+function patchPool(proto) {
+  const owner = ownerOf(proto, 'checkOut');
+  if (!owner) return;
+  patchMethod(owner, 'checkOut', (original) => function checkOut(callback) {
+    if (typeof callback === 'function') {
+      const args = Array.prototype.slice.call(arguments);
+      args[0] = AsyncResource.bind(callback);
+      return original.apply(this, args);
+    }
+    return original.apply(this, arguments);
+  });
+}
+
+// What a reply says: documents returned (a cursor's batch) or matched / written (n), and the
+// first write error. A write that hit a duplicate key answers ok: 1 with writeErrors.
+function outcomeOf(reply) {
+  try {
+    if (!reply || typeof reply !== 'object') return {};
+    // Driver 6 cursor replies are read lazily; the batch size is cheap.
+    if (typeof reply.batchSize === 'number') return { rows: reply.batchSize };
+    // Other driver 6 replies are lazy BSON too; write replies are small.
+    const object = typeof reply.toObject === 'function' ? reply.toObject() : reply;
+    const failure = firstWriteError(object);
+    const cursor = object.cursor;
+    let rows = null;
+    if (cursor && typeof cursor === 'object') {
+      const batch = cursor.firstBatch || cursor.nextBatch;
+      if (Array.isArray(batch)) rows = batch.length;
+    } else if (Number.isInteger(object.n)) {
+      rows = object.n;
+    } else if (Array.isArray(object.values)) {
+      rows = object.values.length;
+    } else if ('value' in object) {
+      rows = object.value ? 1 : 0;
+    }
+    return failure ? { rows, error: failure } : { rows };
+  } catch (error) {
+    return {};
+  }
+}
+
+function firstWriteError(reply) {
+  const writeError = Array.isArray(reply.writeErrors) && reply.writeErrors[0];
+  const concernError = reply.writeConcernError;
+  const error = writeError || concernError;
+  if (!error || typeof error !== 'object') return null;
+  const message = String(error.errmsg || error.message || 'write error');
+  return error.code !== undefined ? `${error.code}: ${message}` : message;
+}

package/src/instrumentation/mysql2.js

@@ -0,0 +1,161 @@
+/**
+ * mysql2 (3.x) queries on the request's timeline, including mysql2/promise, which runs on the same
+ * core connections. Knex, Sequelize, TypeORM, Drizzle, Kysely and Prisma's MariaDB/MySQL adapters
+ * send their queries through it.
+ *
+ * - Connection.prototype.query and .execute start the span. The statement is recorded with its
+ *   placeholders and values (mysql2 formats query() values into the SQL client side; the timeline
+ *   keeps them apart, so values can be masked by column).
+ * - The span ends with the callback (mysql2/promise always passes one), or, in streaming mode, with
+ *   the command's 'end' or 'error' event, seen by wrapping the command's emit(): no listener is
+ *   added, so an unhandled 'error' still behaves as it would.
+ * - Pool.getConnection callbacks run in the context they were queued in, and pool.query() /
+ *   pool.execute() read the caller (the pooled query runs from a callback, on a later tick).
+ */
+
+import { AsyncResource } from 'async_hooks';
+import { Caller } from '../timeline/caller.js';
+import { Timeline } from '../timeline/timeline.js';
+import { Operation } from './operation.js';
+import { ownerOf, patchMethod } from './patch.js';
+
+/**
+ * Patches a mysql2 module.
+ */
+export class Mysql2Instrumentation {
+  /**
+   * @param {*} mysql2 - What require('mysql2') returns
+   * @returns {boolean} Whether it was recognized and patched
+   */
+  static patch(mysql2) {
+    try {
+      const Connection = mysql2 && mysql2.Connection;
+      // The core Connection queues commands; mysql2/promise's Connection only wraps one.
+      if (typeof Connection !== 'function' || !Connection.prototype || typeof Connection.prototype.execute !== 'function' || typeof Connection.prototype.addCommand !== 'function') return false;
+      for (const method of ['query', 'execute']) {
+        patchMethod(ownerOf(Connection.prototype, method), method, (original) => function (sql, values, cb) {
+          return run(this, original, arguments);
+        });
+      }
+      if (typeof mysql2.Pool === 'function') patchPool(mysql2.Pool.prototype);
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+}
+
+function run(connection, original, args) {
+  const timeline = Timeline.current();
+  if (!timeline || !timeline.settings.captureQueries) return original.apply(connection, args);
+
+  const sql = args[0];
+  let text;
+  let params;
+  try {
+    if (sql && typeof sql === 'object') {
+      text = sql.sql;
+      params = sql.values !== undefined ? sql.values : typeof args[1] !== 'function' ? args[1] : undefined;
+    } else {
+      text = sql;
+      params = typeof args[1] === 'function' ? undefined : args[1];
+    }
+  } catch (error) {
+    text = undefined;
+  }
+  if (typeof text !== 'string') return original.apply(connection, args);
+
+  const span = timeline.query({ system: 'mysql', client: 'mysql2', text, params, operation: Operation.noteQuery() });
+  if (!span) return original.apply(connection, args);
+
+  const finish = (err, rows) => span.end(err ? { error: err } : { rows: rowsOf(rows) });
+  const callArgs = Array.prototype.slice.call(args);
+  let observed = false;
+  if (sql && typeof sql === 'object' && typeof sql.onResult === 'function') {
+    // A command built elsewhere (pool.query builds it, then hands it to a connection).
+    const onResult = sql.onResult;
+    sql.onResult = function (err, rows, fields) {
+      finish(err, rows);
+      return onResult.apply(this, arguments);
+    };
+    observed = true;
+  } else {
+    for (let i = 1; i < 3 && i < callArgs.length; i++) {
+      if (typeof callArgs[i] !== 'function') continue;
+      const callback = callArgs[i];
+      callArgs[i] = function (err, rows, fields) {
+        finish(err, rows);
+        return callback.apply(this, arguments);
+      };
+      observed = true;
+      break;
+    }
+  }
+
+  let command;
+  let returned = false;
+  try {
+    command = original.apply(connection, callArgs);
+    returned = true;
+  } finally {
+    if (!returned) span.cancel();
+  }
+  if (!observed) observeEvents(command, span);
+  return command;
+}
+
+// Streaming mode: the command emits 'result' per row, then 'end' (or 'error').
+function observeEvents(command, span) {
+  if (!command || typeof command.emit !== 'function') {
+    span.end();
+    return;
+  }
+  const emit = command.emit;
+  let rows = 0;
+  command.emit = function (event, value) {
+    if (event === 'result') rows++;
+    else if (event === 'end') span.end({ rows });
+    else if (event === 'error') span.end({ error: value });
+    return emit.apply(this, arguments);
+  };
+}
+
+function patchPool(proto) {
+  // Bound whatever the caller's context (see the pg integration).
+  patchMethod(ownerOf(proto, 'getConnection'), 'getConnection', (original) => function getConnection(cb) {
+    if (typeof cb === 'function') {
+      return original.call(this, AsyncResource.bind(cb));
+    }
+    return original.apply(this, arguments);
+  });
+  for (const method of ['query', 'execute']) {
+    patchMethod(ownerOf(proto, method), method, (original) => function (sql, values, cb) {
+      const timeline = Timeline.current();
+      if (!timeline || !timeline.settings.captureQueries) return original.apply(this, arguments);
+      let text;
+      try {
+        text = sql && typeof sql === 'object' ? sql.sql : sql;
+      } catch (error) {
+        text = undefined;
+      }
+      if (typeof text !== 'string') return original.apply(this, arguments);
+      const key = Timeline.sqlFingerprint(text, 'mysql');
+      // Inside a Prisma operation, the caller is the line that made the Prisma call, when known.
+      if (!timeline.needsCaller(key) || Operation.caller()) return original.apply(this, arguments);
+      const caller = timeline.settings.caller.capture();
+      const args = arguments;
+      return Caller.withHint({ key, caller }, () => original.apply(this, args));
+    });
+  }
+}
+
+// Rows returned (a SELECT's rows) or affected (a ResultSetHeader's affectedRows).
+function rowsOf(rows) {
+  try {
+    if (Array.isArray(rows)) return rows.length;
+    if (rows && Number.isInteger(rows.affectedRows)) return rows.affectedRows;
+  } catch (error) {
+    // Unreadable: unknown.
+  }
+  return null;
+}

package/src/instrumentation/operation.js

@@ -0,0 +1,70 @@
+/**
+ * The ORM operation the code running now belongs to ("User.findMany"), so the database queries a
+ * Prisma call runs through a driver adapter (pg, mysql2) are recorded with the call that ran them,
+ * and with the app's line that made it: Prisma runs some of them on its own (an include's), where
+ * the app's frame isn't on the stack.
+ */
+
+import { AsyncLocalStorage } from 'async_hooks';
+
+const operations = new AsyncLocalStorage();
+
+/**
+ * Carries the current ORM operation through the async work it causes, and counts the driver
+ * queries recorded for it: an operation whose queries can't be seen (Prisma 6's engine runs its
+ * adapter outside the request's context) is recorded as a whole instead.
+ */
+export class Operation {
+  /**
+   * Runs `fn` as part of `operation`.
+   *
+   * @param {{ name: string, queries: number, caller?: Function|null }} operation - Such as
+   *   { name: "User.findMany", queries: 0 }; `caller`, when the ORM captured its call site,
+   *   returns the app's frame that made the call (a CallerInfo, or null)
+   * @param {Function} fn
+   * @returns {*} What fn returns
+   */
+  static run(operation, fn) {
+    return operations.run(operation, fn);
+  }
+
+  /**
+   * @returns {{ name: string, queries: number }|undefined} The operation the code running now
+   *   belongs to
+   */
+  static current() {
+    return operations.getStore();
+  }
+
+  /**
+   * The app's frame that made the current operation's call, when the ORM captured it (read once
+   * per operation): the queries the operation runs take their caller from it.
+   *
+   * @returns {import('../timeline/caller.js').CallerInfo|null}
+   */
+  static caller() {
+    const operation = operations.getStore();
+    if (!operation || typeof operation.caller !== 'function') return null;
+    if (operation.found === undefined) {
+      try {
+        operation.found = operation.caller() || null;
+      } catch (error) {
+        operation.found = null;
+      }
+    }
+    return operation.found;
+  }
+
+  /**
+   * Notes a driver query recorded for the current operation, and returns the operation's name
+   * for the query's span.
+   *
+   * @returns {string|undefined}
+   */
+  static noteQuery() {
+    const operation = operations.getStore();
+    if (!operation) return undefined;
+    operation.queries++;
+    return operation.name;
+  }
+}

package/src/instrumentation/patch.js

@@ -0,0 +1,72 @@
+/**
+ * Patching library methods without the app noticing.
+ *
+ * A wrapper keeps the original's name and length (some libraries inspect a function's length to
+ * pick a calling convention), is installed once per method and module instance, and calls the
+ * original with the same `this` and arguments.
+ */
+
+// Owner object -> names of its methods this copy of PeekInside has patched.
+const patched = new WeakMap();
+
+/**
+ * Replaces `owner[name]` with `makeWrapper(original)`, once.
+ *
+ * @param {Object} owner - The object that holds the method as an own property (a prototype)
+ * @param {string} name
+ * @param {(original: Function) => Function} makeWrapper
+ * @returns {boolean} Whether the method is patched now (also when it already was)
+ */
+export function patchMethod(owner, name, makeWrapper) {
+  if (!owner || typeof owner[name] !== 'function') return false;
+  let names = patched.get(owner);
+  if (!names) {
+    names = new Set();
+    patched.set(owner, names);
+  }
+  if (names.has(name)) return true;
+
+  const original = owner[name];
+  const wrapper = makeWrapper(original);
+  try {
+    Object.defineProperty(wrapper, 'length', { value: original.length, configurable: true });
+    Object.defineProperty(wrapper, 'name', { value: original.name, configurable: true });
+  } catch (error) {
+    // Cosmetic only.
+  }
+  const descriptor = Object.getOwnPropertyDescriptor(owner, name);
+  Object.defineProperty(owner, name, {
+    value: wrapper,
+    writable: descriptor ? descriptor.writable !== false : true,
+    enumerable: descriptor ? descriptor.enumerable : false,
+    configurable: true
+  });
+  names.add(name);
+  return true;
+}
+
+/**
+ * The object in `target`'s prototype chain that holds `name` as an own property: where a method
+ * has to be patched so every instance (and subclass) sees the wrapper.
+ *
+ * @param {Object} target - Usually a class's prototype
+ * @param {string} name
+ * @returns {Object|null}
+ */
+export function ownerOf(target, name) {
+  for (let current = target; current && current !== Object.prototype; current = Object.getPrototypeOf(current)) {
+    if (Object.prototype.hasOwnProperty.call(current, name)) return current;
+  }
+  return null;
+}
+
+/**
+ * Whether a value is a native promise (not merely a thenable: lazy thenables, such as Prisma's
+ * and Mongoose's queries, run when then() is called).
+ *
+ * @param {*} value
+ * @returns {boolean}
+ */
+export function isNativePromise(value) {
+  return value instanceof Promise;
+}