railwatch 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 072de4fbe3a2b0854d5e00b3b41b033a901d05d9f681f8e6083ae9c6882e4751
-  data.tar.gz: f24164cbf663302b6df3e302aadf59e7328316a4e6d1c86d1b8b5ad49ee6f85f
+  metadata.gz: af26db042e24211ffde4ad4e82dd90a7bc27e37c0bc9f74674947a30109b0036
+  data.tar.gz: 8c8033a1fa3f4b97142dd6b3593cf4bcc7fa16d2bea97fed6d580ee1584133de
 SHA512:
-  metadata.gz: 9d3907a21539f08dd1e71d4eb83e0305d749673a51e9eb4d8404e4cff2924665d0c0dd28c5f4e8d62b50174ff0618f7e43d41a5984cd52b24a1d6fe63745dae7
-  data.tar.gz: 1bc7449ec96e9c85432d9f75746a28e4f5152ba71b97d3d32e6b7a9ee4b53044abdf34281a78bf4bf546436b0b8168376b51635daf640fe396fd853163cde638
+  metadata.gz: 1ab758eed04fbcc9088989d5c411c88e0e80d8c3fbc08195c2908f04fcf38a21ad6b9ed8ec3ab8363081fcad59886f1abff8efb93bd6abfaeb156bada0bb66dc
+  data.tar.gz: 81e0e6e114d46a70619e21ae97816f451b83ccee7ee3f8e8aad8f2ccce8bd487beb31bfdea4cbbdf467357da7e7c4ae1b32dad69eae317e55083755897f3aa23

data/CHANGELOG.md

@@ -6,6 +6,20 @@
      filled in by the release commit, which is also the only commit that
      touches lib/railwatch/version.rb and Gemfile.lock. See CONTRIBUTING.md. -->
 
+## 1.3.0 (2026-10-25)
+
+- The initial-load visit splits its TTFB into `redirect_ms`,
+  `connect_ms` and `server_ms`, which add up to `ttfb`, plus
+  `redirect_count`. TTFB is measured from navigation start, so it holds
+  every redirect before the page: a 1.2 s TTFB on a route the server
+  answers in 100 ms was a redirect chain, and nothing said so.
+  `redirect_ms` (navigation start to `fetchStart`) is still measured when
+  a hop is cross-origin, where browsers report `redirectCount` 0; the
+  client then leaves `redirect_count` out rather than claim no redirect.
+  The beacon accepts and clamps the four fields. Receivers must store them
+  for them to show anywhere. Apps that copied the client
+  (`app/frontend/lib/railwatch.ts`) need the same change in their copy.
+
 ## 1.2.0 (2026-10-25)
 
 - Executions send only the counters that fired. Every parent record

data/app/controllers/railwatch/beacon_controller.rb

@@ -10,6 +10,8 @@ module Railwatch
     # forged beacon, not a page load, so it is clamped rather than stored.
     MAX_METRIC_MS = 120_000
     MAX_CLS = 100.0
+    # Browsers stop following a redirect chain at 20 (Fetch's limit).
+    MAX_REDIRECTS = 20
 
     MAX_REQUEST_BYTES = 256 * 1024
     MAX_VISITS = 50
@@ -50,6 +52,7 @@ module Railwatch
           cls: cumulative_layout_shift(v["cls"]),
           inp: metric_ms(v["inp"]),
           ttfb: metric_ms(v["ttfb"]),
+          **ttfb_phases(v),
           user: user_id,
           tenant: tenant,
           user_agent: safe_string(request.user_agent, 256))
@@ -274,9 +277,38 @@ module Railwatch
     # Web vitals only ride along on the initial-load visit, and only from
     # browsers that support the entry type behind them, so every one of these
     # is nil far more often than not.
+    # A value that is not a finite number ("1e309" parses to Infinity, which
+    # #round refuses) is nil, like a missing one: raising here would drop the
+    # whole beacon at the rescue below, every other visit in it included.
     def metric_ms(value)
