Skip to content

Commit 3a1e4da

Browse files
ryansolidClaude via Cursorcursoragent
committed
feat(web): server spans in the Performance panel over Server-Timing
Performance tracks Stage 5. Dev and observe servers write the request's timed work as Server-Timing metrics beside the trace entries: `solid-invocation` on a server-function response, `solid-shell` and one `solid-boundary` per boundary that waited and settled before the shell on a document. Dev always; observe only while something on the server is subscribed to the invocation/boundary records (no wire change without an observer); prod carries no code. `desc` is sanitized to printable ASCII — a non-ASCII header value throws from Headers.append, which hung a response whose first write carried it. `@solidjs/web/performance-tracks` reads the metrics back: `<id> · server` spans beneath each call, placed against the resource's responseStart (PerformanceObserver for late entries, centred in the call after 30 s), and the document's navigation serverTiming painted at enable. Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]>
1 parent 56918c6 commit 3a1e4da

12 files changed

Lines changed: 1061 additions & 61 deletions

File tree

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
"@solidjs/web": patch
3+
"solid-js": patch
4+
---
5+
6+
Performance tracks: server spans in the browser panel (Stage 5)
7+
8+
Dev and observe servers now write the request's timed work as `Server-Timing` metrics beside the trace entries: `solid-invocation;dur;desc="<id>"` on a server-function response, and `solid-shell;dur` plus one `solid-boundary;dur;desc="<owner path>"` per boundary that waited and settled before the shell on a document. Dev builds always write them; observe builds only while something on the server is subscribed to the `invocation` / `boundary` records (no wire change without an observer); prod builds carry no code. `desc` values are sanitized to printable ASCII (a non-ASCII header value throws from `Headers.append`, which used to be able to hang a response whose first write carried it).
9+
10+
`@solidjs/web/performance-tracks` reads the metrics back: a `call` record's response headers become `<id> · server` spans beneath the call, placed against the resource's `responseStart` (via `PerformanceObserver` for late-arriving entries, centred in the call when none arrives within 30 s), and the document's `PerformanceNavigationTiming.serverTiming` paints `shell · server` / `boundary … · server` when the tracks enable.

‎documentation/plans/chrome-performance-tracks-plan.md‎

Lines changed: 78 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# Chrome Performance Tracks — Solid's records on the Performance panel
22

