@forge-ops/tracker 0.10.0 → 0.12.0

package/README.md

@@ -113,6 +113,28 @@ 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.
 
+## Where an error happened
+
+An error reported during a request carries three extra fields:
+
+- `transaction_name`: the method and the route pattern, `"GET /orders/:id"`, the same name
+  performance monitoring and traces use.
+- `endpoint`: the method and the route as declared, `"GET /orders/:id"`. Never the literal path, so
+  an id or a token in the URL never ends up here. On Express, it's the route 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`, since the mount path Express exposes is the literal
+  matched one.
+- `trace_id`: the request's W3C trace id, which ForgeOps uses to link this error to errors that
+  other services reported for the same trace (see "Following a request across services" below).
+
+Register `forgeOpsTrackerTracingExpressMiddleware` before your routes, or call
+`registerForgeOpsTrackerTracing(app)` on Fastify (see "Distributed tracing" below), for these to be
+set on an error you capture yourself inside a handler; Fastify knows the route before any handler
+runs, Express as soon as the matched handler starts. `forgeOpsTrackerExpressMiddleware` and
+`registerForgeOpsTracker` add them to an unhandled error on their own. They're left out entirely
+outside a request (a script, a worker), and they're never PII-scrubbed, like `environment` and
+`release`: they're structured fields, not free text.
+
 ## Identifying users
 
 ```js
@@ -353,9 +375,59 @@ flush and would otherwise grow it for as long as the process lives. A NaN or inf
 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.
 
+## What changed
+
+ForgeOps can show what changed in your system next to the errors and slowdowns that followed it.
+Two ways in:
+
+**Record a change yourself** when something changes that no deploy captures, like a feature flag
+flipped, a config value edited, or a migration run by hand:
+
+```js
+import * as forgeOpsTracker from "@forge-ops/tracker";
+
+forgeOpsTracker.recordChange({
+  kind: "feature_flag", // feature_flag, config, migration, dependency, infrastructure, or other
+  title: "Enabled new_checkout for 10% of users",
+  details: { flag: "new_checkout", rolloutPercent: 10 },
+  actor: "ops@example.com",
+  url: "https://flags.example.com/new_checkout",
+});
+```
+
+`kind` and `title` are required; `details`, `environment` (defaults to the configured one),
+`service`, `actor`, `url`, `id` (an idempotency key, so sending the same change twice records it
+once), and `occurredAt` (a `Date` or ISO 8601 string, defaulting to now) are optional. An unknown
+`kind` is sent as `other`. It's queued and delivered on the same async loop as error events, so it
+never slows down the caller, never throws, and is a no-op when the client isn't enabled for the
+environment.
+
+**Changes between deploys are detected for you.** Once per process, `init()` schedules a snapshot
+of what the process is running: the Node version, and each of the `dependencies` in your app's
+`package.json` (read from `appRoot`, the working directory by default) resolved to the version
+actually installed in `node_modules`. ForgeOps compares it with the previous boot's and records
+whatever changed, such as a package upgrade. It's sent on a later event-loop turn, so startup never
+waits on it.
+
+```js
+forgeOpsTracker.init({
+  dsn: "https://<api_key>@getforgeops.net/api/v1/events",
+  detectChanges: true, // default; false sends no startup snapshot
+  trackEnvVarNames: false, // default; true also sends environment variable names
+});
+```
+
+With `trackEnvVarNames` on, the snapshot lists the names of your environment variables (never their
+values), so an added or removed variable shows up as a change. Names that differ from host to host,
+like `HOSTNAME`, `PATH`, `PORT`, `LC_*`, and Kubernetes service variables, are left out, as are the
+SDK's own `FORGE_OPS_*` settings.
+
+Requires a ForgeOps plan that includes change tracking; on a plan that doesn't, both are rejected
+server-side and dropped, exactly like any other delivery failure.
+
 ## Distributed tracing
 
-For one slow request, `forgeOpsTrackerTracingExpressMiddleware` (Express) and
+For one slow or errored 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.
@@ -363,7 +435,7 @@ it, so ForgeOps can render a waterfall for that one request.
 ```js
 import { forgeOpsTrackerTracingExpressMiddleware } from "@forge-ops/tracker/integrations/tracing";
 
-app.use(forgeOpsTrackerTracingExpressMiddleware);
+app.use(forgeOpsTrackerTracingExpressMiddleware); // before your routes
 ```
 
 ```js
