@forge-ops/tracker 0.10.0 → 0.12.0

package/src/index.js

@@ -1,5 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { BreadcrumbBuffer } from "./breadcrumbBuffer.js";
+import { buildChange, buildSnapshot } from "./changes.js";
 import { Client } from "./client.js";
 import { Configuration } from "./configuration.js";
 import { DeliveryQueue } from "./deliveryQueue.js";
@@ -8,8 +9,10 @@ import { installHttpTracing, _uninstallHttpTracing } from "./httpTracing.js";
 import { MetricBuffer } from "./metricBuffer.js";
 import { PerformanceFlusher } from "./performanceFlusher.js";
 import { Reporter } from "./reporter.js";
+import { requestStateFor } from "./requestState.js";
 import { SessionFlusher } from "./sessionFlusher.js";
 import { randomSpanId, SpanBuffer } from "./spanBuffer.js";
+import { buildTraceparent } from "./traceParent.js";
 
 export { Configuration };
 export { withSql } from "./sqlStatement.js";
@@ -19,6 +22,8 @@ let reporter = null;
 let sessionFlusher = null;
 let performanceFlusher = null;
 let spanQueue = null;
+let changeQueue = null;
+let changeSnapshotStarted = false;
 let metricBuffer = null;
 let infrastructureMetricBuffer = null;
 let processHandlersInstalled = false;
@@ -78,6 +83,14 @@ const spanStorage = new AsyncLocalStorage();
 // SpanBuffer at all" as the real signal for "not inside a traced request").
 const spanParentStorage = new AsyncLocalStorage();
 