33
_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
66
interaction-contract decisions D1/D2; its "↔ Tracks" marks are the meeting
77
points) and second consumer, beside `@sentry/solid-2`, of the observe-tier
88
contract in `proposals/production-observability-sketch.md` §7. Owner: Ryan._
@@ -196,18 +196,82 @@ transition)`. Shape: `{ ownerPath?, at, shownMs, interaction? }` (item 4's
196196
compiler release carrying `sourceNames` — the compiler rejects unknown
197197
options, so the plugin's `@solidjs/compiler` range must move with it.
198198

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).
211275

212276
## Where Solid beats React
213277

‎documentation/solid-2.0/08-dev-diagnostics.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1060,6 +1060,8 @@ const disable = enablePerformanceTracks({
10601060
10611061
Group `Solid`, tracks in order: **Interactions** — the input delay, the handler, then the settle to `committed`/`held` (a silent hold as a warning); **Propagation** — one span per scheduler drain labelled by the writes that started it and what they reached (`count 0 → 1 — click on button#next · 5 runs, 1 unchanged`), with every run inside it beneath, labelled by what made it run (`<TodoRow> › effect ← doubled`) — the write's path through the graph as a flame; **Effects** and **Memos** — one span per re-run, creation run (`· create`) and effect callback (`· callback`), coloured by self time, `warning` for a run that changed nothing; **Async** — flights kickoff → landing (abandoned ones as warnings) and fallbacks shown → hidden; **Holds** — each wait labelled by its blockers, `warning` when silent, `error` when long; **Navigations** — request → settle by route pattern; **Server** — server-function calls and frame streams. Every span is emitted retroactively from the record's own `performance.now()` stamps — nothing brackets a hot path.
10621062
1063+
The **Server** track also shows the server's side of the work it painted from the client: dev and observe servers write the request's timed work as `Server-Timing` metrics — `solid-invocation` on a server-function response, `solid-shell` and one `solid-boundary` per boundary that waited on a document (RFC 12, [the trace the request belongs to](12-ssr-http.md#the-trace-the-request-belongs-to-gettracecontext)) — and the adapter reads them back: a `call` record's `live.response` headers become `<id> · server` beneath the call span, placed so the server span ends at the resource's `responseStart` and runs back its `dur` (the gap before it is the request's wire; `Wire` is a property), with the document's own `PerformanceNavigationTiming.serverTiming` painted as `shell · server` and `boundary <App> › <Loading> · server` when the tracks enable. Resource entries can land after the call settles, so the adapter watches `PerformanceObserver({ type: "resource", buffered: true })` for up to 30 s per call and centres the span inside the call when no entry arrives. An observe-tier server writes the metrics only while something on the server is subscribed to its `invocation`/`boundary` records (a diagnostics capture, an APM adapter) — enabling the tracks in the browser does not by itself change a production-shaped wire; a dev server always writes them.
1064+
10631065
Labels read as source: a flow control's own nodes fold into its tag (`<App> › <Show>` rather than `<App> › <Show> › condition value`) and a composed primitive's nodes into the primitive (`createDebounced.value` → `createDebounced`, the same rule as `store.user`), with the runtime's name kept in the span's `Node` property; the `Owner path` property is the unfolded truth and `Node id` the engine's id. Rich mode carries the why-chain (`formatRerun`) as the tooltip, and causes, deps added/removed, phase, origin and interaction as properties.
10641066
10651067
Findings become markers: every `DiagnosticEvent` delivered while enabled is a marker on the panel's Timings track (`SILENT_HOLD — <App> › <Search>`), coloured by severity, and — at `warn` or worse — annotated as a performance issue for the Insights sidebar (`detail.devtools.performanceIssue`, with the repair guide's section for the code as its link; Chrome ignores the annotation where it is not yet supported). In dev, every span and marker is emitted inside the `console.createTask` task of the component it belongs to, so the entry's stack in the panel points at the JSX site that rendered the component rather than at the engine. The dev component wrapper creates that task only for components rendered while an attribution engine is installed — `console.createTask` captures a stack per call, roughly the wrapper's own cost again and ~90 B retained per instance, DevTools open or not, and only an attribution consumer reads it — so a dev session with nothing enabled pays nothing, and the tracks enabled at bootstrap see every component's site (a component rendered before any consumer enabled carries no task and its spans are emitted plainly). Enabling takes its own hold on the engine (`attribution.enable({ log: false, ... })` — asking for no console log, which quiets the console only while no other holder wants it), so it coexists with a diagnostics capture or an APM adapter; the returned function releases it. There is one instance per page: a second `enablePerformanceTracks()` while one is running joins it (the first call's options stand) and returns its own release, and the instance is torn down when every release has been called — a module HMR re-evaluates lands back on one set of tracks, not two painters. The adapter is the one place host APIs are called from inside the engine's hooks, and it guards them: a `performance`/`console` call that throws drops that entry (dev warns once) and never reaches the engine.

‎documentation/solid-2.0/12-ssr-http.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -202,6 +202,8 @@ interface TraceContext {
202202

203203
The runtime also hands the trace **down to the browser**, which cannot send a header on the initial document request and has to learn the server's trace from the response: `entries` are emitted as `Server-Timing` metrics (`traceparent;desc="00-…"`) on the response head when it commits — every exit, so frames, server-function responses and redirects carry it too — and, for HTML documents, as `<meta name="traceparent" content="…">` in the shell head (the `</head>` splice or the `onHead` string; a headless fragment ships only the header). A `Server-Timing` name the application already wrote (an `httpHeader` declaration, an integration's metrics) is respected; the runtime's entries fold in beside it. One rule governs when the browser is told: **only when something is recording the trace** — the incoming `traceparent` had its sampled flag set (the caller says it recorded), or (observe/dev builds) a provider answered. Two things therefore stay silent while remaining fully available to `getTraceContext()`: a trace the runtime originated alone, and an **unsampled** upstream trace (`00-…-00`). Neither has a recorded server span for the browser to attach to, and a parent with flags `00` would make a parent-based browser sampler drop the pageload it would otherwise record. The unsampled case is everyday infrastructure — load balancers and meshes (GCP, Envoy/Istio, Azure Front Door) stamp `traceparent` on every request they forward — so an app on them with no APM sees zero wire change, while forwarding that trace downstream from a server function stays correct W3C propagation. The incoming `baggage` is likewise never echoed to the page — it is upstream context; a provider that wants its own in the document adds it.
204204

