@forge-ops/tracker 0.5.0 → 0.9.1

package/README.md

@@ -1,6 +1,6 @@
 # @forge-ops/tracker
 
-Node.js error reporting client for a [ForgeOps](../../) instance.
+Node.js error reporting client for [ForgeOps](https://getforgeops.net).
 Requires Node 18+ (for global `fetch`). It captures uncaught exceptions, unhandled promise
 rejections, and explicitly reported errors, builds a backtrace, scrubs likely PII, and delivers
 events to ForgeOps over HTTP without blocking the request or process that raised them.
@@ -20,7 +20,7 @@ variable or explicitly:
 import * as forgeOpsTracker from "@forge-ops/tracker";
 
 forgeOpsTracker.init({
-  dsn: "https://<api_key>@your-forgeops-host/api/v1/events", // or leave unset to read FORGE_OPS_DSN
+  dsn: "https://<api_key>@getforgeops.net/api/v1/events", // or leave unset to read FORGE_OPS_DSN
   release: "...",
   environment: "production",
 });
@@ -32,11 +32,13 @@ overridden by passing it in the options object.
 ### Express
 
 ```js
+import { forgeOpsTrackerBreadcrumbContextExpressMiddleware } from "@forge-ops/tracker/integrations/breadcrumb-context";
 import { forgeOpsTrackerSessionTrackingExpressMiddleware } from "@forge-ops/tracker/integrations/session-tracking";
 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(forgeOpsTrackerBreadcrumbContextExpressMiddleware); // first, before everything else below
+app.use(forgeOpsTrackerSessionTrackingExpressMiddleware);
 app.use(forgeOpsTrackerPerformanceExpressMiddleware); // order relative to routes doesn't matter
 app.use(forgeOpsTrackerUserContextMiddleware); // after Passport's own session middleware, if used
 // ...routes...
@@ -51,8 +53,10 @@ for async handlers; each route would need its own try/catch there instead.
 ### Fastify
 
 ```js
+import { registerForgeOpsTrackerBreadcrumbContext } from "@forge-ops/tracker/integrations/breadcrumb-context";
 import { registerForgeOpsTracker } from "@forge-ops/tracker/integrations/fastify";
 
+registerForgeOpsTrackerBreadcrumbContext(app); // first, before registerForgeOpsTracker
 registerForgeOpsTracker(app); // called directly, not via app.register()
 ```
 
@@ -143,6 +147,57 @@ just through a synchronous call chain. Composes with the manual API above rather
 it: call `runWithUser` yourself for a route (or a custom auth setup this can't detect) that needs
 to override what was auto-detected.
 
+## Breadcrumbs
+
+A trail of what happened right before an error. With `forgeOpsTrackerBreadcrumbContextExpressMiddleware`/
+`registerForgeOpsTrackerBreadcrumbContext` installed (see the Express/Fastify snippets above), every
+request gets its own trail, and the Express performance middleware records a `"controller"`
+breadcrumb into it automatically, no further setup needed. Shows up alongside the error on an
+issue's own detail page.
+
+```js
+forgeOpsTracker.init({
+  dsn: "...",
+  trackBreadcrumbs: false, // opt out of the automatic sources entirely
+  maxBreadcrumbs: 30, // oldest entry dropped once this many have accumulated in one request
+});
+```
+
+Add your own by hand, regardless of whether the automatic sources are on:
+
+```js
+forgeOpsTracker.addBreadcrumb("charged card", { category: "billing", data: { orderId: order.id } });
+```
+
+`category` defaults to `"custom"`, `level` to `"info"` (`"debug"`/`"info"`/`"warning"`/`"error"` are
+the four levels the automatic sources themselves use too), and `data` to `{}`. Works outside a
+request entirely too (a plain script, a worker with no breadcrumb-context middleware/hook
+installed): the buffer it adds to is created lazily wherever it's first called, the same "works
+standalone, no specific setup required" shape the manual API in every other SDK in this repo
+already has.
+
+Each request gets its own fresh, bounded trail (a ring buffer capped at `maxBreadcrumbs`, oldest
+entry dropped once full), scoped with a second `AsyncLocalStorage` instance, the same mechanism
+`runWithUser()`/the user-context middleware already use for the affected user: Node is
+single-threaded, so a plain module-level variable would leak one request's trail into another's
+interleaved on the same event loop, exactly the bug `AsyncLocalStorage` avoids here. Confirmed
+directly, with a real Express app and a real Fastify app, each running two genuinely concurrent,
+interleaved requests, that one request's trail never bleeds into the other's, and that a
+breadcrumb recorded deep inside an awaited route handler (or the performance middleware's own
+`res.on("finish")` listener, which fires later still) is still visible to `captureException()` at
+the end of that same request. Unlike the affected user above, a breadcrumb's `message`/`data`
+**is** scrubbed for likely PII: console-style/query/request trail entries are exactly the kind of
+free text (a bind parameter showing up in a message, a URL with a token in it) the scrubber exists
+to catch, not a deliberately-structured field the way `user` is.
+
+There's currently no query-level automatic breadcrumb source: this client has no ORM/DB driver
+integration to hang one off of yet, the same reason there's no query-level performance
+instrumentation either. Fastify also gets no automatic `"controller"` breadcrumb today, since
+there's no Fastify performance/timing integration in this client for one to ride alongside (see
+"Performance monitoring" below); `registerForgeOpsTrackerBreadcrumbContext` still gives Fastify
+requests their own trail, so `addBreadcrumb()` calls from inside a Fastify route handler work
+correctly and show up on that request's error.
+
 ## Delivery: an async loop, not a thread
 
 `DeliveryQueue` here isn't a background *thread*: Node is single-threaded. But a Node process is
@@ -178,6 +233,8 @@ and redacted before the payload ever leaves this process. ForgeOps itself scrubs
 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.
+Breadcrumbs (see "Breadcrumbs" above) are *not* exempt, unlike the user: they're scrubbed the same
+as the message/backtrace/context.
 
 To disable it:
 
@@ -240,7 +297,15 @@ runs, diffed once the response finishes) so a dashboard widget on ForgeOps can s
 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.
+transaction on the same kind of `setInterval` timer session tracking above uses. The same
+middleware also records a `"controller"` breadcrumb (see "Breadcrumbs" above), gated on
+`trackBreadcrumbs` independently of `trackPerformance`: turning either one off doesn't affect the
+other.
+
+Each aggregate also carries a small latency histogram (a count per fixed latency bucket: 50, 100,
+250, 500, 1000, 2500, 5000 and 10000ms, plus an overflow bucket), so ForgeOps can show an
+approximate p50/p95/p99 per transaction, not just an average. Percentiles are accurate to the width
+of whichever bucket a duration falls into; the SDK never stores the individual durations.
 
 ```js
 forgeOpsTracker.init({
@@ -259,6 +324,100 @@ Fastify isn't supported yet: unlike session tracking, there's no existing reques
 to build this on for Fastify today, so it's a separate piece of work rather than something this
 version already covers.
 
+## Custom metrics and infrastructure monitoring
+
+Two explicit calls (nothing is automatic, so there is no `track*` flag): a business event you name
+yourself, and a reading from one of your own hosts.
+
+```js
+forgeOpsTracker.captureMetric("signup"); // value defaults to 1: a bare counter
+forgeOpsTracker.captureMetric("payment", 49); // a real magnitude; it may be negative (a refund)
+
+forgeOpsTracker.captureInfrastructureMetric("cpu", 0.42); // hostname defaults to serverName
+forgeOpsTracker.captureInfrastructureMetric("disk", 0.81, { hostname: "db-1" });
+await forgeOpsTracker.flushMetrics(); // optional: send right now
+```
+
+Each capture is buffered and flushed as one batch every `metricFlushIntervalMs` /
+`infrastructureMetricFlushIntervalMs` (60000 by default) on an unref'd `setInterval` timer, and once
+more when the event loop drains (`beforeExit`, which does not change how the process exits the way a
+`SIGTERM` listener would), so a short-lived cron script that captures a few readings and ends needs
+nothing more. Call `await flushMetrics()` if it exits another way (`process.exit()`). Every entry is
+stored as it was captured (a signup is a row, not a running total), so a count or sum you compute later
+is exact. Both are a no-op when the client isn't enabled for the environment.
+
+A failed delivery keeps every entry for the next flush, and an entry captured while a delivery is in
+flight is kept too (the Ruby gem's own buffer loses it). The buffer holds at most 1000 entries per
+kind and drops further ones until a flush succeeds, since a plan without the feature rejects every
+flush and would otherwise grow it for as long as the process lives. A NaN or infinite value is
+dropped at capture: `JSON.stringify` turns it into `null` and the server would reject the whole
+batch behind it. Requires a ForgeOps plan that includes custom metrics / infrastructure monitoring.
+
+## Distributed tracing
+
+For one slow 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.
+
+```js
+import { forgeOpsTrackerTracingExpressMiddleware } from "@forge-ops/tracker/integrations/tracing";
+
+app.use(forgeOpsTrackerTracingExpressMiddleware);
+```
+
+```js
+import { registerForgeOpsTrackerTracing } from "@forge-ops/tracker/integrations/tracing";
+
+registerForgeOpsTrackerTracing(fastify);
+```
+
+This is the whole point of the feature, so it's worth being explicit about: a request's own trace
+is only ever built, let alone sent, once its own root span's duration crosses a threshold, decided
+entirely client-side before a single byte goes over the wire. A normal, fast request costs
+nothing extra.
+
+```js
+forgeOpsTracker.init({
+  dsn: "...",
+  trackTracing: false, // opt out entirely
+  traceCaptureThresholdMs: 500, // default 1000
+});
+```
+
+Outbound HTTP calls made via Node's built-in `http`/`https` modules (and so anything built on top
+of them, like `axios` or `node-fetch`) nest in automatically, no extra setup: `init()` always
+installs this hook, the same way `gems/forge_ops_tracker`'s own `Net::HTTP.prepend` always applies
+regardless of config, checking `trackTracing` fresh on every actual call rather than at install
+time. Every span name (`"GET api.stripe.com"`) is low-cardinality by design, the same as every
+transaction name elsewhere in this SDK: never the raw URL path or query string, since either can
+carry a customer's own id or a secret.
+
+There's no way to auto-detect "this is a logically distinct service layer" the way an outbound
+HTTP call already has a real hook to extend, so wrap your own service-layer code by hand to have
+it show up as its own span:
+
+```js
+await forgeOpsTracker.span("PaymentService.charge", () => chargeCard(order));
+```
+
+Works with both synchronous and `async` callbacks (the returned promise, if any, is awaited
+before the span is recorded), and nests correctly even when two spans are awaited concurrently in
+the same request (`Promise.all`), since span nesting is tracked per async execution branch via
+`AsyncLocalStorage`, not a single shared stack. `kind` accepts `"controller"`, `"service"` (the
+default), `"database"`, `"redis"`, `"http"`, `"job"`, or `"other"`, and takes an options object:
+`forgeOpsTracker.span("PaymentService.charge", fn, { kind: "service", data: {} })`. A no-op
+outside of a request currently being traced (a plain script, a request that already finished) or
+with `trackTracing` off: it just runs the callback and records nothing, never throwing.
+
+Requires a ForgeOps plan that includes distributed tracing; on a plan that doesn't, a captured
+trace is simply rejected server-side and dropped, exactly like any other delivery failure.
+
+**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.
+
 ## Running the tests
 
 ```bash

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@forge-ops/tracker",
-  "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.",
+  "version": "0.9.1",
+  "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",
   "exports": {
@@ -9,7 +9,9 @@
     "./integrations/express": "./src/integrations/express.js",
     "./integrations/fastify": "./src/integrations/fastify.js",
     "./integrations/session-tracking": "./src/integrations/sessionTracking.js",
-    "./integrations/performance": "./src/integrations/performance.js"
+    "./integrations/performance": "./src/integrations/performance.js",
+    "./integrations/breadcrumb-context": "./src/integrations/breadcrumbContext.js",
+    "./integrations/tracing": "./src/integrations/tracing.js"
   },
   "engines": {
     "node": ">=18"

package/src/breadcrumbBuffer.js

@@ -0,0 +1,48 @@
+/**
+ * A bounded, in-order trail of whatever happened recently in this request: the controller/route
+ * lifecycle, plus anything added by hand via addBreadcrumb() in index.js, recorded automatically
+ * once a breadcrumb-context middleware/hook (see integrations/breadcrumbContext.js) gives the
+ * request its own buffer to accumulate into. Ported from
+ * gems/forge_ops_tracker/lib/forge_ops_tracker/breadcrumb_buffer.rb: the same ring buffer contract
+ * (capped at Configuration#maxBreadcrumbs, oldest entry dropped once full), but scoped per request
+ * via AsyncLocalStorage rather than Ruby's Thread.current or Python's contextvars.ContextVar; see
+ * index.js's own breadcrumbStorage comment for why that's the correct mechanism here.
+ */
+export class BreadcrumbBuffer {
+  #configuration;
+  #entries = [];
+
+  constructor(configuration) {
+    this.#configuration = configuration;
+  }
+
+  /**
+   * @param {string} message
+   * @param {{ category?: string, level?: string, data?: Record<string, unknown> }} [options]
+   */
+  add(message, { category = "custom", level = "info", data = {} } = {}) {
+    // Read fresh on every add, not captured once at construction: the same reasoning
+    // DeliveryQueue re-reads Configuration#queueSize on every push(), so a config change from
+    // init() takes effect on whatever's added next, not just on a buffer created earlier.
+    const maxSize = Math.max(this.#configuration.maxBreadcrumbs, 0);
+    if (maxSize === 0) {
+      return;
+    }
+
+    this.#entries.push({
+      category: String(category),
+      message: String(message),
+      level: String(level),
+      timestamp: new Date().toISOString().replace(/\.\d+Z$/, "Z"),
+      data: data ?? {},
+    });
+    while (this.#entries.length > maxSize) {
+      this.#entries.shift();
+    }
+  }
+
+  /** @returns {Array<Record<string, unknown>>} a copy, never the internal array itself */
+  all() {
+    return [...this.#entries];
+  }
+}

package/src/client.js

@@ -39,6 +39,35 @@ export class Client {
     return this.#post(this.#configuration.performanceSamplesUri(), { samples });
   }
 
+  /**
+   * One whole captured trace (a trace_id plus every span belonging to it) delivered as one POST,
+   * unlike deliverPerformanceSamples' own batched-over-a-time-window shape: a trace is already a
+   * complete, immediately relevant unit the moment its own request finishes, matching
+   * Api::V1::SpansController's own expected body and gems/forge_ops_tracker's own
+   * Client#deliver_spans.
+   * @param {{ trace_id: string, spans: Array<Record<string, unknown>> }} payload
+   */
+  async deliverSpans(payload) {
+    return this.#post(this.#configuration.spansUri(), payload);
+  }
+
+  /**
+   * A batch of individual capture_metric entries, posted as { metrics }, matching
+   * Api::V1::CustomMetricsController's own expected body.
+   * @param {Record<string, unknown>[]} metrics
+   */
+  async deliverMetrics(metrics) {
+    return this.#post(this.#configuration.customMetricsUri(), { metrics });
+  }
+
+  /**
+   * Same again for infrastructure readings; see Api::V1::InfrastructureMetricsController.
+   * @param {Record<string, unknown>[]} metrics
+   */
+  async deliverInfrastructureMetrics(metrics) {
+    return this.#post(this.#configuration.infrastructureMetricsUri(), { metrics });
+  }
+
   /**
    * @param {string | null} uri
    * @param {Record<string, unknown>} payload

package/src/configuration.js

@@ -65,6 +65,42 @@ export class Configuration {
    * one small batch on this interval" reasoning as sessionFlushIntervalMs above. */
   performanceFlushIntervalMs = 60000;
 
+  /** Milliseconds between flushes of the buffered captureMetric()/captureInfrastructureMetric()
+   * entries (see metricBuffer.js). No trackMetrics flag the way trackPerformance has one: these are
+   * explicit calls the host app's own code makes, not automatic instrumentation, so there is nothing
+   * to turn off that simply not calling them doesn't already do. */
+  metricFlushIntervalMs = 60000;
+  infrastructureMetricFlushIntervalMs = 60000;
+
+  /**
+   * Whether the Express/Fastify integrations give every request its own breadcrumb trail, and
+   * whatever automatic sources this client already times (currently just the Express
+   * controller/route lifecycle; see integrations/performance.js) also record a breadcrumb
+   * alongside the timing they already do. On by default, the same posture trackSessions/
+   * trackPerformance above already have. addBreadcrumb() itself is never gated by this: only the
+   * automatic sources are, matching gems/forge_ops_tracker's own track_breadcrumbs.
+   */
+  trackBreadcrumbs = true;
+  /** Oldest entry dropped once this many have accumulated in a single request: the same "bounded
+   * ring buffer, not an unbounded log" reasoning sdks/typescript's own Configuration#maxBreadcrumbs
+   * already documents. */
+  maxBreadcrumbs = 30;
+
+  /**
+   * Whether the Express/Fastify integrations capture one request's own full nested call tree (its
+   * root span plus every service/database/http/redis span recorded underneath it) as a
+   * distributed trace, once that request's own total duration crosses traceCaptureThresholdMs
+   * below. On by default, the same "on unless you turn it off" posture every other automatic
+   * instrumentation flag above already has; a fast request still costs nothing regardless, since
+   * the send-or-don't decision happens after the fact, per request, not by disabling this flag.
+   */
+  trackTracing = true;
+  /** A request's own root span duration has to reach at least this many milliseconds before its
+   * whole trace is sent at all; this is the entire point of the feature, not a sampling knob: a
+   * normal, fast request never costs a single byte over the wire. Matches
+   * gems/forge_ops_tracker's own Configuration#trace_capture_threshold_ms default. */
+  traceCaptureThresholdMs = 1000;
+
   /** @returns {string | null} */
   apiKey() {
     const parsed = this.#parsedDsn();
@@ -115,6 +151,43 @@ export class Configuration {
     return uri.replace(/\/events$/, "/performance_samples");
   }
 
+  /**
+   * Same derivation again, swapping the trailing /events for /custom_metrics.
+   * @returns {string | null}
+   */
+  customMetricsUri() {
+    const uri = this.ingestionUri();
+    if (!uri) {
+      return null;
+    }
+    return uri.replace(/\/events$/, "/custom_metrics");
+  }
+
+  /**
+   * Same derivation again, swapping the trailing /events for /infrastructure_metrics.
+   * @returns {string | null}
+   */
+  infrastructureMetricsUri() {
+    const uri = this.ingestionUri();
+    if (!uri) {
+      return null;
+    }
+    return uri.replace(/\/events$/, "/infrastructure_metrics");
+  }
+
+  /**
+   * Same derivation again, swapping the trailing /events for /spans: one captured trace, one POST,
+   * matching gems/forge_ops_tracker's own Configuration#spans_uri.
+   * @returns {string | null}
+   */
+  spansUri() {
+    const uri = this.ingestionUri();
+    if (!uri) {
+      return null;
+    }
+    return uri.replace(/\/events$/, "/spans");
+  }
+
   /** @returns {boolean} */
   isEnabled() {
     return Boolean(this.dsn) && this.apiKey() !== null && this.enabledEnvironments.has(this.environment);

package/src/deliveryQueue.js

@@ -23,19 +23,32 @@
 export class DeliveryQueue {
   #configuration;
   #client;
+  #deliverMethod;
+  #label;
   #queue = [];
   #processing = false;
 
-  constructor(configuration, client) {
+  /**
+   * deliverMethod/label default to Client#deliver's own "event" shape, so every existing call
+   * site (Reporter, and every test written against it) keeps working unchanged. Spans reuse this
+   * same queue rather than a second, near-identical class (the shape gems/forge_ops_tracker's own
+   * SpanQueue takes instead, since Ruby's DeliveryQueue has no such parameter to extend): only the
+   * client method actually called, and the word used in a dropped/failed log line, ever differ
+   * between an error event and a captured trace.
+   * @param {{ deliverMethod?: string, label?: string }} [options]
+   */
+  constructor(configuration, client, { deliverMethod = "deliver", label = "event" } = {}) {
     this.#configuration = configuration;
     this.#client = client;
+    this.#deliverMethod = deliverMethod;
+    this.#label = label;
   }
 
   /** @param {Record<string, unknown>} payload */
   push(payload) {
     const maxSize = Math.max(1, this.#configuration.queueSize);
     if (this.#queue.length >= maxSize) {
-      this.#configuration.log("[forge-ops-tracker] delivery queue full, dropping event");
+      this.#configuration.log(`[forge-ops-tracker] delivery queue full, dropping ${this.#label}`);
       return false;
     }
 
@@ -59,7 +72,7 @@ export class DeliveryQueue {
     while (this.#queue.length > 0) {
       const payload = this.#queue.shift();
       try {
-        await this.#client.deliver(payload);
+        await this.#client[this.#deliverMethod](payload);
       } catch (e) {
         // Per-item, not wrapping the whole loop: one bad delivery must
         // not stop every event queued after it.

package/src/eventBuilder.js

@@ -47,8 +47,9 @@ export class EventBuilder {
    * @param {Error} error
    * @param {Record<string, unknown>} [context]
    * @param {Record<string, unknown> | null} [user]
+   * @param {Array<Record<string, unknown>>} [breadcrumbs]
    */
-  build(error, context = {}, user = null) {
+  build(error, context = {}, user = null, breadcrumbs = []) {
     const payload = {
       exception_class: error?.name ?? "Error",
       message: error?.message ?? "",
@@ -64,6 +65,9 @@ export class EventBuilder {
     if (user && Object.keys(user).length > 0) {
       payload.user = { ...user };
     }
+    if (breadcrumbs && breadcrumbs.length > 0) {
+      payload.breadcrumbs = [...breadcrumbs];
+    }
 
     return this.#configuration.scrubPii ? this.#scrub(payload) : payload;
   }
@@ -74,15 +78,23 @@ export class EventBuilder {
   // 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.
+  // carry. breadcrumbs is *not* exempt, unlike user: console-style/query/
+  // request trail entries are exactly the kind of free text (a bind
+  // parameter showing up in a message, a URL with a token in it) the
+  // scrubber exists to catch, matching the server's own
+  // api/v1/events_controller.rb treatment of this field.
   #scrub(payload) {
-    return {
+    const scrubbed = {
       ...payload,
       message: scrubString(payload.message),
       backtrace: payload.backtrace.map((frame) => this.#scrubFrame(frame)),
       context: scrub(payload.context),
       tags: scrub(payload.tags),
     };
+    if ("breadcrumbs" in payload) {
+      scrubbed.breadcrumbs = scrub(payload.breadcrumbs);
+    }
+    return scrubbed;
   }
 
   #scrubFrame(frame) {

package/src/histogramBucketer.js

@@ -0,0 +1,26 @@
+/**
+ * Buckets a single duration into one of a fixed set of latency-range labels, the building block
+ * PerformanceFlusher uses to accumulate an approximate distribution (not just count/sum/max)
+ * alongside every transaction bucket it already tallies. The server merges these counts across
+ * matching samples at read time and walks cumulative counts to approximate a percentile, accurate
+ * to the bucket width: this SDK never stores the raw duration list a true percentile would need.
+ * Ported from gems/forge_ops_tracker/lib/forge_ops_tracker/histogram_bucketer.rb.
+ *
+ * BOUNDARIES_MS is duplicated on the server side, in app/services/histogram_percentile.rb. Change
+ * one, change the other, or a released SDK version and the server it talks to would silently
+ * disagree about what each bucket label means.
+ */
+export const BOUNDARIES_MS = Object.freeze([50, 100, 250, 500, 1000, 2500, 5000, 10000]);
+
+/**
+ * Returns the label (a string) of the smallest boundary durationMs fits under, or "inf" for
+ * anything larger than the largest boundary. A string, not a number: this travels as a JSON
+ * object key once flushed, and JSON object keys are always strings.
+ *
+ * @param {number} durationMs
+ * @returns {string}
+ */
+export function bucketFor(durationMs) {
+  const boundary = BOUNDARIES_MS.find((b) => durationMs <= b);
+  return boundary === undefined ? "inf" : String(boundary);
+}

package/src/httpTracing.js

@@ -0,0 +1,104 @@
+import http from "node:http";
+import https from "node:https";
+
+let installed = false;
+let originalHttpRequest = null;
+let originalHttpsRequest = null;
+
+/**
+ * Wraps Node's own http/https request() exactly once for the life of the process (idempotent, see
+ * the installed guard below): most third-party HTTP clients (axios, node-fetch, undici's own
+ * legacy adapter, ...) ultimately call through one of these two functions, so wrapping here
+ * covers those as a side effect without a separate integration per library, the same reasoning
+ * gems/forge_ops_tracker's own Net::HTTP.prepend(Timing) documents for Ruby's own HTTP ecosystem.
+ * Known, honest gap this shares with that Ruby wrapper's own module-prepend approach: code that
+ * destructures `request` off `http`/`https` (or otherwise captures a reference) *before*
+ * installHttpTracing runs keeps calling the original, unwrapped function; calling init() before
+ * any other library gets required, the normal way an app entry point is written anyway, avoids
+ * this in practice.
+ *
+ * recordSpan is passed in as a plain parameter rather than imported directly from index.js: this
+ * module gets installed FROM index.js's own init(), so importing index.js back from here would
+ * create a circular module dependency index.js has never needed before, for no real benefit over
+ * just passing the one function actually used.
+ *
+ * @param {(name: string, kind: string, startedAt: Date, durationMs: number, data?: Record<string, unknown>) => void} recordSpan
+ */
+export function installHttpTracing(recordSpan) {
+  if (installed) {
+    return;
+  }
+  installed = true;
+  originalHttpRequest = http.request;
+  originalHttpsRequest = https.request;
+  http.request = wrap(originalHttpRequest, recordSpan);
+  https.request = wrap(originalHttpsRequest, recordSpan);
+}
+
+/** @internal test-only: restores http/https.request exactly as installHttpTracing found them. */
+export function _uninstallHttpTracing() {
+  if (!installed) {
+    return;
+  }
+  http.request = originalHttpRequest;
+  https.request = originalHttpsRequest;
+  installed = false;
+  originalHttpRequest = null;
+  originalHttpsRequest = null;
+}
+
+function wrap(originalRequest, recordSpan) {
+  return function patchedRequest(...args) {
+    const startedAt = new Date();
+    const start = performance.now();
+    const req = originalRequest.apply(this, args);
+    const { method, host } = describeRequest(args);
+
+    // "response" and "error" are mutually exclusive on a real ClientRequest, but guarded anyway:
+    // recording twice for the same outbound call would double it up in the waterfall.
+    let finished = false;
+    const finish = (status) => {
+      if (finished) {
+        return;
+      }
+      finished = true;
+      recordSpan(`${method} ${host}`, "http", startedAt, performance.now() - start, status === undefined ? {} : { status });
+    };
+
+    // No status at all means the request itself failed (DNS, connection refused, timeout) before
+    // any response ever came back: recorded regardless, an honest "this dependency call never
+    // completed" span rather than silently dropping it.
+    req.once("response", (res) => finish(res.statusCode));
+    req.once("error", () => finish());
+
+    return req;
+  };
+}
+
+/**
+ * Best-effort parse of whatever calling convention produced this request (a bare options object,
+ * a URL string/object plus an optional options object, either form optionally followed by a
+ * callback): only ever used to build a low-cardinality "<METHOD> <host>" label, never to read the
+ * path or query string a customer's own request carries (that could hold a customer's own id or
+ * a secret), the same reasoning every other transaction_name/span name in this client already
+ * follows.
+ * @param {unknown[]} args
+ */
+function describeRequest(args) {
+  const [first, second] = args;
+  const options = {};
+
+  if (typeof first === "string" || first instanceof URL) {
+    const url = typeof first === "string" ? new URL(first) : first;
+    options.host = url.hostname;
+    if (second && typeof second === "object") {
+      Object.assign(options, second);
+    }
+  } else if (first && typeof first === "object") {
+    Object.assign(options, first);
+  }
+
+  const method = String(options.method ?? "GET").toUpperCase();
+  const host = options.host ?? options.hostname ?? "unknown";
+  return { method, host };
+}