+// Request-scoped RequestState (trace id, remote parent span id, transaction name, endpoint, errored
+// flag; see requestState.js), published by the Express/Fastify integrations for the duration of a
+// request through _runWithRequestState below. Not gated on trackTracing: the trace id links an
+// error to errors in other services even when no spans are ever recorded. Unset outside a request,
+// where captureException, span tracing, and the outbound-HTTP wrapper all behave exactly as they
+// did before this existed.
+const requestStorage = new AsyncLocalStorage();
+
 function getConfiguration() {
   if (configuration === null) {
     configuration = new Configuration();
@@ -173,6 +186,70 @@ export async function flushMetrics() {
   await Promise.all([metricBuffer.flush(), infrastructureMetricBuffer.flush()]);
 }
 
+function getChangeQueue() {
+  if (changeQueue === null) {
+    const config = getConfiguration();
+    changeQueue = new DeliveryQueue(config, new Client(config), { deliverMethod: "deliverChange", label: "change" });
+  }
+  return changeQueue;
+}
+
+/**
+ * Records one thing that changed in a running system, so ForgeOps can show it next to the errors
+ * and slowdowns that followed:
+ *
+ *     recordChange({ kind: "feature_flag", title: "Enabled new_checkout for 10%", details: { rollout: 10 } });
+ *
+ * `kind` is one of feature_flag, config, migration, dependency, infrastructure, or other (anything
+ * else is sent as "other"). `environment` defaults to the configured one; `occurredAt` (a Date or an
+ * ISO 8601 string) defaults to now; `id` is an optional idempotency key. Queued and delivered on the
+ * same async loop as error events, so it never blocks the caller. A no-op when the client isn't
+ * enabled. Never throws: returns false when nothing was queued.
+ *
+ * @param {{ kind: string, title: string, details?: Record<string, unknown>, environment?: string,
+ *   service?: string, actor?: string, url?: string, id?: string, occurredAt?: Date | string }} change
+ * @returns {boolean}
+ */
+export function recordChange(change) {
+  try {
+    const config = getConfiguration();
+    if (!config.isEnabled()) {
+      return false;
+    }
+    const payload = buildChange(config, change ?? {});
+    if (payload === null) {
+      return false;
+    }
+    return getChangeQueue().push(payload);
+  } catch (e) {
+    getConfiguration().log(`[forge-ops-tracker] recordChange failed: ${e.name}: ${e.message}`);
+    return false;
+  }
+}
+
+/**
+ * Sends the one startup snapshot this process sends (see changes.js), on a later event-loop turn so
+ * init() returns immediately and startup never waits on it. A second call is a no-op. Does nothing,
+ * and doesn't use up the once, when the client isn't enabled or detectChanges is off. The timer is
+ * unref'd, so a short script that's otherwise done doesn't stay alive just to send it. Never throws.
+ */
+function startChangeSnapshot(config) {
+  if (changeSnapshotStarted || !config.isEnabled() || !config.detectChanges) {
+    return false;
+  }
+  changeSnapshotStarted = true;
+
+  const timer = setTimeout(async () => {
+    try {
+      await new Client(config).deliverChangeSnapshot(await buildSnapshot(config));
+    } catch (e) {
+      config.log(`[forge-ops-tracker] change snapshot failed: ${e.name}: ${e.message}`);
+    }
+  }, 0);
+  timer.unref?.();
+  return true;
+}
+
 /**
  * A DeliveryQueue reused for spans (see that class's own comment for why it takes a
  * deliverMethod/label rather than needing a whole second, near-identical class the way
@@ -242,6 +319,64 @@ export function _runWithBreadcrumbTrail(callback) {
   return breadcrumbStorage.run(new BreadcrumbBuffer(config), callback);
 }
 
+/**
+ * Internal; called by the Express/Fastify integrations with their own request object and its
+ * incoming traceparent header's raw value. Returns the RequestState memoized on that request (see
+ * requestState.js), continuing the incoming trace or starting a fresh one, or null when the client
+ * isn't enabled at all, the same "skip entirely" gating every other automatic source applies.
+ *
+ * @param {object} request an Express req or a Fastify request
+ * @param {unknown} traceparent
+ * @returns {import("./requestState.js").RequestState | null}
+ */
+export function _requestStateFor(request, traceparent) {
+  if (!getConfiguration().isEnabled()) {
+    return null;
+  }
+  return requestStateFor(request, traceparent);
+}
+
+/**
+ * Internal; runs callback with `state` published as the current request's for its whole async
+ * call chain. Just calls callback when state is null, or already the current one (two integrations
+ * wrapping the same request), so it never nests a second identical context.
+ *
+ * @template T
+ * @param {import("./requestState.js").RequestState | null} state
+ * @param {() => T} callback
+ * @returns {T}
+ */
+export function _runWithRequestState(state, callback) {
+  if (!state || requestStorage.getStore() === state) {
+    return callback();
+  }
+  return requestStorage.run(state, callback);
+}
+
+/**
+ * Internal; called by the outbound-HTTP wrapper (httpTracing.js) just before a request to
+ * `host`:`port` goes out. Returns the traceparent header value naming `spanId` (that request's own
+ * span) as the parent, or null when this request shouldn't carry one: outside a request, with
+ * propagateTraces off or `host` not a propagation target, or for a delivery to ForgeOps itself.
+ *
+ * @param {string} host
+ * @param {number | string | null | undefined} port
+ * @param {string} protocol
+ * @param {string} spanId
+ * @returns {string | null}
+ */
+export function _traceparentFor(host, port, protocol, spanId) {
+  const state = requestStorage.getStore();
+  if (!state) {
+    return null;
+  }
+  const config = getConfiguration();
+  if (config.isOwnHost(host, port, protocol) || !config.propagatesTraceTo(host)) {
+    return null;
+  }
+  return buildTraceparent(state.traceId, spanId);
+}
+
 /**
  * Internal; called by the Express/Fastify tracing integration (integrations/tracing.js), never
  * by host app code directly. Gives callback's own async call chain a fresh SpanBuffer, with its
@@ -261,7 +396,10 @@ export function _runWithSpanTrace(callback) {
   if (!config.trackTracing || !config.isEnabled()) {
     return callback();
   }
-  const buffer = new SpanBuffer(config);
+  // The trace id and remote parent come from the request's RequestState (see _runWithRequestState
+  // above), so this trace and any error event from the same request agree on the trace.
+  const state = requestStorage.getStore();
+  const buffer = new SpanBuffer(config, state ? { traceId: state.traceId, parentSpanId: state.parentSpanId } : {});
   return spanStorage.run(buffer, () => spanParentStorage.run(buffer.rootSpanId, callback));
 }
 
@@ -285,7 +423,11 @@ export function _finishSpanTrace(name, startedAt, durationMs) {
     return;
   }
   buffer.record({ spanId: buffer.rootSpanId, name, kind: "controller", startedAt, durationMs, root: true });
-  if (buffer.isSlow(getConfiguration().traceCaptureThresholdMs)) {
+  // An errored request's trace is always sent too, however fast it was, since the waterfall of
+  // what led up to an error is exactly what an issue page wants to show next to it. "Errored" means
+  // captureException ran during the request (the Express/Fastify error integrations call it too).
+  const errored = requestStorage.getStore()?.errored === true;
+  if (buffer.isSlow(getConfiguration().traceCaptureThresholdMs) || (errored && buffer.rootRecorded)) {
     getSpanQueue().push({ trace_id: buffer.traceId, spans: buffer.spans });
   }
 }
@@ -303,15 +445,17 @@ export function _finishSpanTrace(name, startedAt, durationMs) {
  * @param {Date} startedAt
  * @param {number} durationMs
  * @param {Record<string, unknown>} [data]
+ * @param {string} [spanId] only passed by the outbound-HTTP wrapper, which has to pick it before
+ *   the call goes out so the traceparent header it sends names this exact span
  */
-export function _recordSpan(name, kind, startedAt, durationMs, data = {}) {
+export function _recordSpan(name, kind, startedAt, durationMs, data = {}, spanId = randomSpanId()) {
   const config = getConfiguration();
   const buffer = spanStorage.getStore();
   if (!config.trackTracing || !buffer) {
     return;
   }
   const parentSpanId = spanParentStorage.getStore() ?? buffer.rootSpanId;
-  buffer.record({ spanId: randomSpanId(), parentSpanId, name, kind, startedAt, durationMs, data });
+  buffer.record({ spanId, parentSpanId, name, kind, startedAt, durationMs, data });
 }
 
 /**
@@ -363,7 +507,9 @@ export function init(options = {}) {
   // gems/forge_ops_tracker's own Railtie always applies Net::HTTP.prepend(Timing) regardless of
   // config, checking configuration.trackTracing fresh on every actual outbound call instead (see
   // _recordSpan above), never at install time.
-  installHttpTracing(_recordSpan);
+  installHttpTracing(_recordSpan, _traceparentFor);
+
+  startChangeSnapshot(config);
 
   return config;
 }
@@ -373,13 +519,20 @@ export function init(options = {}) {
  * established for this async call chain, if anything; pass one explicitly to override that for
  * this one report.
  *
+ * Inside a request the Express/Fastify integrations are handling, the event also carries the
+ * request's transaction_name, endpoint, and trace_id, and the request's trace is sent however fast
+ * it was.
+ *
  * @param {Error} error
  * @param {Record<string, unknown>} [context]
  * @param {Record<string, unknown> | null} [user]
  */
 export function captureException(error, context = {}, user = null) {
   const breadcrumbs = breadcrumbStorage.getStore()?.all() ?? [];
-  getReporter().report(error, context, user ?? userStorage.getStore()?.user ?? null, breadcrumbs);
+  const state = requestStorage.getStore();
+  state?.markErrored();
+  const request = state ? { transactionName: state.transactionName, endpoint: state.endpoint, traceId: state.traceId } : {};
+  getReporter().report(error, context, user ?? userStorage.getStore()?.user ?? null, breadcrumbs, request);
 }
 
 /**
@@ -537,8 +690,13 @@ function installProcessLevelHandlers() {
   process.on("unhandledRejection", unhandledRejectionListener);
 }
 
-/** @internal not part of the public API: resets module state between test cases */
-export function _resetForTesting() {
+/**
+ * @internal not part of the public API: resets module state between test cases. The startup change
+ * snapshot is left marked as already sent, so the many tests that init() an enabled client and
+ * count fetch calls don't see an extra one; pass { changeSnapshot: true } to let the next init()
+ * send it (see test/changes.test.js).
+ */
+export function _resetForTesting({ changeSnapshot = false } = {}) {
   if (uncaughtExceptionListener) {
     process.off("uncaughtExceptionMonitor", uncaughtExceptionListener);
   }
@@ -550,6 +708,8 @@ export function _resetForTesting() {
   sessionFlusher = null;
   performanceFlusher = null;
   spanQueue = null;
+  changeQueue = null;
+  changeSnapshotStarted = !changeSnapshot;
   metricBuffer?.discard();
   infrastructureMetricBuffer?.discard();
   metricBuffer = null;
@@ -565,6 +725,7 @@ export function _resetForTesting() {
   // sharing the same root context. disable() drops it and leaves the instance perfectly usable
   // again for the next run()/enterWith() call, confirmed directly, not assumed.
   breadcrumbStorage.disable();
+  requestStorage.disable();
   // Re-installed fresh on the very next init() call in whatever test runs next: without this,
   // http.request/https.request would stay wrapped by a closure over a *previous* test's own
   // _recordSpan reference forever (installHttpTracing's own guard only ever installs once per

package/src/integrations/express.js

@@ -1,4 +1,5 @@
-import { captureException, runWithUser } from "../index.js";
+import { _requestStateFor, _runWithRequestState, captureException, runWithUser } from "../index.js";
+import { describeExpressRoute } from "./tracing.js";
 
 /**
  * Express error-handling middleware. Register last, after all routes:
@@ -12,6 +13,12 @@ import { captureException, runWithUser } from "../index.js";
  * async route handlers to error-handling middleware automatically,
  * verified directly against a real async handler, not assumed. Only an
  * exception your own code catches and handles is invisible to this.
+ *
+ * The event carries the request's trace id, transaction name, and
+ * endpoint: the RequestState forgeOpsTrackerTracingExpressMiddleware
+ * already stashed on req when that's installed, or one created here from
+ * the request's own traceparent header when it isn't, so an unhandled
+ * error is linked across services either way.
  */
 export function forgeOpsTrackerExpressMiddleware(err, req, res, next) {
   // See integrations/sessionTracking.js's own comment: marks the request crashed before
@@ -20,10 +27,14 @@ export function forgeOpsTrackerExpressMiddleware(err, req, res, next) {
   // the time it checks.
   req._forgeOpsSessionCrashed = true;
 
-  captureException(err, {
-    path: req.path,
-    method: req.method,
-  });
+  const state = _requestStateFor(req, req.headers?.traceparent);
+  state?.describeWith(() => describeExpressRoute(req));
+  _runWithRequestState(state, () =>
+    captureException(err, {
+      path: req.path,
+      method: req.method,
+    }),
+  );
   next(err);
 }
 

package/src/integrations/fastify.js

@@ -1,4 +1,5 @@
-import { captureException } from "../index.js";
+import { _requestStateFor, _runWithRequestState, captureException } from "../index.js";
+import { fastifyRoutePattern } from "./tracing.js";
 
 /**
  * Called directly with your Fastify instance: not registered via
@@ -15,13 +16,25 @@ import { captureException } from "../index.js";
  * continues exactly as if this hook weren't registered. Only an
  * exception your own code catches and handles is invisible to this.
  *
+ * The event carries the request's trace id, transaction name, and
+ * endpoint: the RequestState registerForgeOpsTrackerTracing already
+ * created for this request when that's registered, or one created here
+ * from the request's own traceparent header when it isn't.
+ *
  * @param {import("fastify").FastifyInstance} fastify
  */
 export function registerForgeOpsTracker(fastify) {
   fastify.addHook("onError", async (request, reply, error) => {
-    captureException(error, {
-      path: request.url,
-      method: request.method,
-    });
+    const state = _requestStateFor(request, request.headers?.traceparent);
+    const route = fastifyRoutePattern(request);
+    if (state && route && state.transactionName === null) {
+      state.setRoute(`${request.method} ${route}`, `${request.method} ${route}`);
+    }
+    _runWithRequestState(state, () =>
+      captureException(error, {
+        path: request.url,
+        method: request.method,
+      }),
+    );
   });
 }

package/src/integrations/tracing.js

@@ -1,4 +1,23 @@
-import { _finishSpanTrace, _runWithSpanTrace } from "../index.js";
+import { _finishSpanTrace, _requestStateFor, _runWithRequestState, _runWithSpanTrace } from "../index.js";
+
+/**
+ * How an Express request is named once a route has matched: transactionName the same
+ * "<HTTP method> <route pattern>" the root span and performance samples use, endpoint the same
+ * route pattern. req.route.path is the pattern as declared on the router that matched it; for a
+ * router mounted with app.use("/api", router), that's the part declared on the router, without
+ * "/api": req.baseUrl is the literal matched mount path, which for a parameterized mount
+ * ("/users/:userId") would put a real id into a field that must never carry one. null before a
+ * route has matched (the event then leaves both fields out).
+ *
+ * @param {import("express").Request} req
+ */
+export function describeExpressRoute(req) {
+  if (!req.route) {
+    return null;
+  }
+  const name = `${req.method} ${req.route.path}`;
+  return { transactionName: name, endpoint: name };
+}
 
 /**
  * Express distributed-tracing middleware: wraps the rest of the request in _runWithSpanTrace
@@ -20,20 +39,33 @@ import { _finishSpanTrace, _runWithSpanTrace } from "../index.js";
  * actually finished and the root span's real total duration is known: nothing about a normal,
  * fast request costs a single byte over the wire, matching gems/forge_ops_tracker's own
  * Middleware::SpanTracing.
+ *
+ * Also publishes this request's RequestState (see requestState.js) whether or not trackTracing is
+ * on, so every request gets a trace id, continuing an incoming W3C traceparent header when there
+ * is one (its root span's parent is then the caller's span), and an error captured anywhere in
+ * the request carries it plus the matched route. Register it before your routes for that: an
+ * error thrown by a route registered ahead of it never sees this request's trace. Express only
+ * sets req.route once the matched handler starts, so the route is read lazily, whenever an error
+ * needs it (see RequestState#describeWith).
  */
 export function forgeOpsTrackerTracingExpressMiddleware(req, res, next) {
-  _runWithSpanTrace(() => {
-    const startedAt = new Date();
-    const start = performance.now();
+  const state = _requestStateFor(req, req.headers?.traceparent);
+  state?.describeWith(() => describeExpressRoute(req));
+
+  _runWithRequestState(state, () =>
+    _runWithSpanTrace(() => {
+      const startedAt = new Date();
+      const start = performance.now();
 
-    res.on("finish", () => {
-      const durationMs = performance.now() - start;
-      const transactionName = `${req.method} ${req.route?.path ?? req.path}`;
-      _finishSpanTrace(transactionName, startedAt, durationMs);
-    });
+      res.on("finish", () => {
+        const durationMs = performance.now() - start;
+        const transactionName = `${req.method} ${req.route?.path ?? req.path}`;
+        _finishSpanTrace(transactionName, startedAt, durationMs);
+      });
 
-    next();
-  });
+      next();
+    }),
+  );
 }
 
 /**
@@ -55,15 +87,29 @@ export function forgeOpsTrackerTracingExpressMiddleware(req, res, next) {
  * matched a route at all (a 404), the same "pattern first, literal path as the 404 fallback"
  * shape the Express integration above already takes.
  *
+ * Also publishes this request's RequestState (see requestState.js) whether or not trackTracing is
+ * on, the same as the Express middleware above: a trace id for every request, continuing an
+ * incoming W3C traceparent header. Fastify has already matched the route by onRequest, so the
+ * transaction name and endpoint are set right here, before any handler runs, and only from the
+ * matched pattern: a request that matched no route (a 404) leaves both out.
+ *
  * @param {import("fastify").FastifyInstance} fastify
  */
 export function registerForgeOpsTrackerTracing(fastify) {
   fastify.addHook("onRequest", (request, reply, done) => {
-    _runWithSpanTrace(() => {
-      request._forgeOpsSpanStartedAt = new Date();
-      request._forgeOpsSpanStart = performance.now();
-      done();
-    });
+    const state = _requestStateFor(request, request.headers?.traceparent);
+    const route = fastifyRoutePattern(request);
+    if (state && route) {
+      state.setRoute(`${request.method} ${route}`, `${request.method} ${route}`);
+    }
+
+    _runWithRequestState(state, () =>
+      _runWithSpanTrace(() => {
+        request._forgeOpsSpanStartedAt = new Date();
+        request._forgeOpsSpanStart = performance.now();
+        done();
+      }),
+    );
   });
 
   fastify.addHook("onResponse", async (request) => {
@@ -78,3 +124,14 @@ export function registerForgeOpsTrackerTracing(fastify) {
     _finishSpanTrace(transactionName, request._forgeOpsSpanStartedAt, durationMs);
   });
 }
+
+/**
+ * Fastify's matched route pattern ("/orders/:id", prefixes included), or undefined for a request
+ * that matched no route: request.routeOptions.url, falling back to the older request.routerPath.
+ *
+ * @param {import("fastify").FastifyRequest} request
+ * @returns {string | undefined}
+ */
+export function fastifyRoutePattern(request) {
+  return request.routeOptions?.url ?? request.routerPath ?? undefined;
+}

package/src/reporter.js

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

package/src/requestState.js

@@ -0,0 +1,117 @@
+import { generateTraceId, parseTraceparent } from "./traceParent.js";
+
+/**
+ * Everything this client knows about the current request that isn't already owned by one of the
+ * older, single-purpose AsyncLocalStorage instances (the user, the breadcrumb trail, the span
+ * buffer): which trace it belongs to, which remote span called it (if any), what it's called, and
+ * whether it errored. One instance per request, published by the Express/Fastify integrations
+ * (see _runWithRequestState in index.js) so captureException, the tracing integration, and the
+ * outbound-HTTP wrapper can all reach it. Ported from
+ * gems/forge_ops_tracker/lib/forge_ops_tracker/request_state.rb.
+ *
+ * The traceId exists for every request, not only when trackTracing is on: it's also what an error
+ * event carries so ForgeOps can link it to errors reported by other services taking part in the
+ * same trace, which works on any plan and with tracing off entirely.
+ *
+ * Also stashed on the framework's own request object (see requestStateFor), the Node equivalent of
+ * the Ruby gem memoizing it in the Rack env: an error-handling middleware that runs outside the
+ * tracing middleware's async context still finds the same instance there.
+ */
+export class RequestState {
+  traceId;
+  parentSpanId;
+  errored = false;
+  #describe;
+  #transactionName = null;
+  #endpoint = null;
+
+  /**
+   * @param {{ traceId?: string, parentSpanId?: string | null }} [ids]
+   */
+  constructor({ traceId = generateTraceId(), parentSpanId = null } = {}) {
+    this.traceId = traceId;
+    this.parentSpanId = parentSpanId;
+  }
+
+  /**
+   * Continues the caller's trace when the request arrived with a usable W3C traceparent header,
+   * remembering the caller's span as this request's remote parent; starts a fresh trace otherwise.
+   * @param {unknown} traceparent
+   */
+  static fromTraceparent(traceparent) {
+    const incoming = parseTraceparent(traceparent);
+    return incoming === null ? new RequestState() : new RequestState(incoming);
+  }
+
+  /**
+   * How to name this request, read lazily, each time an error needs it: Express only sets req.route
+   * once the matched route's own handler starts running, with no app-level hook in between, so the
+   * integration hands over a function that reads it then instead of a name it can't know yet at
+   * request start. Returns null (and the event leaves both fields out) until a route has matched.
+   * @param {() => { transactionName: string, endpoint: string } | null} describe
+   */
+  describeWith(describe) {
+    this.#describe = describe;
+  }
+
+  /**
+   * Sets both names outright, for a framework that already knows the matched route when the
+   * request starts (Fastify's onRequest).
+   * @param {string} transactionName
+   * @param {string} endpoint
+   */
+  setRoute(transactionName, endpoint) {
+    this.#transactionName = transactionName;
+    this.#endpoint = endpoint;
+  }
+
+  /** @returns {string | null} */
+  get transactionName() {
+    return this.#transactionName ?? this.#described()?.transactionName ?? null;
+  }
+
+  /** @returns {string | null} */
+  get endpoint() {
+    return this.#endpoint ?? this.#described()?.endpoint ?? null;
+  }
+
+  markErrored() {
+    this.errored = true;
+  }
+
+  #described() {
+    try {
+      return this.#describe?.() ?? null;
+    } catch {
+      return null;
+    }
+  }
+}
+
+const REQUEST_STATE_KEY = Symbol.for("forge-ops-tracker.requestState");
+
+/**
+ * The RequestState memoized on `request` (an Express req or a Fastify request), created from its
+ * traceparent header on first use: whichever integration reaches a request first creates it, and
+ * every other one gets the identical instance back, so they all agree on one trace id. A symbol
+ * key, not a plain property: invisible to the app's own enumeration and serialization of req.
+ *
+ * @param {object} request
+ * @param {unknown} traceparent the incoming traceparent header's raw value
+ * @returns {RequestState}
+ */
+export function requestStateFor(request, traceparent) {
+  if (request[REQUEST_STATE_KEY] === undefined) {
+    request[REQUEST_STATE_KEY] = RequestState.fromTraceparent(traceparent);
+  }
+  return request[REQUEST_STATE_KEY];
+}
+
+/**
+ * The RequestState already memoized on `request`, if any integration created one.
+ * @param {object} request
+ * @returns {RequestState | undefined}
+ */
+export function existingRequestState(request) {
+  return request?.[REQUEST_STATE_KEY];
+}