@forge-ops/tracker 0.12.0 → 0.13.0

package/README.md

@@ -539,10 +539,39 @@ 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 with their SQL
+
+Database queries aren't captured automatically (this SDK has no query or ORM instrumentation hook
+to extend), so wrap a query by hand with `kind: "database"` to have it show up as its own span. Pass
+the SQL as `statement` and ForgeOps shows which query a slow request spent its time in:
+
+```js
+import pg from "pg";
+import * as forgeOpsTracker from "@forge-ops/tracker";
+
+const pool = new pg.Pool();
+
+app.get("/orders", async (req, res) => {
+  const sql = "SELECT id, total FROM orders WHERE customer_id = $1 AND status = 'open'";
+  const { rows } = await forgeOpsTracker.span("Load open orders", () => pool.query(sql, [req.user.id]), {
+    kind: "database",
+    statement: sql,
+    dbSystem: "postgresql",
+  });
+  res.json(rows);
+});
+```
+
+The statement is masked before it's stored on the span: every string and number becomes `?`, so the
+span above carries `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. `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`.
+
+**Known gaps:** no automatic database span capture (see above) and no Redis span capture (no
+existing Redis hook or dependency exists here either); a Redis call inside a traced request just
+won't show up as its own span for now.
 
 ## Database errors
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forge-ops/tracker",
-  "version": "0.12.0",
+  "version": "0.13.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",

package/src/index.js

@@ -12,6 +12,7 @@ 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 };
@@ -610,17 +611,30 @@ 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.
+ *
  * @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 +666,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: