@forge-ops/tracker 0.12.0 → 0.14.0

package/README.md

@@ -429,8 +429,8 @@ server-side and dropped, exactly like any other delivery failure.
 
 For one slow or errored request, `forgeOpsTrackerTracingExpressMiddleware` (Express) and
 `registerForgeOpsTrackerTracing()` (Fastify, `./integrations/tracing`) capture its full nested
-call tree: the route span, plus every outbound HTTP call and manually-wrapped span nested under
-it, so ForgeOps can render a waterfall for that one request.
+call tree: the route span, plus every outbound HTTP call, database query, Redis command and
+manually-wrapped span nested under it, so ForgeOps can render a waterfall for that one request.
 
 ```js
 import { forgeOpsTrackerTracingExpressMiddleware } from "@forge-ops/tracker/integrations/tracing";
@@ -539,10 +539,115 @@ app.use(forgeOpsTrackerExpressMiddleware);
 app.listen(3000);
 ```
 
-**Known gaps:** no database span capture (this SDK has no existing query/ORM instrumentation hook
-of any kind yet to extend) and no Redis span capture (no existing Redis hook or dependency exists
-here either); a database call or Redis call inside a traced request just won't show up as its own
-span for now.
+### Database spans
+
+Queries run through [`pg`](https://node-postgres.com) (node-postgres) are captured automatically,
+one `"database"` span per query, with no extra setup: `init()` finds `pg` in your app and wraps
+`Client#query`, which `Pool#query` goes through too. Callbacks, promises, and config objects
+(`{ text, values, name }`) are all covered.
+
+```js
+import pg from "pg";
+
+const pool = new pg.Pool();
+
+app.get("/orders", async (req, res) => {
+  // Recorded as a "SELECT orders" span, nested under this request's route span.
+  const { rows } = await pool.query(
+    "SELECT id, total FROM orders WHERE customer_id = $1 AND status = 'open'",
+    [req.user.id],
+  );
+  res.json(rows);
+});
+```
+
+The span is named after the statement's verb and table (`"SELECT orders"`, `"INSERT INTO orders"`,
+`"UPDATE orders"`, `"DELETE sessions"`, or just the first keyword, like `"BEGIN"`), never the SQL
+itself. It carries the statement in its data as `db.statement`, masked before it's stored: every
+string and number becomes `?`, so the query above is sent as
+`SELECT id, total FROM orders WHERE customer_id = $1 AND status = ?`, and ForgeOps masks it again
+on arrival. It's cut to 4000 characters. Bind values (the `[req.user.id]` array) are never read or
+sent. `db.system` is `"postgresql"`. A failed query is recorded too, and its error reaches your
+code exactly as before.
+
+For any other database library, wrap a query by hand with `kind: "database"` and pass the SQL as
+`statement`; it's masked the same way:
+
+```js
+import mysql from "mysql2/promise";
+import * as forgeOpsTracker from "@forge-ops/tracker";
+
+const connection = await mysql.createConnection(process.env.DATABASE_URL);
+
+app.get("/orders", async (req, res) => {
+  const sql = "SELECT id, total FROM orders WHERE customer_id = ? AND status = 'open'";
+  const [rows] = await forgeOpsTracker.span("Load open orders", () => connection.execute(sql, [req.user.id]), {
+    kind: "database",
+    statement: sql,
+    dbSystem: "mysql",
+  });
+  res.json(rows);
+});
+```
+
+`dbSystem` is optional (`"postgresql"`, `"mysql"`, `"sqlite"`, `"mssql"`, `"oracle"`, or any other
+lowercase name) and both options are ignored on spans of any other kind. They go out in the span's
+data as `db.statement` and `db.system`. A hand-made span around a `pg` query still works: the
+automatic query span just nests under it.
+
+### Redis spans
+
+Commands sent through [`ioredis`](https://github.com/redis/ioredis) or
+[`redis`](https://github.com/redis/node-redis) (node-redis) are captured automatically too, one
+`"redis"` span per command, pipelined ones included:
+
+```js
+import Redis from "ioredis";
+
+const redis = new Redis(process.env.REDIS_URL);
+
+app.get("/cart", async (req, res) => {
+  // Recorded as a "Redis GET" span.
+  const cart = await redis.get(`cart:${req.user.id}`);
+  res.json(JSON.parse(cart ?? "[]"));
+});
+```
+
+A span is named after the command alone (`"Redis GET"`, `"Redis SET"`, `"Redis LPUSH"`) and
+carries no data: never the key or any other argument, since a key can easily hold a user's id or
+another sensitive value. A failed command is recorded too. `ioredis` is covered from version 4 on;
+`redis` from 5.12 on (with Node 18.19 or later), through the diagnostics channel it publishes every
+command on, so nothing in it is patched.
+
+### When `init()` can't find `pg` or `ioredis`
+
+`init()` looks for `pg` and `ioredis` from the directory your app was started in, and from where
+this package is installed. Neither is a dependency of this package: one your app doesn't have is
+simply skipped. If your app is bundled, or started from a directory its `node_modules` isn't
+under, hand the module over yourself, once, at startup:
+
+```js
+import pg from "pg";
+import Redis from "ioredis";
+import * as forgeOpsTracker from "@forge-ops/tracker";
+
+forgeOpsTracker.init({ dsn: "..." });
+forgeOpsTracker.instrumentPg(pg);
+forgeOpsTracker.instrumentIoredis(Redis);
+```
+
+Both are safe to call more than once, and return `false` when given something that isn't `pg` or
+an `ioredis` class. `redis` never needs this.
+
+**Known gaps:**
+
+- `redis` (node-redis) before 5.12 (all of 4.x, and 5.0 to 5.11) publishes nothing to listen to,
+  so its commands don't show up as spans. Upgrade, or wrap the calls you care about with
+  `span(name, fn, { kind: "redis" })`.
+- `pg-native` (`pg.native`), and cursors and streams passed to `query()` (`pg-cursor`,
+  `pg-query-stream`), aren't captured.
+- Other database libraries (`mysql2`, `better-sqlite3`, Prisma, and so on) aren't captured
+  automatically; wrap their queries with `span()` as shown above.
 
 ## Database errors
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forge-ops/tracker",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "ForgeOps error tracking client: captures unhandled exceptions (Express/Fastify integration, plus explicit capture anywhere else) and delivers them to ForgeOps over HTTP.",
   "type": "module",
   "main": "src/index.js",
@@ -46,6 +46,9 @@
     "@eslint/js": "^10.0.0",
     "eslint": "^10.0.0",
     "express": "^5.0.0",
-    "fastify": "^5.0.0"
+    "fastify": "^5.0.0",
+    "ioredis": "^6.0.0",
+    "pg": "^8.23.0",
+    "redis": "^6.2.1"
   }
 }

