|
1 | 1 | # Chrome Performance Tracks — Solid's records on the Performance panel |
2 | 2 |
|
3 | 3 | _Drafted 2026-09-18 as a Cursor plan; landed in the repo 2026-09-21 with the |
4 | | -work. Status: SHIPPED through Stage 4 on the `perf-tracks` branch; Stage 5 |
5 | | -deferred. Sibling of `responsiveness-findings-plan.md` (the findings and the |
| 4 | +work. Status: SHIPPED through Stage 4 (#3580); Stage 5 (server spans over |
| 5 | +`Server-Timing`) implemented on `feat/performance-tracks-server`, PR pending. Sibling of `responsiveness-findings-plan.md` (the findings and the |
6 | 6 | interaction-contract decisions D1/D2; its "↔ Tracks" marks are the meeting |
7 | 7 | points) and second consumer, beside `@sentry/solid-2`, of the observe-tier |
8 | 8 | contract in `proposals/production-observability-sketch.md` §7. Owner: Ryan._ |
@@ -196,18 +196,82 @@ transition)`. Shape: `{ ownerPath?, at, shownMs, interaction? }` (item 4's |
196 | 196 | compiler release carrying `sourceNames` — the compiler rejects unknown |
197 | 197 | options, so the plugin's `@solidjs/compiler` range must move with it. |
198 | 198 |
|
199 | | -## Stage 5 (deferred): server spans in the browser panel |
200 | | - |
201 | | -Ride the existing `Server-Timing` carrier (`packages/web/src/trace.ts`, |
202 | | -`appendTraceServerTiming`) rather than a custom debug chunk: in dev/observe, |
203 | | -append `dur=` metrics per `invocation` and `boundary` to the document and |
204 | | -server-function responses. Chrome renders `Server-Timing` in the Network |
205 | | -track's request details with no client code, and the adapter can read them |
206 | | -via `PerformanceResourceTiming.serverTiming` and draw them on the `Server` |
207 | | -track beside the matching `call`, joined by function `id`. Server waterfall |
208 | | -/ N+1 per request stays a consumer-side join over `invocation`/`boundary` |
209 | | -records (responsiveness item 5b). Not part of this delivery; the record |
210 | | -shapes stay serializable and the header stays the one carrier. |
| 199 | +## Stage 5: server spans in the browser panel |
| 200 | + |
| 201 | +The client-side `Server` track shows a server-function call as the browser |
| 202 | +saw it: request out, answer decoded. What the server did inside that span — |
| 203 | +how long the function itself ran, and for the document, how long the shell |
| 204 | +render waited on which `<Loading>` boundary before the head could leave — |
| 205 | +is the server's `invocation` and `boundary` records, which never reach the |
| 206 | +browser. Stage 5 carries the durations over and paints them under the |
| 207 | +matching client span. React 19.2's server tracks do the equivalent for |
| 208 | +Flight only, dev-only; this works on any Solid response, in observe too. |
| 209 | + |
| 210 | +**Carrier: `Server-Timing`, the header the trace already rides.** One |
| 211 | +metric per timed thing, standard `dur` and `desc` params, appended at head |
| 212 | +commit by the same path as the trace entries (`appendTraceServerTiming`; |
| 213 | +`commitResponseStub` / `commitEventResponse`). No custom chunk, no `<meta>`: |
| 214 | +the header is what Chrome's Network details already show with no client |
| 215 | +code, what `PerformanceResourceTiming.serverTiming` and |
| 216 | +`PerformanceNavigationTiming.serverTiming` expose to the page, and the one |
| 217 | +place a metric can land for a redirect, an RPC response or a frame stream |
| 218 | +as much as for the document. The consequence is accepted, not worked |
| 219 | +around: a header is frozen when the head leaves, so only what the server |
| 220 | +knew by then rides it. For a server-function response that is everything |
| 221 | +(the function ran before the response was built). For a streamed document |
| 222 | +it is the shell: the render up to the flush, and the boundaries that |
| 223 | +settled inside it. Boundaries that stream after the shell cannot be on the |
| 224 | +header; they stay server-side records (the diagnostics artifact has them, |
| 225 | +`SSR_*` findings judge them). A later stage could carry them in the swap |
| 226 | +chunk the client already applies; that is a new carrier and a new decision. |
| 227 | + |
| 228 | +| Metric | On | `dur` | `desc` | |
| 229 | +| ------------------ | ------------------------------ | ------------------------------------------------------- | ------------------------------------------------------------- | |
| 230 | +| `solid-invocation` | the response the call produced | the execution (`InvocationEvent.durationMs`) | the function `id` (a direct SSR-time call: on the document) | |
| 231 | +| `solid-shell` | the document | render start → head commit (`renderToString`: complete) | — | |
| 232 | +| `solid-boundary` | the document | discovery → settle, boundaries settled before the head | the boundary's nearest component label, else its hydration id | |
| 233 | + |
| 234 | +**Gate — when the header changes.** The trace precedent holds: an app with |
| 235 | +no observer sees zero wire change in the observe build. Metrics ride the |
| 236 | +header exactly when the runtime is already measuring for a listener — |
| 237 | +`OBSERVE.records.observed("invocation")` / `observed("boundary")` on the |
| 238 | +server (a diagnostics capture, an APM adapter) — because the measurement is |
| 239 | +the same one the record carries; the header is a second reader of it, not |
| 240 | +a second clock. Dev builds carry them always: dev is where the panel is |
| 241 | +used, `enablePerformanceTracks()` runs in the browser and has no server |
| 242 | +half to switch on, and the boundary already measures in dev for its own |
| 243 | +checks. (`observeInvocation` gains the same `IS_DEV || observed` timing |
| 244 | +gate `ssrLoadingBoundary` has.) No new server API: an observe deployment |
| 245 | +that wants server spans in the panel installs an observer, the same way it |
| 246 | +gets the trace advertised. |
| 247 | + |
| 248 | +**Client — the adapter.** Nothing new on the wire from the browser and no |
| 249 | +change to the `call` record: the adapter reads the metrics off |
| 250 | +`CallLive.response` (the transport's own `Response`; same-origin headers are |
| 251 | +readable, cross-origin ones when `Timing-Allow-Origin` allows) and places |
| 252 | +them with the fetch's `PerformanceResourceTiming` entry — the server span |
| 253 | +ends at the entry's `responseStart` (the head left the server right after |
| 254 | +the function returned) and runs back `dur`. The entry lands in the |
| 255 | +performance timeline after the body is read, so it can arrive after the |
| 256 | +`call` record: the adapter keeps a `PerformanceObserver` on `resource` |
| 257 | +entries while enabled and paints when the entry for the call's URL and time |
| 258 | +window shows up (entries are historical stamps, so painting late is exact; |
| 259 | +the observer sees entries the buffer would have dropped). Without a |
| 260 | +resource entry (no `PerformanceObserver`, a `responseStart` of `0` under a |
| 261 | +missing `Timing-Allow-Origin`) the server span is placed centred in the |
| 262 | +call span and its tooltip says so. Pending calls with no entry are dropped |
| 263 | +after thirty seconds. For the document, at enable, the navigation entry's |
| 264 | +`serverTiming` paints `solid-shell` ending at its `responseStart` and each |
| 265 | +`solid-boundary` inside it, ending where the shell ends (their settle is at |
| 266 | +or before the flush; the exact offset is not carried — the last one to |
| 267 | +settle is what releases the shell, the others are earlier by an unknown |
| 268 | +margin, stated in the tooltip). Server spans are `tertiary` on the `Server` |
| 269 | +track, labelled `<id> · server` / `shell · server` / `<Page> · boundary`, |
| 270 | +beneath the `secondary` client spans, so the wire is the visible gap |
| 271 | +between them. |
| 272 | + |
| 273 | +Server waterfall / N+1 per request stays a consumer-side join over |
| 274 | +`invocation`/`boundary` records (responsiveness item 5b). |
211 | 275 |
|
212 | 276 | ## Where Solid beats React |
213 | 277 |
|
|
0 commit comments