205+
The same header carries the request's **timed work** for the Performance panel (RFC 08, [Chrome Performance panel](08-dev-diagnostics.md#chrome-performance-panel-solidjswebperformance-tracks)) under its own gate: `solid-invocation;dur=…;desc="<id>"` on a server-function response, `solid-shell;dur=…` (render start → head commit) and one `solid-boundary;dur=…;desc="<owner path>"` per boundary that waited and settled before the shell on a document. Dev builds always write them; observe builds only while something has `observe.records.observed("invocation")` / `("boundary")` — the measurement is being taken for a listener, so the header rides along — and prod builds never have the code. The header freezes when the head leaves, so a streamed boundary is not on it; `desc` values are sanitized to printable ASCII (the owner path joins with `>` on the wire) because a header value cannot carry code points above `0xFF`.
206+
205207
**The provider** (observe and dev builds — `OBSERVE.server.trace`, see RFC 08) is how an APM overrides or extends the derivation once, globally: Sentry's server SDK answers from OpenTelemetry's active span and adds its `sentry-trace`/`baggage` entries, which the browser SDK reads from the same two carriers. A provider answers every field its vendor decides — `parentId` included, since a vendor continuing from its own header (`sentry-trace`) has a parent the runtime's `traceparent` derivation cannot know. That is the entire integration surface a server-side observer needs from the render — it never owns the head, never re-streams the body, and never has to know the host.
206208

207209
### Cookies: the codec + native `Headers`

‎packages/solid/src/server/hydration.ts‎

Lines changed: 23 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -118,9 +118,30 @@ function ssrLoadingBoundary(
118118
const record = (outcome: BoundaryEvent["outcome"], streamed: boolean, error?: unknown) => {
119119
if (recorded) return;
120120
recorded = true;
121-
if (IS_DEV) checkWaited(outcome, timed ? performance.now() - discoveredAt : 0);
121+
const settledAt = timed ? performance.now() : 0;
122+
if (IS_DEV) checkWaited(outcome, settledAt - discoveredAt);
123+
// The document's `Server-Timing` (the web runtime's seam on the render
124+
// context — see `_timing`): a boundary the shell WAITED on — a pass past
125+
// discovery, settled before the flush — labelled by its owner path, the
126+
// label the client's `fallback` record and the findings carry. One that
127+
// streams settled after the head left and cannot ride the header; one
128+
// decided on its first pass (a renderToString fallback, a client hole)
129+
// held nothing up.
130+
const timing = timed && !streamed && passes > 1 ? ctx._timing : undefined;
131+
// The core's walk (`_parent` + `_name`), the same one its diagnostics
132+
// make over these owners, so the record, the finding it may pair with
133+
// and the metric locate to the same `<App> › <Page>`.
134+
const path = observed || timing !== undefined ? ownerPath(o) : undefined;
135+
if (timing !== undefined) {
136+
// ASCII on the wire (a header value is a byte string); the adapter
137+
// renders the path with the artifact's ` › `.
138+
timing.push({
139+
name: "solid-boundary",
140+
dur: settledAt - discoveredAt,
141+
desc: path ? path.join(" > ") : id
142+
});
143+
}
122144
if (!observed) return;
123-
const settledAt = performance.now();
124145
const event: BoundaryEvent = {
125146
id,
126147
at: discoveredAt,
@@ -131,10 +152,6 @@ function ssrLoadingBoundary(
131152
streamed
132153
};
133154
if (revealGroup) event.revealGroup = revealGroup.id;
134-
// The core's walk (`_parent` + `_name`), the same one its diagnostics
135-
// make over these owners, so the record and the finding it may pair with
136-
// locate to the same `<App> › <Page>`.
137-
const path = ownerPath(o);
138155
if (path) event.ownerPath = path;
139156
const live: BoundaryLive = {};
140157
if (outcome === "error") live.error = error;

‎packages/solid/src/server/shared.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,15 @@ export type HydrationContext = {
6565
getBoundaryModules?: (id: string) => Record<string, string> | null;
6666
/** @internal Tracks which Loading boundary is currently rendering. Set by @solidjs/web via applyAssetTracking(). */
6767
_currentBoundaryId?: string | null;
68+
/**
69+
* @internal The document's timed server work for its response's
70+
* `Server-Timing`, in completion order. Set by @solidjs/web at render
71+
* start while it times the document (dev; observe with a `"boundary"`
72+
* listener); `ssrLoadingBoundary` pushes a `solid-boundary` metric for
73+
* each boundary that waited and settled before the shell. Absent when
74+
* the document is not timed — the boundary then pushes nothing.
75+
*/
76+
_timing?: { name: string; dur: number; desc?: string }[];
6877
/**
6978
* @internal Containment channel for errors surfacing in async resume loops
7079
* (boundary retries, flush passes), where nothing is on the stack to catch

0 commit comments

Comments
 (0)