+      finite_ms(value)&.round&.clamp(0, MAX_METRIC_MS)
+    end
+
+    # The initial load's TTFB split into phases. They add up to ttfb, so if
+    # clamping any of them (or ttfb itself) would break that sum, the split is
+    # dropped rather than stored inconsistent: ttfb stays, the phases are nil.
+    def ttfb_phases(visit)
+      raw = %w[redirect_ms connect_ms server_ms].to_h { |key| [ key, finite_ms(visit[key]) ] }
+      phases = raw.transform_values { |ms| ms&.round&.clamp(0, MAX_METRIC_MS) }
+      total = finite_ms(visit["ttfb"])
+      clamped = raw.any? { |key, ms| ms && ms.round != phases[key] }
+      over = total && total.round > MAX_METRIC_MS
+      phases = phases.transform_values { nil } if clamped || over
+      phases.transform_keys(&:to_sym).merge(redirect_count: redirect_count(visit["redirect_count"]))
+    end
+
+    def finite_ms(value)
+      return nil if value.nil? || value == ""
+      float = safe_float(value)
+      float.finite? ? float : nil
+    end
+
+    # How many redirects the browser SHOWED. It hides them when any hop was
+    # cross-origin, so the client sends nothing then rather than 0, and a
+    # nil here must stay nil: "none" and "hidden" are different answers.
+    def redirect_count(value)
       return nil if value.nil? || value == ""
-      safe_float(value).round.clamp(0, MAX_METRIC_MS)
+      safe_integer(value).clamp(0, MAX_REDIRECTS)
     end
 
     def cumulative_layout_shift(value)

data/docs/records.md

@@ -768,7 +768,11 @@ entirely if `config.beacon_enabled` is off.
 | `lcp` | Largest Contentful Paint, integer ms, clamped to 0–120000. Initial load only. |
 | `cls` | Cumulative Layout Shift — the largest session window, float rounded to 4 decimals, clamped to 0–100. Initial load only. |
 | `inp` | Interaction to Next Paint, integer ms, clamped to 0–120000. The slowest interaction, not the spec's high percentile. Initial load only. |
-| `ttfb` | Time to First Byte from navigation timing's `responseStart`, integer ms, clamped to 0–120000. Initial load only. |
+| `ttfb` | Time to First Byte from navigation timing's `responseStart`, integer ms, clamped to 0–120000. Initial load only. Includes every redirect before the page. |
+| `redirect_ms` | The part of `ttfb` before the final request started: navigation start to `fetchStart` (`workerStart` when a service worker started first). Every redirect hop, plus a few ms of the browser's own work. Still measured when a hop is cross-origin, when the browser hides the count. Integer ms, clamped to 0–120000. Initial load only. |
+| `redirect_count` | Redirects the browser **showed** (`redirectCount`), clamped to 0–20. Nil when it showed none, which is either no redirect or a cross-origin hop it hid: never read nil as "no redirect", read `redirect_ms`. Initial load only. |
+| `connect_ms` | `ttfb` from the final request's start to `requestStart`: service worker startup, HTTP cache, DNS, TCP and TLS. Integer ms, clamped to 0–120000. Initial load only. |
+| `server_ms` | `ttfb` from `requestStart` to `responseStart`: the network round trip plus the server's time. Integer ms, clamped to 0–120000. Initial load only. |
 | `user` | Resolved server-side from the beacon request's session/cookies, same resolver as every other record. |
 | `tenant` | Current tenant context. |
 | `user_agent` | Truncated to 256 chars. |
@@ -781,7 +785,11 @@ never routed it. It has `method` `"GET"`, `status` `"success"`, and
 four Core Web Vitals. It is held back until the page is first hidden, on
 `visibilitychange`/`pagehide`, so those numbers are final when it ships.
 Every vital is nil on a browser that doesn't support the
-`PerformanceObserver` entry type behind it.
+`PerformanceObserver` entry type behind it. `redirect_ms`, `connect_ms`
+and `server_ms` add up to `ttfb` exactly (the boundaries are rounded
+before subtracting); all three are nil when the browser's timestamps are
+missing or out of order, and when clamping `ttfb` or any phase to the
+120,000 ms cap would leave a split that no longer adds up.
 
 ### `session`
 

data/lib/generators/railwatch/install/templates/railwatch.ts

@@ -1,7 +1,8 @@
 // Railwatch browser client for Inertia. Reports each visit's duration,
 // component, and prop payload size to /railwatch/beacon so the platform can
-// show real page-load timing, plus Core Web Vitals (LCP, CLS, INP, TTFB)
-// for the initial page load, plus every JavaScript error the page throws
+// show real page-load timing, plus Core Web Vitals (LCP, CLS, INP, TTFB,
+// with TTFB split into redirect / connection / server time) for the
+// initial page load, plus every JavaScript error the page throws
 // with the breadcrumb trail that led to it.
 // No dependencies -- every metric comes from PerformanceObserver or the
 // navigation timing entry, and every API is feature-detected, so browsers
@@ -23,6 +24,11 @@ interface Visit {
   cls?: number
   inp?: number
   ttfb?: number
+  // TTFB split into phases (initial load only; see ttfbPhases).
+  redirect_ms?: number
+  redirect_count?: number
+  connect_ms?: number
+  server_ms?: number
 }
 
 // The tab's session, for release health. sessionStorage scopes it to the
@@ -679,6 +685,58 @@ function pageComponent(): string | undefined {
   }
 }
 
+// Where the initial load's TTFB went, in three phases that add up to it:
+//
+//   redirect_ms  navigation start -> the final request's start: every
+//                redirect hop, plus the browser's own few ms (so never
+//                quite 0).
+//   connect_ms   -> requestStart: service worker startup, HTTP cache, DNS,
+//                TCP and TLS for the final request.
+//   server_ms    -> responseStart: the network round trip and the server's
+//                time.
+//
+// The final request starts at fetchStart, or at workerStart when a service
+// worker had to start first (the web-vitals library cuts there too).
+//
+// redirect_ms stays honest when a hop is cross-origin. The browser then
+// zeroes redirectCount, redirectStart and redirectEnd (Navigation Timing 2),
+// but fetchStart is still the final request's start (Fetch's "post-redirect
+// start time"), so the hidden hops' time is still in it.
+//
+// redirect_count is sent only when the browser shows the redirects. A 0
+// means "no redirect" or "hidden", and a hidden redirect must never be
+// reported as no redirect.
+//
+// The boundaries are rounded before subtracting, so the three phases add up
+// to the reported ttfb exactly. A browser whose timestamps are missing or
+// out of order sends no phases rather than a wrong split.
+function ttfbPhases(nav: PerformanceNavigationTiming): Partial<Visit> {
+  const fetchStart =
+    nav.workerStart > 0 && nav.workerStart < nav.fetchStart
+      ? nav.workerStart
+      : nav.fetchStart
+  // Order is judged on the raw timestamps: rounding first would let a
+  // requestStart a hair before fetchStart through as a 0 ms phase.
+  const ordered =
+    nav.responseStart > 0 &&
+    fetchStart >= nav.startTime &&
+    nav.requestStart >= fetchStart &&
+    nav.responseStart >= nav.requestStart
+  if (!ordered) return {}
+  const [start, fetched, requested, responded] = [
+    nav.startTime,
+    fetchStart,
+    nav.requestStart,
+    nav.responseStart,
+  ].map(Math.round)
+  return {
+    redirect_ms: fetched - start,
+    redirect_count: nav.redirectCount > 0 ? nav.redirectCount : undefined,
+    connect_ms: requested - fetched,
+    server_ms: responded - requested,
+  }
+}
+
 // The first page load is a visit too -- it just wasn't routed by Inertia, so
 // the component name comes off the root element's serialized page object.
 function initialVisit(): Visit | null {
@@ -696,6 +754,7 @@ function initialVisit(): Visit | null {
     component,
     duration_ms: duration,
     status: "success",
+    ...ttfbPhases(nav),
   }
 }
 

data/lib/railwatch/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Railwatch
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 end

data/lib/railwatch/wire_fixtures.json

@@ -605,6 +605,10 @@
     "cls": null,
     "inp": null,
     "ttfb": null,
+    "redirect_ms": null,
+    "redirect_count": null,
+    "connect_ms": null,
+    "server_ms": null,
     "user": null,
     "tenant": null,
     "user_agent": ""

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: railwatch
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Cole Robertson