@forge-ops/tracker 0.2.0 → 0.3.0

package/README.md

@@ -36,9 +36,11 @@ overridden by passing it in the options object.
 
 ```js
 import { forgeOpsTrackerSessionTrackingExpressMiddleware } from "@forge-ops/tracker/integrations/session-tracking";
+import { forgeOpsTrackerPerformanceExpressMiddleware } from "@forge-ops/tracker/integrations/performance";
 import { forgeOpsTrackerExpressMiddleware } from "@forge-ops/tracker/integrations/express";
 
 app.use(forgeOpsTrackerSessionTrackingExpressMiddleware); // first, before any routes
+app.use(forgeOpsTrackerPerformanceExpressMiddleware); // order relative to routes doesn't matter
 // ...routes...
 app.use(forgeOpsTrackerExpressMiddleware); // still last, after all routes
 ```
@@ -197,6 +199,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.3.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/index.js

@@ -2,6 +2,7 @@ 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,6 +11,7 @@ export { Configuration };
 let configuration = null;
 let reporter = null;
 let sessionFlusher = null;
+let performanceFlusher = null;
 let processHandlersInstalled = false;
 let uncaughtExceptionListener = null;
 let unhandledRejectionListener = null;
@@ -39,6 +41,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 +64,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.
  *
@@ -137,6 +162,7 @@ export function _resetForTesting() {
   configuration = null;
   reporter = null;
   sessionFlusher = null;
+  performanceFlusher = null;
   processHandlersInstalled = false;
   uncaughtExceptionListener = null;
   unhandledRejectionListener = null;

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();
+  }
+}