package/src/databaseTracing.js

@@ -0,0 +1,196 @@
+import { AsyncResource } from "node:async_hooks";
+import { requireOptional } from "./optionalModules.js";
+import { mask } from "./sqlStatement.js";
+
+const WRAPPED = Symbol("forgeOpsTrackerWrapped");
+
+let installed = false;
+// Every patch made, so _uninstallDatabaseTracing can put each method back exactly as found.
+const patches = [];
+
+/**
+ * Records one "database" span per query run through node-postgres (pg), for any app that has it
+ * installed; installed from index.js's init() the same way installHttpTracing is, exactly once
+ * for the life of the process (see the installed guard), and checking whether a trace is being
+ * captured fresh on every query rather than at install time. An app without pg gets nothing
+ * patched and nothing loaded (see requireOptional).
+ *
+ * Wraps pg.Client.prototype.query, which pg.Pool's own query() also goes through, so a pooled
+ * query is covered with no separate hook. Every calling style is handled: a callback (as the last
+ * argument, or on a config object's own `callback`), a returned promise, and a string or config
+ * object ({ text, values, name, ... }). A submittable (pg-cursor, pg-query-stream, or a raw
+ * pg.Query) is passed straight through unrecorded: it has no single "done" moment this could
+ * observe without adding an "error" listener, which would change what an unhandled stream error
+ * does in the host app.
+ *
+ * The span is named "<VERB> <table>" (see queryName) and carries the statement masked by
+ * sqlStatement.js's mask() as data["db.statement"] (every string and number replaced by "?", the
+ * same masking span({ statement }) and gems/forge_ops_tracker's database spans apply) and
+ * "postgresql" as data["db.system"]. Bind values are never read.
+ *
+ * @param {(name: string, kind: string, startedAt: Date, durationMs: number, data?: Record<string, unknown>) => void} recordSpan
+ * @param {() => boolean} isTracing whether the current async context has a trace to record into
+ */
+export function installDatabaseTracing(recordSpan, isTracing) {
+  if (installed) {
+    return;
+  }
+  installed = true;
+  for (const pg of requireOptional("pg")) {
+    instrumentPg(pg, recordSpan, isTracing);
+  }
+}
+
+/**
+ * Patches one pg module (what `import pg from "pg"` returns). Safe to call more than once for the
+ * same module: a method this already wrapped is left alone.
+ *
+ * Also binds a callback passed to pg.Pool#connect to the async context it was called from, while a
+ * trace is being captured. When every pooled client is busy, pg-pool queues the request and later
+ * hands it a client from inside whichever other request released one, so without this, a query
+ * run on that client would be recorded into the wrong request's trace.
+ *
+ * @param {any} pg
+ * @param {Parameters<typeof installDatabaseTracing>[0]} recordSpan
+ * @param {() => boolean} isTracing
+ * @returns {boolean} whether there was a pg Client to patch
+ */
+export function instrumentPg(pg, recordSpan, isTracing) {
+  const clientPrototype = pg?.Client?.prototype;
+  if (typeof clientPrototype?.query !== "function") {
+    return false;
+  }
+  patch(clientPrototype, "query", (original) => wrapQuery(original, recordSpan, isTracing));
+
+  const poolPrototype = pg.Pool?.prototype;
+  if (typeof poolPrototype?.connect === "function") {
+    patch(poolPrototype, "connect", (original) => wrapConnect(original, isTracing));
+  }
+  return true;
+}
+
+/** @internal test-only: restores every method installDatabaseTracing/instrumentPg replaced. */
+export function _uninstallDatabaseTracing() {
+  while (patches.length > 0) {
+    const { target, key, original, own } = patches.pop();
+    if (own) {
+      target[key] = original;
+    } else {
+      delete target[key];
+    }
+  }
+  installed = false;
+}
+
+function patch(target, key, wrapper) {
+  const original = target[key];
+  if (original[WRAPPED]) {
+    return;
+  }
+  const wrapped = wrapper(original);
+  wrapped[WRAPPED] = true;
+  patches.push({ target, key, original, own: Object.prototype.hasOwnProperty.call(target, key) });
+  target[key] = wrapped;
+}
+
+function wrapQuery(originalQuery, recordSpan, isTracing) {
+  return function patchedQuery(config, values, callback) {
+    if (config == null || typeof config.submit === "function" || !isTracing()) {
+      return originalQuery.apply(this, arguments);
+    }
+
+    const statement = typeof config === "string" ? config : config.text;
+    const masked = typeof statement === "string" ? mask(statement) : null;
+    const startedAt = new Date();
+    const start = performance.now();
+
+    // Bound to the caller's async context now: pg calls back (and settles its promise) from its
+    // socket's own event handlers, where the trace this query belongs to isn't the current one.
+    let finished = false;
+    const finish = AsyncResource.bind(() => {
+      if (finished) {
+        return;
+      }
+      finished = true;
+      const data = { "db.system": "postgresql" };
+      if (masked !== null) {
+        data["db.statement"] = masked;
+      }
+      recordSpan(queryName(masked), "database", startedAt, performance.now() - start, data);
+    });
+
+    const args = [...arguments];
+    const callbackIndex = typeof callback === "function" ? 2 : typeof values === "function" ? 1 : -1;
+    if (callbackIndex !== -1) {
+      args[callbackIndex] = withFinish(args[callbackIndex], finish);
+      return originalQuery.apply(this, args);
+    }
+    if (typeof config === "object" && typeof config.callback === "function") {
+      // A new object inheriting from the caller's, with only `callback` replaced: pg reads the
+      // rest (text, values, name, rowMode...) through it unchanged, getters included.
+      args[0] = Object.create(config, {
+        callback: { value: withFinish(config.callback, finish), writable: true, enumerable: true, configurable: true },
+      });
+      return originalQuery.apply(this, args);
+    }
+
+    const result = originalQuery.apply(this, args);
+    if (!result || typeof result.then !== "function") {
+      return result;
+    }
+    // The promise returned in pg's place settles exactly like pg's own, so a rejection the app
+    // never handles is still reported as unhandled, the same as without this wrapper.
+    return result.then(
+      (value) => {
+        finish();
+        return value;
+      },
+      (error) => {
+        finish();
+        throw error;
+      },
+    );
+  };
+}
+
+function withFinish(callback, finish) {
+  return function queryCallback(...args) {
+    finish();
+    return callback.apply(this, args);
+  };
+}
+
+function wrapConnect(originalConnect, isTracing) {
+  return function patchedConnect(callback, ...rest) {
+    if (typeof callback === "function" && isTracing()) {
+      return originalConnect.call(this, AsyncResource.bind(callback), ...rest);
+    }
+    return originalConnect.apply(this, arguments);
+  };
+}
+
+const SELECT_DELETE = /^\s*(SELECT|DELETE)\b[\s\S]*?\bFROM\s+["'`]?(\w+)/i;
+const INSERT_UPDATE = /^\s*(INSERT INTO|UPDATE)\s+["'`]?(\w+)/i;
+
+/**
+ * A low-cardinality span name for a query, never the SQL text itself: "<VERB> <table>" for the
+ * shapes that carry a table in a predictable place ("SELECT orders", "INSERT INTO orders",
+ * "UPDATE orders", "DELETE sessions"), just the first keyword otherwise ("BEGIN", "SELECT" for
+ * "SELECT 1"), and "SQL" for a blank or missing statement. A direct port of the Python SDK's
+ * _query_transaction_name (and the Elixir SDK's QueryNaming), so the same query gets the same name
+ * in every SDK. Given the masked statement, so a quoted value can never become part of a name.
+ *
+ * @param {string | null | undefined} sql
+ * @returns {string}
+ */
+export function queryName(sql) {
+  if (typeof sql !== "string") {
+    return "SQL";
+  }
+  const match = SELECT_DELETE.exec(sql) ?? INSERT_UPDATE.exec(sql);
+  if (match) {
+    return `${match[1].toUpperCase()} ${match[2]}`;
+  }
+  const first = sql.trim().split(/\s+/, 1)[0];
+  return first ? first.toUpperCase() : "SQL";
+}

package/src/index.js

@@ -3,15 +3,18 @@ import { BreadcrumbBuffer } from "./breadcrumbBuffer.js";
 import { buildChange, buildSnapshot } from "./changes.js";
 import { Client } from "./client.js";
 import { Configuration } from "./configuration.js";
+import { installDatabaseTracing, instrumentPg as instrumentPgModule, _uninstallDatabaseTracing } from "./databaseTracing.js";
 import { DeliveryQueue } from "./deliveryQueue.js";
 import { EventBuilder } from "./eventBuilder.js";
 import { installHttpTracing, _uninstallHttpTracing } from "./httpTracing.js";
 import { MetricBuffer } from "./metricBuffer.js";
 import { PerformanceFlusher } from "./performanceFlusher.js";
+import { installRedisTracing, instrumentIoredis as instrumentIoredisClass, _uninstallRedisTracing } from "./redisTracing.js";
 import { Reporter } from "./reporter.js";
 import { requestStateFor } from "./requestState.js";
 import { SessionFlusher } from "./sessionFlusher.js";
 import { randomSpanId, SpanBuffer } from "./spanBuffer.js";
+import { mask as maskSql } from "./sqlStatement.js";
 import { buildTraceparent } from "./traceParent.js";
 
 export { Configuration };
@@ -434,11 +437,11 @@ export function _finishSpanTrace(name, startedAt, durationMs) {
 
 /**
  * Internal; called by whatever this client already automatically times end-to-end with no
- * children of its own to nest anything under (currently just the outbound HTTP wrapper; see
- * httpTracing.js), never by host app code directly. A no-op, the same as every other automatic
- * source, when there's no request-level trace currently open at all (trackTracing off, or
- * genuinely outside any request the tracing integration ever wrapped): never fabricates a trace
- * with no request to belong to.
+ * children of its own to nest anything under (the outbound HTTP wrapper in httpTracing.js, and the
+ * pg, ioredis and node-redis wrappers in databaseTracing.js and redisTracing.js), never by host
+ * app code directly. A no-op, the same as every other automatic source, when there's no
+ * request-level trace currently open at all (trackTracing off, or genuinely outside any request
+ * the tracing integration ever wrapped): never fabricates a trace with no request to belong to.
  *
  * @param {string} name
  * @param {string} kind
@@ -458,6 +461,49 @@ export function _recordSpan(name, kind, startedAt, durationMs, data = {}, spanId
   buffer.record({ spanId, parentSpanId, name, kind, startedAt, durationMs, data });
 }
 
+/**
+ * Internal; whether a span recorded right now would land anywhere: trackTracing is on and the
+ * current async context is inside a traced request. The database and Redis wrappers check this
+ * before doing any work for a query or command, so outside a trace they cost nothing beyond the
+ * call itself.
+ *
+ * @returns {boolean}
+ */
+export function _isTracing() {
+  return getConfiguration().trackTracing && spanStorage.getStore() !== undefined;
+}
+
+/**
+ * Records a "database" span for every query run through this pg module (`import pg from "pg"`),
+ * for an app where init() couldn't find pg by itself: a bundled app, or one whose node_modules
+ * isn't under the directory it was started from. init() already does this for the pg it can
+ * find, so most apps never need to call it. Safe to call more than once.
+ *
+ *     import pg from "pg";
+ *     forgeOpsTracker.instrumentPg(pg);
+ *
+ * @param {unknown} pg
+ * @returns {boolean} whether it was a pg module this could patch
+ */
+export function instrumentPg(pg) {
+  return instrumentPgModule(pg, _recordSpan, _isTracing);
+}
+
+/**
+ * Records a "redis" span for every command sent through this ioredis Redis class, for an app
+ * where init() couldn't find ioredis by itself (see instrumentPg above). Safe to call more than
+ * once.
+ *
+ *     import Redis from "ioredis";
+ *     forgeOpsTracker.instrumentIoredis(Redis);
+ *
+ * @param {unknown} Redis
+ * @returns {boolean} whether it was an ioredis class this could patch
+ */
+export function instrumentIoredis(Redis) {
+  return instrumentIoredisClass(Redis, _recordSpan, _isTracing);
+}
+
 /**
  * Internal; called by whatever this client already automatically times (currently just the
  * Express controller/route lifecycle; see integrations/performance.js), never by host app code
@@ -508,6 +554,10 @@ export function init(options = {}) {
   // config, checking configuration.trackTracing fresh on every actual outbound call instead (see
   // _recordSpan above), never at install time.
   installHttpTracing(_recordSpan, _traceparentFor);
+  // The same for database queries (pg) and Redis commands (ioredis, node-redis), for whichever of
+  // those the app has installed; nothing is loaded for one it doesn't (see optionalModules.js).
+  installDatabaseTracing(_recordSpan, _isTracing);
+  installRedisTracing(_recordSpan, _isTracing);
 
   startChangeSnapshot(config);
 
@@ -610,17 +660,32 @@ export function runWithUser(user, callback) {
  * request-level trace around it, and no middleware left running to ever flush it, would just
  * accumulate in memory forever with nothing to ever send it, worse than not recording it at all.
  *
+ * A "database" span can also carry the SQL it ran, so ForgeOps can show which query was slow:
+ *
+ *     await forgeOpsTracker.span("Load orders", () => pool.query(sql, [userId]), {
+ *       kind: "database",
+ *       statement: sql,
+ *       dbSystem: "postgresql",
+ *     });
+ *
+ * The statement is masked (every string and number replaced by "?") before it's ever stored on
+ * the span, and sent as data["db.statement"], with dbSystem lowercased as data["db.system"]. Bind
+ * values are never taken, and both options are ignored on any other kind of span. Queries run
+ * through pg are already recorded this way on their own (see databaseTracing.js); a span wrapped
+ * around one just becomes its parent.
+ *
  * @template T
  * @param {string} name
  * @param {() => T} callback
- * @param {{ kind?: string, data?: Record<string, unknown> }} [options]
+ * @param {{ kind?: string, data?: Record<string, unknown>, statement?: string, dbSystem?: string }} [options]
  * @returns {T}
  */
-export function span(name, callback, { kind = "service", data = {} } = {}) {
+export function span(name, callback, { kind = "service", data = {}, statement, dbSystem } = {}) {
   const buffer = spanStorage.getStore();
   if (!buffer) {
     return callback();
   }
+  data = databaseSpanData(kind, data, statement, dbSystem);
 
   const spanId = randomSpanId();
   const parentSpanId = spanParentStorage.getStore() ?? buffer.rootSpanId;
@@ -652,6 +717,33 @@ export function span(name, callback, { kind = "service", data = {} } = {}) {
   }
 }
 
+/**
+ * The data a span is recorded with: unchanged unless it's a database span, which gets the masked
+ * statement as "db.statement" and the lowercased database name as "db.system". A "db.statement"
+ * passed in `data` directly is masked as well, so the raw SQL can't reach the payload either way.
+ * @param {string} kind
+ * @param {Record<string, unknown>} data
+ * @param {string | undefined} statement
+ * @param {string | undefined} dbSystem
+ * @returns {Record<string, unknown>}
+ */
+function databaseSpanData(kind, data, statement, dbSystem) {
+  if (kind !== "database") {
+    return data;
+  }
+  const result = { ...data };
+  const masked = maskSql(typeof statement === "string" ? statement : result["db.statement"]);
+  if (masked === null) {
+    delete result["db.statement"];
+  } else {
+    result["db.statement"] = masked;
+  }
+  if (typeof dbSystem === "string" && dbSystem.trim() !== "") {
+    result["db.system"] = dbSystem.trim().toLowerCase();
+  }
+  return result;
+}
+
 /**
  * Reports anything that would otherwise crash the process outright (a
  * plain script, an unhandled promise rejection) with no further wiring:
@@ -734,4 +826,6 @@ export function _resetForTesting({ changeSnapshot = false } = {}) {
   // on that instead of actually restoring the original functions would be fragile, not a genuine
   // guarantee.
   _uninstallHttpTracing();
+  _uninstallDatabaseTracing();
+  _uninstallRedisTracing();
 }

package/src/optionalModules.js

@@ -0,0 +1,39 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+
+/**
+ * Loads a library the host app may or may not have installed (pg, ioredis), for the automatic
+ * database and Redis span capture in databaseTracing.js and redisTracing.js. This SDK never
+ * depends on any of them: a library that isn't installed just resolves to nothing here, and that
+ * integration stays off.
+ *
+ * Resolved from the app's own directory (process.cwd()) first, then from this package's own
+ * location, since a package manager that isolates dependencies (pnpm) may not let this package see
+ * the app's copy at all. Every distinct copy found is returned (a monorepo can hold two), so each
+ * one gets patched. An app whose copy can't be found this way (a bundled app, or one started from
+ * another directory) can hand the module over itself instead: see instrumentPg/instrumentIoredis
+ * in index.js.
+ *
+ * Loading through require() also covers an app that imports the library as ESM: pg's ESM entry
+ * point and ioredis's CommonJS one both end up in the same require cache entry, so there's only
+ * one Client/Redis class to patch either way.
+ *
+ * @param {string} name
+ * @returns {unknown[]}
+ */
+export function requireOptional(name) {
+  const bases = [path.join(process.cwd(), "package.json"), import.meta.url];
+  const loaded = new Map();
+  for (const base of bases) {
+    try {
+      const require = createRequire(base);
+      const resolved = require.resolve(name);
+      if (!loaded.has(resolved)) {
+        loaded.set(resolved, require(name));
+      }
+    } catch {
+      // Not installed where this base looks: nothing to patch from here.
+    }
+  }
+  return [...loaded.values()];
+}

package/src/redisTracing.js

@@ -0,0 +1,158 @@
+import { AsyncResource } from "node:async_hooks";
+import diagnosticsChannel from "node:diagnostics_channel";
+import { requireOptional } from "./optionalModules.js";
+
+const WRAPPED = Symbol("forgeOpsTrackerWrapped");
+const SEEN = Symbol("forgeOpsTrackerSeen");
+const SPAN = Symbol("forgeOpsTrackerSpan");
+const NODE_REDIS_COMMAND_CHANNEL = "node-redis:command";
+
+let installed = false;
+// Every patch made, so _uninstallRedisTracing can put each method back exactly as found.
+const patches = [];
+let nodeRedisSubscription = null;
+
+/**
+ * Records one "redis" span per Redis command, for an app using ioredis or node-redis (the `redis`
+ * package); installed from index.js's init() the same way installHttpTracing is, exactly once for
+ * the life of the process, and checking whether a trace is being captured fresh on every command.
+ * Neither library is loaded or required unless the app has it installed.
+ *
+ * Every span is named "Redis <COMMAND>" (the command alone, upcased: GET, SET, LPUSH...) with no
+ * data at all: never a key or any other argument, since a key can easily carry a customer's own
+ * id or other sensitive value. The same name and kind gems/forge_ops_tracker's
+ * Integrations::RedisClientTiming records.
+ *
+ * ioredis (every version from 4.x on) is covered by wrapping Redis.prototype.sendCommand, which
+ * every command goes through, pipelined and MULTI ones included (see instrumentIoredis).
+ *
+ * node-redis is covered through the "node-redis:command" diagnostics channel it publishes every
+ * command on from version 5.12 on (@redis/client), so nothing in it is patched and it's never
+ * loaded from here: subscribing by name works whether or not the app ever loads it. Earlier
+ * node-redis versions (4.x, and 5.x before 5.12) publish nothing there and aren't covered.
+ *
+ * @param {(name: string, kind: string, startedAt: Date, durationMs: number, data?: Record<string, unknown>) => void} recordSpan
+ * @param {() => boolean} isTracing whether the current async context has a trace to record into
+ */
+export function installRedisTracing(recordSpan, isTracing) {
+  if (installed) {
+    return;
+  }
+  installed = true;
+  for (const Redis of requireOptional("ioredis")) {
+    instrumentIoredis(Redis, recordSpan, isTracing);
+  }
+  subscribeNodeRedis(recordSpan, isTracing);
+}
+
+/**
+ * Patches one ioredis Redis class (what `import Redis from "ioredis"` returns). Safe to call more
+ * than once for the same class.
+ *
+ * ioredis can pass the same command through sendCommand more than once (flushing its offline
+ * queue once connected, resending after a reconnect), so each command is only timed the first
+ * time, from when the app sent it until its reply. The span is recorded when ioredis settles the
+ * command (its own resolve/reject), rather than by attaching a handler to the command's promise:
+ * that would mark a rejection the app never handles as handled, and it would no longer be
+ * reported as an unhandled rejection.
+ *
+ * @param {any} Redis
+ * @param {Parameters<typeof installRedisTracing>[0]} recordSpan
+ * @param {() => boolean} isTracing
+ * @returns {boolean} whether there was a sendCommand to patch
+ */
+export function instrumentIoredis(Redis, recordSpan, isTracing) {
+  const prototype = Redis?.prototype;
+  if (typeof prototype?.sendCommand !== "function" || prototype.sendCommand[WRAPPED]) {
+    return typeof prototype?.sendCommand === "function";
+  }
+  const originalSendCommand = prototype.sendCommand;
+
+  const patchedSendCommand = function patchedSendCommand(command, ...rest) {
+    if (command && typeof command === "object" && !command[SEEN] && isTracing()) {
+      command[SEEN] = true;
+      observeCommand(command, recordSpan);
+    }
+    return originalSendCommand.call(this, command, ...rest);
+  };
+  patchedSendCommand[WRAPPED] = true;
+
+  patches.push({ target: prototype, key: "sendCommand", original: originalSendCommand, own: Object.prototype.hasOwnProperty.call(prototype, "sendCommand") });
+  prototype.sendCommand = patchedSendCommand;
+  return true;
+}
+
+/** @internal test-only: restores every method installRedisTracing replaced, and unsubscribes. */
+export function _uninstallRedisTracing() {
+  while (patches.length > 0) {
+    const { target, key, original, own } = patches.pop();
+    if (own) {
+      target[key] = original;
+    } else {
+      delete target[key];
+    }
+  }
+  if (nodeRedisSubscription !== null) {
+    diagnosticsChannel.tracingChannel(NODE_REDIS_COMMAND_CHANNEL).unsubscribe(nodeRedisSubscription);
+    nodeRedisSubscription = null;
+  }
+  installed = false;
+}
+
+function observeCommand(command, recordSpan) {
+  const { resolve, reject } = command;
+  if (typeof resolve !== "function" || typeof reject !== "function") {
+    return;
+  }
+  const finish = startSpan(command.name, recordSpan);
+  command.resolve = function resolveWithSpan(...args) {
+    finish();
+    return resolve.apply(this, args);
+  };
+  command.reject = function rejectWithSpan(...args) {
+    finish();
+    return reject.apply(this, args);
+  };
+}
+
+/**
+ * Starts timing one command now and returns the function that records it, bound to the caller's
+ * async context: the reply arrives from the connection's own socket handlers, where the trace the
+ * command belongs to isn't the current one. Only ever records once.
+ */
+function startSpan(commandName, recordSpan) {
+  const name = `Redis ${String(commandName).toUpperCase()}`;
+  const startedAt = new Date();
+  const start = performance.now();
+  let finished = false;
+  return AsyncResource.bind(() => {
+    if (finished) {
+      return;
+    }
+    finished = true;
+    recordSpan(name, "redis", startedAt, performance.now() - start);
+  });
+}
+
+/**
+ * node-redis runs each command inside TracingChannel#tracePromise: "start" is published
+ * synchronously from the app's own call (so isTracing() sees the right trace), and "asyncEnd" once
+ * the reply has settled the command either way. Only `context.command` (already upcased by
+ * node-redis) is read, never `context.args`.
+ */
+function subscribeNodeRedis(recordSpan, isTracing) {
+  if (typeof diagnosticsChannel.tracingChannel !== "function") {
+    return;
+  }
+  nodeRedisSubscription = {
+    start(context) {
+      if (context && typeof context === "object" && isTracing()) {
+        context[SPAN] = startSpan(context.command, recordSpan);
+      }
+    },
+    asyncEnd(context) {
+      context?.[SPAN]?.();
+    },
+  };
+  diagnosticsChannel.tracingChannel(NODE_REDIS_COMMAND_CHANNEL).subscribe(nodeRedisSubscription);
+}