@@ -375,7 +447,9 @@ 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.
+nothing extra. A request that errored (an unhandled error, or any `captureException()` during it)
+is the one exception: its trace is always sent, however fast it was, since the spans leading up to
+an error are exactly what you want next to it.
 
 ```js
 forgeOpsTracker.init({
@@ -413,6 +487,58 @@ with `trackTracing` off: it just runs the callback and records nothing, never th
 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.
 
+### Following a request across services
+
+Traces use the [W3C Trace Context](https://www.w3.org/TR/trace-context/) standard, so a request can
+be followed from one service into the next, whichever language or tracing library the other
+service uses:
+
+- **Incoming**: a request that arrives with a valid `traceparent` header continues that trace (same
+  trace id), and its root span records the caller's span as its parent. A missing or malformed
+  header just starts a new trace.
+- **Outgoing**: every outbound call made through Node's `http`/`https` modules during a request
+  gets a `traceparent` header whose parent id is that call's own span, so the next service's spans
+  nest under it. A `traceparent` you set yourself is never replaced, and this client's own
+  deliveries to ForgeOps never get one. The global `fetch()` doesn't go through `http`/`https`, so
+  it isn't instrumented and gets no header.
+
+A trace id exists for every request even with `trackTracing` off, and the header is still sent,
+since the trace id is also what links an error here to an error in the service you called. Seeing
+the two errors connected in ForgeOps needs both services' projects linked there.
+
+```js
+import http from "node:http";
+import express from "express";
+import * as forgeOpsTracker from "@forge-ops/tracker";
+import { forgeOpsTrackerExpressMiddleware } from "@forge-ops/tracker/integrations/express";
+import { forgeOpsTrackerTracingExpressMiddleware } from "@forge-ops/tracker/integrations/tracing";
+
+forgeOpsTracker.init({
+  dsn: "https://<api_key>@getforgeops.net/api/v1/events",
+  propagateTraces: true, // default true; false never sends traceparent
+  // Default null: every host. A string matches that host and its subdomains on a dot boundary
+  // ("internal.example" matches "orders.internal.example", not "notinternal.example"); a RegExp is
+  // tested against the host, without the port.
+  tracePropagationTargets: ["internal.example", /^10\.0\./],
+});
+
+const app = express();
+app.use(forgeOpsTrackerTracingExpressMiddleware);
+
+app.post("/checkout", (req, res, next) => {
+  // Carries traceparent: 00-<this request's trace id>-<this call's span id>-01
+  const call = http.request("http://orders.internal.example/orders", { method: "POST" }, (response) => {
+    response.resume();
+    res.status(response.statusCode === 201 ? 201 : 502).end();
+  });
+  call.on("error", next);
+  call.end(JSON.stringify({ sku: "A1" }));
+});
+
+app.use(forgeOpsTrackerExpressMiddleware);
+app.listen(3000);
+```
+
 **Known gaps:** no database span capture (this SDK has no existing query/ORM instrumentation hook
 of any kind yet to extend) and no Redis span capture (no existing Redis hook or dependency exists
 here either); a database call or Redis call inside a traced request just won't show up as its own

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forge-ops/tracker",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "ForgeOps error tracking client: captures unhandled exceptions (Express/Fastify integration, plus explicit capture anywhere else) and delivers them to ForgeOps over HTTP.",
   "type": "module",
   "main": "src/index.js",

package/src/changes.js

@@ -0,0 +1,147 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * Payloads for "what changed": one explicit recordChange() call (POST /api/v1/changes), and the
+ * startup snapshot (POST /api/v1/change_snapshots) that ForgeOps diffs against the previous boot's
+ * to record what changed between deploys. Mirrors gems/forge_ops_tracker's Change and
+ * ChangeSnapshot.
+ *
+ * The snapshot leaves out any key it can't determine reliably rather than guessing, since the
+ * server reads a missing key as "unknown", never as "everything was removed". Environment variable
+ * names are only ever names, never values, and only when trackEnvVarNames is on.
+ */
+
+/** The server rejects any other kind outright (422), so an unknown one is sent as "other" rather
+ * than dropped: the change still gets recorded, just less specifically categorized. */
+export const CHANGE_KINDS = Object.freeze(["feature_flag", "config", "migration", "dependency", "infrastructure", "other"]);
+const MAX_TITLE_LENGTH = 200;
+
+const MAX_DEPENDENCIES = 3000;
+const MAX_NAME_LENGTH = 200;
+const MAX_VERSION_LENGTH = 100;
+const MAX_ENV_VAR_NAMES = 3000;
+
+/** Host-specific variables that differ from one box to the next (or one boot to the next) without
+ * anything about the deploy having changed, so a fleet doesn't look like it's changing on every
+ * restart. The SDK's own FORGE_OPS_* settings are dropped too. */
+const ENV_VAR_DENYLIST = new Set([
+  "HOSTNAME", "HOST", "HOME", "PATH", "PWD", "OLDPWD", "SHLVL", "_", "TERM", "USER", "LOGNAME", "SHELL",
+  "LANG", "TMPDIR", "TZ", "PORT", "DYNO", "INVOCATION_ID", "JOURNAL_STREAM",
+]);
+const ENV_VAR_DENYLIST_PATTERNS = [
+  /^LC_/, /^SYSTEMD_/, /^MEMORY_PRESSURE_/, /^KUBERNETES_/, /^FORGE_OPS_/,
+  /_SERVICE_HOST$/, /_SERVICE_PORT/, /_PORT_.*_TCP/,
+];
+
+/** @param {unknown} kind */
+export function normalizeKind(kind) {
+  return CHANGE_KINDS.includes(kind) ? kind : "other";
+}
+
+/**
+ * The body for one recordChange() call, or null when there's nothing sendable (a blank title: the
+ * server requires one, so posting it anyway would only ever come back 422).
+ * @param {import("./configuration.js").Configuration} configuration
+ * @param {{ kind: string, title: string, details?: Record<string, unknown>, environment?: string,
+ *   service?: string, actor?: string, url?: string, id?: string, occurredAt?: Date | string }} change
+ */
+export function buildChange(configuration, { kind, title, details, environment, service, actor, url, id, occurredAt } = {}) {
+  const trimmed = title == null ? "" : String(title).trim();
+  if (trimmed === "") {
+    return null;
+  }
+
+  const payload = {
+    kind: normalizeKind(kind),
+    title: trimmed.slice(0, MAX_TITLE_LENGTH),
+    details: details !== null && typeof details === "object" && !Array.isArray(details) ? details : {},
+    environment: String(environment ?? configuration.environment),
+  };
+  for (const [key, value] of Object.entries({ service, actor, url, id })) {
+    if (value != null) {
+      payload[key] = String(value);
+    }
+  }
+  payload.occurred_at = iso8601(occurredAt);
+  return payload;
+}
+
+/** @param {Date | string | undefined} value */
+function iso8601(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (value instanceof Date && !Number.isNaN(value.getTime())) {
+    return value.toISOString();
+  }
+  return new Date().toISOString();
+}
+
+/** @param {string} name */
+export function isDeniedEnvVar(name) {
+  return ENV_VAR_DENYLIST.has(name) || ENV_VAR_DENYLIST_PATTERNS.some((pattern) => pattern.test(name));
+}
+
+/**
+ * Names only, never values, sorted so the same set always serializes the same way.
+ * @param {Record<string, string | undefined>} [env]
+ */
+export function envVarNames(env = process.env) {
+  return Object.keys(env)
+    .filter((name) => !isDeniedEnvVar(name))
+    .sort()
+    .slice(0, MAX_ENV_VAR_NAMES);
+}
+
+export function runtime() {
+  return `node ${process.versions.node}`;
+}
+
+/**
+ * The app's own direct dependencies (the "dependencies" in `<appRoot>/package.json`), each
+ * resolved to the version actually installed under `<appRoot>/node_modules/<name>/package.json`,
+ * never the semver range the manifest asks for. A dependency that isn't installed there is left
+ * out rather than guessed at, and so is the whole key (null) when there's no package.json to read.
+ * @param {string} appRoot
+ */
+export async function dependencies(appRoot) {
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(path.join(appRoot, "package.json"), "utf8"));
+  } catch {
+    return null;
+  }
+
+  const names = Object.keys(manifest?.dependencies ?? {}).sort().slice(0, MAX_DEPENDENCIES);
+  const resolved = await Promise.all(names.map((name) => installedVersion(appRoot, name)));
+  const found = {};
+  names.forEach((name, index) => {
+    if (resolved[index]) {
+      found[name.slice(0, MAX_NAME_LENGTH)] = resolved[index].slice(0, MAX_VERSION_LENGTH);
+    }
+  });
+  return Object.keys(found).length > 0 ? found : null;
+}
+
+async function installedVersion(appRoot, name) {
+  try {
+    const installed = JSON.parse(await readFile(path.join(appRoot, "node_modules", name, "package.json"), "utf8"));
+    return typeof installed?.version === "string" ? installed.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/** @param {import("./configuration.js").Configuration} configuration */
+export async function buildSnapshot(configuration) {
+  const state = { runtime: runtime() };
+  const deps = await dependencies(configuration.appRoot);
+  if (deps) {
+    state.dependencies = deps;
+  }
+  if (configuration.trackEnvVarNames) {
+    state.env_var_names = envVarNames();
+  }
+  return { environment: configuration.environment, state };
+}

package/src/client.js

@@ -68,6 +68,23 @@ export class Client {
     return this.#post(this.#configuration.infrastructureMetricsUri(), { metrics });
   }
 
+  /**
+   * One recordChange() call; see Api::V1::ChangesController. A plan without change tracking
+   * answers 403, which is just a false here like any other non-2xx.
+   * @param {Record<string, unknown>} payload
+   */
+  async deliverChange(payload) {
+    return this.#post(this.#configuration.changesUri(), payload);
+  }
+
+  /**
+   * The startup snapshot; see Api::V1::ChangeSnapshotsController.
+   * @param {Record<string, unknown>} payload
+   */
+  async deliverChangeSnapshot(payload) {
+    return this.#post(this.#configuration.changeSnapshotsUri(), payload);
+  }
+
   /**
    * @param {string | null} uri
    * @param {Record<string, unknown>} payload

package/src/configuration.js

@@ -116,6 +116,41 @@ export class Configuration {
    * gems/forge_ops_tracker's own Configuration#trace_capture_threshold_ms default. */
   traceCaptureThresholdMs = 1000;
 
+  /**
+   * Adds a W3C `traceparent` header (https://www.w3.org/TR/trace-context/) to every outbound
+   * http/https request made during a request the Express/Fastify tracing integration is handling
+   * (see httpTracing.js), so a service that reports to ForgeOps too (or anything else that
+   * understands the standard) continues this request's trace instead of starting its own. On by
+   * default, the same as gems/forge_ops_tracker's propagate_traces: the header also carries the
+   * trace id that links an error here to an error there, which is useful with or without spans.
+   * Never overwrites a traceparent the request already has.
+   */
+  propagateTraces = true;
+  /**
+   * Which hosts get that header. null (the default) means every host. Otherwise an array whose
+   * entries are either a host string, matching that host and its subdomains on a dot boundary
+   * ("example.com" matches "api.example.com", not "badexample.com"; a leading dot is ignored), or a
+   * RegExp tested against the host (no port). Narrow it for a third-party API that rejects headers
+   * it doesn't know, or that shouldn't learn this app's trace ids at all.
+   * @type {Array<string | RegExp> | null}
+   */
+  tracePropagationTargets = null;
+
+  /**
+   * Sends one startup snapshot per process (the Node version and the installed versions of your
+   * package.json dependencies; see changes.js) which ForgeOps diffs against the previous boot's to
+   * record what changed between deploys. On by default, same posture as every other automatic
+   * behavior here.
+   */
+  detectChanges = true;
+  /**
+   * Whether that snapshot also lists the names of this process's environment variables, so an
+   * added or removed variable shows up as a change. Off by default: names only, never values, but
+   * even names can say more about an app than some teams want to share. Host-specific names
+   * (HOSTNAME, PATH, PORT, and so on; see changes.js) are always left out.
+   */
+  trackEnvVarNames = false;
+
   /** @returns {string | null} */
   apiKey() {
     const parsed = this.#parsedDsn();
@@ -203,6 +238,76 @@ export class Configuration {
     return uri.replace(/\/events$/, "/spans");
   }
 
+  /**
+   * Same derivation again, swapping the trailing /events for /changes (recordChange()).
+   * @returns {string | null}
+   */
+  changesUri() {
+    const uri = this.ingestionUri();
+    if (!uri) {
+      return null;
+    }
+    return uri.replace(/\/events$/, "/changes");
+  }
+
+  /**
+   * Same derivation again, swapping the trailing /events for /change_snapshots (the startup
+   * snapshot).
+   * @returns {string | null}
+   */
+  changeSnapshotsUri() {
+    const uri = this.ingestionUri();
+    if (!uri) {
+      return null;
+    }
+    return uri.replace(/\/events$/, "/change_snapshots");
+  }
+
+  /**
+   * Whether an outbound request to `host` should carry a traceparent header; see
+   * propagateTraces/tracePropagationTargets above. Case-insensitive, since hostnames are.
+   * @param {string} host
+   * @returns {boolean}
+   */
+  propagatesTraceTo(host) {
+    if (!this.propagateTraces) {
+      return false;
+    }
+    if (this.tracePropagationTargets === null || this.tracePropagationTargets === undefined) {
+      return true;
+    }
+    const normalized = String(host ?? "").toLowerCase();
+    return this.tracePropagationTargets.some((target) => {
+      if (target instanceof RegExp) {
+        target.lastIndex = 0; // a /g or /y pattern would otherwise carry state from the last test
+        return target.test(normalized);
+      }
+      const suffix = String(target).toLowerCase().replace(/^\./, "");
+      return suffix !== "" && (normalized === suffix || normalized.endsWith(`.${suffix}`));
+    });
+  }
+
+  /**
+   * Whether a request to `host`:`port` is one of this client's own deliveries to ForgeOps (same
+   * host and port as the DSN), so the outbound-HTTP wrapper never adds a traceparent to it. The
+   * Client itself uses fetch(), which that wrapper never sees, so this is a second guard, not the
+   * only one.
+   * @param {string} host
+   * @param {number | string | null | undefined} port
+   * @param {string} protocol "http:" or "https:"
+   * @returns {boolean}
+   */
+  isOwnHost(host, port, protocol) {
+    const parsed = this.#parsedDsn();
+    if (parsed === null || !host) {
+      return false;
+    }
+    const defaultPort = (scheme) => (scheme === "http:" ? "80" : scheme === "https:" ? "443" : "");
+    const ownPort = parsed.port || defaultPort(parsed.protocol);
+    const targetPort = port === null || port === undefined || port === "" ? defaultPort(protocol) : String(port);
+    return String(host).toLowerCase() === parsed.hostname.toLowerCase() && targetPort === ownPort;
+  }
+
   /** @returns {boolean} */
   isEnabled() {
     return Boolean(this.dsn) && this.apiKey() !== null && this.enabledEnvironments.has(this.environment);

package/src/eventBuilder.js

@@ -49,8 +49,14 @@ export class EventBuilder {
    * @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]
+   *   Where the error happened (see RequestState in requestState.js): transactionName is the same
+   *   "GET /orders/:id" name the request's root span and performance samples use, endpoint the
+   *   human-readable route ("GET /orders/:id"), traceId the request's 32-character lowercase hex
+   *   W3C trace id, which is also what links this error to errors other services reported for the
+   *   same trace. All absent outside a request, and a missing one is left out of the payload.
    */
-  build(error, context = {}, user = null, breadcrumbs = []) {
+  build(error, context = {}, user = null, breadcrumbs = [], request = {}) {
     const payload = {
       exception_class: error?.name ?? "Error",
       message: error?.message ?? "",
@@ -69,13 +75,24 @@ export class EventBuilder {
     if (breadcrumbs && breadcrumbs.length > 0) {
       payload.breadcrumbs = [...breadcrumbs];
     }
+    if (request.transactionName) {
+      payload.transaction_name = request.transactionName;
+    }
+    if (request.endpoint) {
+      payload.endpoint = request.endpoint;
+    }
+    if (request.traceId) {
+      payload.trace_id = request.traceId;
+    }
     this.#attachSql(payload, error);
 
     return this.#configuration.scrubPii ? this.#scrub(payload) : payload;
   }
 
-  // exception_class/occurred_at/environment/release/server_name/user are
-  // left alone: structured fields this client or the host app sets
+  // exception_class/occurred_at/environment/release/server_name/user/
+  // transaction_name/endpoint/trace_id are left alone (endpoint is a
+  // declared route pattern, never the literal path, so there's no id or
+  // token in it to scrub): structured fields this client or the host app sets
   // deliberately, not free text an exception or its context could
   // accidentally spill sensitive data into. user specifically is a
   // deliberate exemption, not an oversight: the scrubber's own email

package/src/httpTracing.js

@@ -1,5 +1,6 @@
 import http from "node:http";
 import https from "node:https";
+import { generateSpanId, TRACEPARENT_HEADER } from "./traceParent.js";
 
 let installed = false;
 let originalHttpRequest = null;
@@ -20,19 +21,28 @@ let originalHttpsRequest = null;
  * 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.
+ * just passing the functions actually used.
  *
- * @param {(name: string, kind: string, startedAt: Date, durationMs: number, data?: Record<string, unknown>) => void} recordSpan
+ * Also propagates the current request's trace to the service being called, as a W3C `traceparent`
+ * header (see traceParent.js, and Configuration#propagateTraces/tracePropagationTargets for turning
+ * it off or narrowing it to specific hosts). The header's parent id is this outbound call's own
+ * span id, generated before the call is made (the span itself can only be recorded afterward, once
+ * its duration is known) and then recorded with that exact id, so the downstream service's root
+ * span points at a span that really exists in this trace. traceparentFor decides whether there is
+ * a trace to continue at all (only inside a request) and returns null otherwise.
+ *
+ * @param {(name: string, kind: string, startedAt: Date, durationMs: number, data?: Record<string, unknown>, spanId?: string) => void} recordSpan
+ * @param {(host: string, port: number | string | null | undefined, protocol: string, spanId: string) => string | null} [traceparentFor]
  */
-export function installHttpTracing(recordSpan) {
+export function installHttpTracing(recordSpan, traceparentFor = () => null) {
   if (installed) {
     return;
   }
   installed = true;
   originalHttpRequest = http.request;
   originalHttpsRequest = https.request;
-  http.request = wrap(originalHttpRequest, recordSpan);
-  https.request = wrap(originalHttpsRequest, recordSpan);
+  http.request = wrap(originalHttpRequest, recordSpan, traceparentFor, "http:");
+  https.request = wrap(originalHttpsRequest, recordSpan, traceparentFor, "https:");
 }
 
 /** @internal test-only: restores http/https.request exactly as installHttpTracing found them. */
@@ -47,12 +57,14 @@ export function _uninstallHttpTracing() {
   originalHttpsRequest = null;
 }
 
-function wrap(originalRequest, recordSpan) {
+function wrap(originalRequest, recordSpan, traceparentFor, defaultProtocol) {
   return function patchedRequest(...args) {
+    const spanId = generateSpanId();
     const startedAt = new Date();
     const start = performance.now();
     const req = originalRequest.apply(this, args);
-    const { method, host } = describeRequest(args);
+    const { method, host, port, protocol } = describeRequest(args, defaultProtocol);
+    propagateTrace(req, () => traceparentFor(host, port, protocol, spanId));
 
     // "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.
@@ -62,7 +74,7 @@ function wrap(originalRequest, recordSpan) {
         return;
       }
       finished = true;
-      recordSpan(`${method} ${host}`, "http", startedAt, performance.now() - start, status === undefined ? {} : { status });
+      recordSpan(`${method} ${host}`, "http", startedAt, performance.now() - start, status === undefined ? {} : { status }, spanId);
     };
 
     // No status at all means the request itself failed (DNS, connection refused, timeout) before
@@ -75,6 +87,31 @@ function wrap(originalRequest, recordSpan) {
   };
 }
 
+/**
+ * Adds the traceparent header to a request that was just created and hasn't sent its headers yet
+ * (the caller only writes or ends it after http.request returns). Leaves a traceparent the caller
+ * already set alone: whoever set it explicitly knows better than this client which trace the call
+ * belongs to. Skipped when headers were already flushed (a raw-array `headers` option sends them at
+ * construction). Never throws, since a failure to add a header must never stop the host app's own
+ * request from going out.
+ *
+ * @param {import("node:http").ClientRequest} req
+ * @param {() => string | null} traceparent
+ */
+function propagateTrace(req, traceparent) {
+  try {
+    if (req.headersSent || req.hasHeader(TRACEPARENT_HEADER)) {
+      return;
+    }
+    const value = traceparent();
+    if (value !== null) {
+      req.setHeader(TRACEPARENT_HEADER, value);
+    }
+  } catch {
+    // See this function's own comment: the request goes out without the header.
+  }
+}
+
 /**
  * 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
@@ -82,15 +119,21 @@ function wrap(originalRequest, recordSpan) {
  * 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.
+ *
+ * port/protocol are only ever used to recognize this client's own deliveries to ForgeOps (see
+ * Configuration#isOwnHost), never in a label.
  * @param {unknown[]} args
+ * @param {string} defaultProtocol
  */
-function describeRequest(args) {
+function describeRequest(args, defaultProtocol) {
   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;
+    options.port = url.port;
+    options.protocol = url.protocol;
     if (second && typeof second === "object") {
       Object.assign(options, second);
     }
@@ -100,5 +143,5 @@ function describeRequest(args) {
 
   const method = String(options.method ?? "GET").toUpperCase();
   const host = options.host ?? options.hostname ?? "unknown";
-  return { method, host };
+  return { method, host, port: options.port, protocol: options.protocol ?? defaultProtocol };
 }