@forge-ops/tracker 0.2.0 → 0.5.0

package/README.md

@@ -7,11 +7,8 @@ events to ForgeOps over HTTP without blocking the request or process that raised
 
 ## Installation
 
-Not yet published to npm: install directly from this path (or a local checkout, once split into
-its own repo):
-
 ```bash
-npm install /path/to/forge_ops/sdks/node
+npm install @forge-ops/tracker
 ```
 
 ## Configuration
@@ -36,9 +33,12 @@ overridden by passing it in the options object.
 
 ```js
 import { forgeOpsTrackerSessionTrackingExpressMiddleware } from "@forge-ops/tracker/integrations/session-tracking";
-import { forgeOpsTrackerExpressMiddleware } from "@forge-ops/tracker/integrations/express";
+import { forgeOpsTrackerPerformanceExpressMiddleware } from "@forge-ops/tracker/integrations/performance";
+import { forgeOpsTrackerUserContextMiddleware, forgeOpsTrackerExpressMiddleware } from "@forge-ops/tracker/integrations/express";
 
 app.use(forgeOpsTrackerSessionTrackingExpressMiddleware); // first, before any routes
+app.use(forgeOpsTrackerPerformanceExpressMiddleware); // order relative to routes doesn't matter
+app.use(forgeOpsTrackerUserContextMiddleware); // after Passport's own session middleware, if used
 // ...routes...
 app.use(forgeOpsTrackerExpressMiddleware); // still last, after all routes
 ```
@@ -109,6 +109,40 @@ themselves, long before it would ever reach here.
 Every failure mode (network errors, timeouts, a full queue, a malformed DSN) is caught and
 dropped rather than thrown, so a broken or unreachable tracker can never take down the host app.
 
+## Identifying users
+
+```js
+captureException(error, {}, { id: user.id, email: user.email });
+```
+
+Or `runWithUser(user, callback)` to attach it to every `captureException()` call made anywhere in
+`callback`'s own async chain, rather than passing it by hand every time, e.g. from your own
+middleware:
+
+```js
+app.use((req, res, next) => runWithUser({ id: req.user?.id, email: req.user?.email }, next));
+```
+
+There's no imperative `setUser()` the way some other languages in this repo have: Node is
+single-threaded, so a plain module-level variable would leak across concurrent requests
+interleaved on the same event loop, exactly the bug the other languages' own thread-local choice
+avoids for their own concurrency model. `AsyncLocalStorage` (Node's own built-in mechanism for
+this) only propagates a value through an async call chain that was explicitly wrapped, so
+`runWithUser`'s wrapping shape is the correct, idiomatic choice here, not a limitation being
+worked around. `id`/`email`/`username` are all independently optional. Shows up on an issue's own
+detail page, and as its own affected-users count alongside the regular event count.
+
+**Express apps get this automatically**: add `forgeOpsTrackerUserContextMiddleware` (see the
+Express snippet above), after whatever middleware actually sets `req.user` (Passport's own session
+middleware, the closest thing Express has to a single dominant auth library, the same role Warden
+plays for Rails). A no-op when `req.user` is never set, whether that's because nobody's signed in
+or Passport isn't installed. Confirmed directly, with a real Express app and a real async route
+handler, that the `AsyncLocalStorage` context this sets survives all the way through to
+`forgeOpsTrackerExpressMiddleware` later in the same request, including across an `await`, not
+just through a synchronous call chain. Composes with the manual API above rather than replacing
+it: call `runWithUser` yourself for a route (or a custom auth setup this can't detect) that needs
+to override what was auto-detected.
+
 ## Delivery: an async loop, not a thread
 
 `DeliveryQueue` here isn't a background *thread*: Node is single-threaded. But a Node process is
@@ -141,7 +175,9 @@ By default, the message, backtrace, and any context/tags you attach are scanned
 for likely personal data: email addresses, formatted SSNs/credit cards, known API key/token
 formats, and anything under a suspiciously-named key (`password`, `apiKey`, `ssn`, and similar),
 and redacted before the payload ever leaves this process. ForgeOps itself scrubs again on arrival
-regardless, so this is a second, earlier layer, not the only one.
+regardless, so this is a second, earlier layer, not the only one. The user attached via
+`captureException`'s third argument or `runWithUser` above is a deliberate exception: it's never
+scrubbed, since redacting it would defeat the whole point of identifying users in the first place.
 
 To disable it:
 
@@ -197,6 +233,32 @@ shutdown if this tracker's own listener won that race. The accepted trade-off: u
 would be if the interval simply hadn't ticked yet: never a behavior change for whatever app this
 is installed into. See `src/sessionFlusher.js`'s own comment for the full reasoning.
 
+## Performance monitoring
+
+By default, the Express integration times every request (`performance.now()` before the route
+runs, diffed once the response finishes) so a dashboard widget on ForgeOps can show which parts
+of your app are actually slow, not just which ones raise. Bucketed by transaction
+(`"GET /users/:id"`, the matched route pattern rather than the literal URL, so a distinct user id
+doesn't explode into its own separate transaction) and flushed as a small periodic aggregate per
+transaction on the same kind of `setInterval` timer session tracking above uses.
+
+```js
+forgeOpsTracker.init({
+  dsn: "...",
+  trackPerformance: false, // opt out entirely
+  performanceFlushIntervalMs: 30000, // default 60000
+});
+```
+
+Requires a ForgeOps plan that includes performance monitoring; on a plan that doesn't, the
+periodic flushes are simply rejected server-side and dropped, exactly like any other delivery
+failure. Same deliberate no-flush-on-`SIGTERM`/`SIGINT` gap as session tracking above, and for
+the identical reason; see `src/performanceFlusher.js`'s own comment.
+
+Fastify isn't supported yet: unlike session tracking, there's no existing request-lifecycle hook
+to build this on for Fastify today, so it's a separate piece of work rather than something this
+version already covers.
+
 ## Running the tests
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forge-ops/tracker",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "ForgeOps error tracking client: captures unhandled exceptions (Express/Fastify integration, plus explicit capture anywhere else) and delivers them to a ForgeOps instance over HTTP.",
   "type": "module",
   "main": "src/index.js",
@@ -8,7 +8,8 @@
     ".": "./src/index.js",
     "./integrations/express": "./src/integrations/express.js",
     "./integrations/fastify": "./src/integrations/fastify.js",
-    "./integrations/session-tracking": "./src/integrations/sessionTracking.js"
+    "./integrations/session-tracking": "./src/integrations/sessionTracking.js",
+    "./integrations/performance": "./src/integrations/performance.js"
   },
   "engines": {
     "node": ">=18"

package/src/client.js

@@ -28,6 +28,17 @@ export class Client {
     return this.#post(this.#configuration.sessionCheckinsUri(), payload);
   }
 
+  /**
+   * Same delivery contract again; samples is a batch (one entry per distinct transaction a
+   * flush interval saw), not a single aggregate the way deliverSessionCheckin's own payload is,
+   * so this posts { samples } rather than the array bare, matching what
+   * Api::V1::PerformanceSamplesController expects.
+   * @param {Record<string, unknown>[]} samples
+   */
+  async deliverPerformanceSamples(samples) {
+    return this.#post(this.#configuration.performanceSamplesUri(), { samples });
+  }
+
   /**
    * @param {string | null} uri
    * @param {Record<string, unknown>} payload

package/src/configuration.js

@@ -56,6 +56,15 @@ export class Configuration {
    * flushed as one small report on this interval, not one network call per request. */
   sessionFlushIntervalMs = 60000;
 
+  /**
+   * Whether the Express integration times every request's duration and periodically reports an
+   * aggregate per transaction. On by default, the same posture trackSessions above already has.
+   */
+  trackPerformance = true;
+  /** Milliseconds between aggregate performance reports; same "counted in-process, flushed as
+   * one small batch on this interval" reasoning as sessionFlushIntervalMs above. */
+  performanceFlushIntervalMs = 60000;
+
   /** @returns {string | null} */
   apiKey() {
     const parsed = this.#parsedDsn();
@@ -94,6 +103,18 @@ export class Configuration {
     return uri.replace(/\/events$/, "/session_checkins");
   }
 
+  /**
+   * Same derivation again, swapping the trailing /events for /performance_samples.
+   * @returns {string | null}
+   */
+  performanceSamplesUri() {
+    const uri = this.ingestionUri();
+    if (!uri) {
+      return null;
+    }
+    return uri.replace(/\/events$/, "/performance_samples");
+  }
+
   /** @returns {boolean} */
   isEnabled() {
     return Boolean(this.dsn) && this.apiKey() !== null && this.enabledEnvironments.has(this.environment);

package/src/eventBuilder.js

@@ -46,8 +46,9 @@ export class EventBuilder {
   /**
    * @param {Error} error
    * @param {Record<string, unknown>} [context]
+   * @param {Record<string, unknown> | null} [user]
    */
-  build(error, context = {}) {
+  build(error, context = {}, user = null) {
     const payload = {
       exception_class: error?.name ?? "Error",
       message: error?.message ?? "",
@@ -60,14 +61,20 @@ export class EventBuilder {
       tags: {},
       sdk_name: SDK_NAME,
     };
+    if (user && Object.keys(user).length > 0) {
+      payload.user = { ...user };
+    }
 
     return this.#configuration.scrubPii ? this.#scrub(payload) : payload;
   }
 
-  // exception_class/occurred_at/environment/release/server_name are left
-  // alone: structured fields this client or the host app sets
+  // exception_class/occurred_at/environment/release/server_name/user are
+  // left alone: structured fields this client or the host app sets
   // deliberately, not free text an exception or its context could
-  // accidentally spill sensitive data into.
+  // accidentally spill sensitive data into. user specifically is a
+  // deliberate exemption, not an oversight: the scrubber's own email
+  // pattern would otherwise redact the exact thing this field exists to
+  // carry.
   #scrub(payload) {
     return {
       ...payload,

package/src/index.js

@@ -1,7 +1,9 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { Client } from "./client.js";
 import { Configuration } from "./configuration.js";
 import { DeliveryQueue } from "./deliveryQueue.js";
 import { EventBuilder } from "./eventBuilder.js";
+import { PerformanceFlusher } from "./performanceFlusher.js";
 import { Reporter } from "./reporter.js";
 import { SessionFlusher } from "./sessionFlusher.js";
 
@@ -10,10 +12,22 @@ export { Configuration };
 let configuration = null;
 let reporter = null;
 let sessionFlusher = null;
+let performanceFlusher = null;
 let processHandlersInstalled = false;
 let uncaughtExceptionListener = null;
 let unhandledRejectionListener = null;
 
+// Request-scoped affected-user storage. AsyncLocalStorage, not a plain module-level variable the
+// way gems/forge_ops_tracker uses Thread.current or Python uses threading.local: Node is
+// single-threaded, so a plain variable would leak across concurrent requests being interleaved
+// on the same event loop, exactly the bug those other languages' own thread-local choice avoids
+// for their own concurrency model. AsyncLocalStorage is the Node-idiomatic equivalent, but its
+// API shape is different on purpose: it only propagates a value through an async call chain that
+// was explicitly wrapped via runWithUser() below (there's no imperative "just set it from
+// anywhere" the way Thread.current allows), which is why this SDK's own set_user-equivalent is a
+// wrapping function, not a bare setter.
+const userStorage = new AsyncLocalStorage();
+
 function getConfiguration() {
   if (configuration === null) {
     configuration = new Configuration();
@@ -39,6 +53,14 @@ function getSessionFlusher() {
   return sessionFlusher;
 }
 
+function getPerformanceFlusher() {
+  if (performanceFlusher === null) {
+    const config = getConfiguration();
+    performanceFlusher = new PerformanceFlusher(config, new Client(config));
+  }
+  return performanceFlusher;
+}
+
 /**
  * Internal; called by the Express/Fastify session-tracking integrations, never by host app
  * code directly (there's nothing for a caller to decide here beyond what the middleware/hook
@@ -54,6 +76,21 @@ export function _recordSession(crashed) {
   getSessionFlusher().recordSession(crashed);
 }
 
+/**
+ * Internal; called by the Express performance-tracking integration, never by host app code
+ * directly, same reasoning as _recordSession above.
+ *
+ * @param {string} transactionName
+ * @param {number} durationMs
+ */
+export function _recordPerformance(transactionName, durationMs) {
+  const config = getConfiguration();
+  if (!config.trackPerformance || !config.isEnabled()) {
+    return;
+  }
+  getPerformanceFlusher().record(transactionName, durationMs);
+}
+
 /**
  * Configure the client. Call once at startup.
  *
@@ -79,13 +116,37 @@ export function init(options = {}) {
 }
 
 /**
- * Report an exception you've already caught.
+ * Report an exception you've already caught. `user` defaults to whatever runWithUser() below
+ * established for this async call chain, if anything; pass one explicitly to override that for
+ * this one report.
  *
  * @param {Error} error
  * @param {Record<string, unknown>} [context]
+ * @param {Record<string, unknown> | null} [user]
+ */
+export function captureException(error, context = {}, user = null) {
+  getReporter().report(error, context, user ?? userStorage.getStore()?.user ?? null);
+}
+
+/**
+ * Runs `callback` (sync or async) with an affected user attached to every `captureException()`
+ * call made anywhere in its call chain that doesn't pass its own explicit `user`, e.g. from your
+ * own middleware:
+ *
+ *     app.use((req, res, next) => runWithUser({ id: req.user?.id }, next));
+ *
+ * There's no imperative `setUser()` the way other languages in this repo have: AsyncLocalStorage
+ * (see this module's own comment on `userStorage`) only propagates a value through an async call
+ * chain that was explicitly wrapped like this, so wrapping is the correct, idiomatic shape here,
+ * not a limitation being worked around.
+ *
+ * @template T
+ * @param {Record<string, unknown>} user
+ * @param {() => T} callback
+ * @returns {T}
  */
-export function captureException(error, context = {}) {
-  getReporter().report(error, context);
+export function runWithUser(user, callback) {
+  return userStorage.run({ user }, callback);
 }
 
 /**
@@ -137,6 +198,7 @@ export function _resetForTesting() {
   configuration = null;
   reporter = null;
   sessionFlusher = null;
+  performanceFlusher = null;
   processHandlersInstalled = false;
   uncaughtExceptionListener = null;
   unhandledRejectionListener = null;

package/src/integrations/express.js

@@ -1,4 +1,4 @@
-import { captureException } from "../index.js";
+import { captureException, runWithUser } from "../index.js";
 
 /**
  * Express error-handling middleware. Register last, after all routes:
@@ -26,3 +26,52 @@ export function forgeOpsTrackerExpressMiddleware(err, req, res, next) {
   });
   next(err);
 }
+
+/**
+ * Automatically identifies the affected user for every error reported for the rest of this
+ * request, when `req.user` is present. Register early, before your routes (and after whatever
+ * middleware actually sets `req.user`, e.g. Passport's own session middleware):
+ *
+ *     app.use(passport.session());
+ *     app.use(forgeOpsTrackerUserContextMiddleware);
+ *     // ...routes...
+ *     app.use(forgeOpsTrackerExpressMiddleware);
+ *
+ * `req.user` is Passport's own convention (the closest thing Express has to a single dominant
+ * auth library, the same role Warden plays for Rails): set once `passport.authenticate()`/session
+ * deserialization succeeds, left `undefined` otherwise, so a plain truthy check is enough, the
+ * same duck-typed "is there a user object at all" check `gems/forge_ops_tracker`'s own Warden
+ * integration does for `env["warden"].user`. A no-op for an app that never set `req.user` at all,
+ * whether that's because nobody's signed in or Passport (or an equivalent) isn't installed.
+ *
+ * Wraps the rest of the request in `runWithUser()` (see that function's own doc comment for why
+ * this SDK has no imperative `setUser()`) rather than setting anything imperatively itself:
+ * confirmed directly, with a real Express app and a real async route handler, that
+ * `AsyncLocalStorage`'s context set by an early middleware like this one does survive all the way
+ * through to a later error-handling middleware (`forgeOpsTrackerExpressMiddleware`, typically
+ * registered last, after every route) in the same request, not just to handlers registered
+ * synchronously right after this one.
+ */
+export function forgeOpsTrackerUserContextMiddleware(req, res, next) {
+  if (!req.user) {
+    next();
+    return;
+  }
+  runWithUser(serializeUser(req.user), next);
+}
+
+function serializeUser(user) {
+  const result = {};
+  if (user.id !== undefined && user.id !== null) {
+    result.id = String(user.id);
+  }
+  if (user.email) {
+    result.email = user.email;
+  }
+  if (user.username) {
+    result.username = user.username;
+  } else if (user.name) {
+    result.username = user.name;
+  }
+  return result;
+}

package/src/integrations/performance.js

@@ -0,0 +1,34 @@
+import { _recordPerformance } from "../index.js";
+
+/**
+ * Express performance-tracking middleware. Register wherever is convenient relative to routes
+ * (unlike sessionTracking.js's own middleware, this doesn't need to run first: it only reads
+ * req.route once the request has already been routed, inside the "finish" listener below, not
+ * at request-start):
+ *
+ *   app.use(forgeOpsTrackerPerformanceExpressMiddleware);
+ *
+ * Times every request (performance.now() before next(), diffed inside res.on("finish")) so a
+ * dashboard widget on ForgeOps can show which parts of your app are actually slow, not just
+ * which ones raise. A separate, independent middleware from both the error and session-tracking
+ * ones, same "several genuinely independent mechanisms" reasoning sessionTracking.js's own
+ * comment documents.
+ *
+ * transactionName is "<HTTP method> <route pattern>", e.g. "GET /users/:id", not the raw URL:
+ * req.route.path is Express's own matched route pattern, read here (after routing has actually
+ * happened, unlike at request-start where it isn't populated yet), which keeps a distinct user
+ * id from exploding into its own separate transaction the way the literal URL would -- the
+ * low-cardinality equivalent of a Rails controller#action. Falls back to req.path (the literal,
+ * unmatched path) for a request that never matched a route at all (a 404).
+ */
+export function forgeOpsTrackerPerformanceExpressMiddleware(req, res, next) {
+  const start = performance.now();
+
+  res.on("finish", () => {
+    const durationMs = performance.now() - start;
+    const transactionName = `${req.method} ${req.route?.path ?? req.path}`;
+    _recordPerformance(transactionName, durationMs);
+  });
+
+  next();
+}

package/src/performanceFlusher.js

@@ -0,0 +1,88 @@
+/**
+ * Times requests in-process, bucketed by transactionName (see integrations/performance.js), and
+ * periodically flushes each distinct bucket as one small aggregate report, rather than one
+ * network call per request. Ported from
+ * gems/forge_ops_tracker/lib/forge_ops_tracker/performance_flusher.rb; structurally the same
+ * shape as sessionFlusher.js right next to it, just keyed by a Map of buckets instead of two
+ * scalar counters.
+ *
+ * setInterval(...).unref(), not a real background thread, same reasoning sessionFlusher.js's own
+ * header comment documents. Also deliberately does NOT hook SIGTERM/SIGINT to force a final
+ * flush on exit, for the exact same reason sessionFlusher.js already rejects that: registering
+ * either listener overrides Node's own default exit behavior, a real correctness risk to the
+ * host app's own graceful shutdown, not just a data-completeness one. The accepted trade-off is
+ * the same too: up to one performanceFlushIntervalMs window of data can be lost on a hard
+ * process exit, a bounded, honest gap rather than a behavior change for the host app.
+ */
+export class PerformanceFlusher {
+  #configuration;
+  #client;
+  #buckets = new Map();
+  #periodStartedAt = new Date();
+  #timer = null;
+
+  constructor(configuration, client) {
+    this.#configuration = configuration;
+    this.#client = client;
+  }
+
+  /**
+   * @param {string} transactionName
+   * @param {number} durationMs
+   */
+  record(transactionName, durationMs) {
+    this.#ensureTimerStarted();
+
+    const bucket = this.#buckets.get(transactionName) ?? { count: 0, durationSumMs: 0, maxDurationMs: 0 };
+    bucket.count += 1;
+    bucket.durationSumMs += durationMs;
+    if (durationMs > bucket.maxDurationMs) {
+      bucket.maxDurationMs = durationMs;
+    }
+    this.#buckets.set(transactionName, bucket);
+  }
+
+  /**
+   * Snapshots and resets the buckets, then delivers them as one batch. A failed delivery keeps
+   * every bucket where it is rather than resetting, so the next flush's batch just grows instead
+   * of losing what was already tallied; same reasoning sessionFlusher.js's own flush() documents.
+   */
+  async flush() {
+    if (this.#buckets.size === 0) {
+      return;
+    }
+
+    const periodEndedAt = new Date();
+    const samples = [...this.#buckets.entries()].map(([transactionName, bucket]) => ({
+      transaction_name: transactionName,
+      environment: this.#configuration.environment,
+      release: this.#configuration.release,
+      period_started_at: this.#periodStartedAt.toISOString(),
+      period_ended_at: periodEndedAt.toISOString(),
+      request_count: bucket.count,
+      duration_sum_ms: bucket.durationSumMs,
+      max_duration_ms: bucket.maxDurationMs,
+    }));
+
+    const delivered = await this.#client.deliverPerformanceSamples(samples);
+    if (!delivered) {
+      return;
+    }
+
+    this.#buckets = new Map();
+    this.#periodStartedAt = periodEndedAt;
+  }
+
+  #ensureTimerStarted() {
+    if (this.#timer !== null) {
+      return;
+    }
+
+    this.#timer = setInterval(() => {
+      this.flush().catch((e) => {
+        this.#configuration.log(`[forge-ops-tracker] performance flush error: ${e.name}: ${e.message}`);
+      });
+    }, this.#configuration.performanceFlushIntervalMs);
+    this.#timer.unref();
+  }
+}

package/src/reporter.js

@@ -20,14 +20,15 @@ export class Reporter {
   /**
    * @param {Error} error
    * @param {Record<string, unknown>} [context]
+   * @param {Record<string, unknown> | null} [user]
    */
-  report(error, context = {}) {
+  report(error, context = {}, user = null) {
     try {
       if (!this.#configuration.isEnabled()) {
         return;
       }
 
-      const payload = this.#eventBuilder.build(error, context);
+      const payload = this.#eventBuilder.build(error, context, user);
       this.#deliveryQueue.push(payload);
     } catch (e) {
       this.#configuration.log(`[forge-ops-tracker] report failed: ${e.name}: ${e.message}`);