Observability
This guide covers what Solid tells you about a running production app: errors your boundaries caught, traces that follow a request from the server into the browser, and what a slow interaction was waiting on.
Error reporting works on every build.
When an Errored boundary catches an error, the browser's global error handler never sees it, so Solid gives you a hook on each platform that reports every failure the runtime handled, along with the component that threw and the boundary that caught it.
Everything else needs the observe build.
It reports what the runtime did as plain records (a Loading boundary that waited on the server, a server-function call, a click and the writes it caused) and carries the request's trace into the browser for you.
Three builds
Solid ships three builds of every runtime package, selected by export condition.
| Build | Condition | Carries | OBSERVE | DEV |
|---|---|---|---|---|
| prod | default | The runtime and the error hooks. | undefined | undefined |
| observe | observe | prod, plus the records channel, the diagnostics channel, attribution support, and server tracing. No console output, no checks. | object | undefined |
| dev | development | observe, plus the development checks and the console reporter. Unminified. | object | object |
The builds nest, so anything that works on the observe build also works on the dev build. The observe build is a little larger than prod. The attribution engine is much larger, but it is a separate import and only ships if you import it.
Opt into the observe build in the Vite plugin:
import solid from "@solidjs/vite-plugin";import { defineConfig } from "vite";
export default defineConfig({ plugins: [solid({ ssr: true, observe: true })],});observe: true adds the observe condition to every environment and turns on sourceNames.
That keeps names like <Checkout>, span.textContent and count through minification, so the paths below name your components instead of saying computed.
Source locations (the at line in a dev console report) stay off unless you set sourceNames: { locations: true }.
Under vite dev you still get the dev build, which includes everything in the observe build, so anything you see there also works in production.
Without the plugin, set resolve.conditions in your bundler (or node --conditions=observe for an unbundled server) and pass sourceNames: true to the compiler yourself.
The two error hooks are part of the runtime, not of OBSERVE.
A production app with no observability tooling at all still gets them; the observe build is for the records and the traces.
Hear the errors your boundaries catch
In the browser, an uncaught error stops the reactive system and goes to reportError, which window.onerror and error monitors already listen to.
An error that a boundary catches does not: the fallback renders, the app keeps running, and no global handler sees it.
configureClientErrors reports those errors:
import { configureClientErrors } from "solid-js";
configureClientErrors({ onError(error, { ownerPath, boundaryPath }) { report(error, { thrownIn: ownerPath?.join(" › "), caughtBy: boundaryPath?.join(" › "), }); },});Click "Place order" with a broken price and the Errored fallback appears; the hook fires once, with ownerPath reading <App> › <Checkout> › <OrderSummary> › computed and boundaryPath reading <App> › <Checkout> › <Errored>.
The first path is where the code broke; the second is what the shopper saw instead.
If reset() hits the same error object again, it is not reported twice.
The paths are only filled in on the observe and dev builds; on the production build the hook still fires, and the paths are undefined.
A root can have its own hook instead of the global one: render(App, el, { onError }) and hydrate(App, el, { onError }) take the same function.
Hear every failure the server handles
On the server, a failure can be handled in several ways that no global handler sees: an Errored fallback rendered into the stream, a Loading fragment that rejected and was handed to the client, a server function that threw, a hydration value that would not serialize, or a failure that fails the whole request.
configureServerErrors reports all of them, once per error object:
import { configureServerErrors } from "@solidjs/web";
configureServerErrors({ onError( error, { kind, handling, ownerPath, boundaryPath, functionId, direct } ) { report(error, { site: `${kind}/${handling}`, thrownIn: ownerPath?.join(" › "), caughtBy: boundaryPath?.join(" › "), serverFunction: functionId, duringRender: direct, }); },});kind and handling tell you what happened:
kind | handling | What happened |
|---|---|---|
render | fallback | An Errored boundary rendered its fallback. |
render | client | A Loading fragment rejected; the client re-renders that subtree. |
render | failed | Nothing contained it; the request fails. |
render | serialize | A value written to the hydration stream would not serialize. |
server-function | thrown | The function threw. direct is true for an in-process call during a render. |
server-function | channel | A returned stream or iterable rejected after the response had started. |
request | failed | Code outside the runtime, such as middleware, passed a failure to reportRequestFailure. |
A failure the runtime never sees, such as an error a middleware catches before rendering starts, reaches the hook only when that code calls reportRequestFailure(error, event) from @solidjs/web; Catching errors shows the call.
The context then carries the request's event, and the hook's return value is ignored, as it is for every failed handling.
The hook runs inside the request scope, so getRequestEvent() works in it.
renderToStream(App, { onError }) and renderToString(App, { onError }) take a per-request hook that replaces the global one for that request.
A monitoring SDK's init() has to run before the modules it patches load; with the Vite plugin, put it in the module named by start.serverSetup, as above.
The hook receives the error as thrown.
What the client receives (the serialized error in an Errored fallback, or the body of a failed server-function call) is a sanitized value, a generic Error outside the dev build.
Return a value from the hook and that value replaces it.
Return the error itself and its message, stack, and any secret they carry reach the browser.
Return a reference the shopper can quote back to you, or nothing.
configureServerErrors({ onError(error, context) { const ref = report(error, context); // The shopper sees "Something went wrong (ref 4f2a)"; the log has the rest. return new Error(`Something went wrong (ref ${ref})`); },});Follow a request into the browser
A request arrives with a W3C traceparent header, or without one.
The server continues the trace it was given or starts a new one, and every getTraceContext() call during the request, including in-process server-function calls, returns the same context.
Forward it from a server function to the services it calls:
import { getTraceContext } from "@solidjs/web";
export async function chargeCard(orderId: string) { "use server"; return fetch(paymentsUrl, { method: "POST", headers: { ...getTraceContext()?.entries }, body: JSON.stringify({ orderId }), });}The runtime also tells the browser which trace the page belongs to, through a Server-Timing header on the response and <meta> tags in the HTML head.
Frame streams and server-function responses have no <head>, so they rely on the header.
You do not need middleware for any of this.
The trace only reaches the browser when the incoming traceparent was sampled or a provider returned one, so a page with no tracing tool sees no change to its responses.
A response that a shared cache may store never carries the trace, because the cache would replay one request's trace to every viewer.
That is a Cache-Control with public or s-maxage (and no no-store or private), or a CDN-Cache-Control a CDN may store under.
A document decides this when its shell head is written, so set the policy before then: with httpHeader while the page renders, or from middleware before next().
import { httpHeader } from "@solidjs/web";
export default async (event, next) => { if (isCachedRoute(new URL(event.request.url).pathname)) { httpHeader("Cache-Control", "public, max-age=0, s-maxage=600"); } return next();};A header set on the returned Response after next() comes too late: the shell, with its <meta> tags, has already been written.
getTraceContext() keeps working either way, so forwarding the trace to downstream services is unaffected.
On the observe build, a tracing tool provides the trace instead of the header:
import { OBSERVE } from "solid-js";
OBSERVE?.server.trace.provide((request) => { const span = activeSpan(); if (!span) return undefined; return { traceId: span.traceId, spanId: span.spanId, entries: { "my-trace": `${span.traceId}-${span.spanId}` }, };});The provider is called once per request, during the request, at the shell flush or the first getTraceContext() read, whichever comes first.
The fields it returns replace the ones the runtime would compute; its entries are merged by name with the runtime's traceparent; returning undefined keeps the runtime's values.
See what the runtime did
OBSERVE.records delivers a plain record each time the runtime finishes one of these, on the server and in the browser:
| Type | Platform | One record per |
|---|---|---|
"render" | server | A renderToString or renderToStream render: how long the shell took and how many boundaries it waited on. |
"boundary" | server | A Loading boundary that waited during a render; one that rendered on its first pass emits nothing. |
"invocation" | server | A server-function execution, from HTTP dispatch or an in-process call. |
"request" | client | A server-function request the page sent, delivered when it is sent, so a call still running has a record. |
"call" | client | A server-function call the page made, as the caller awaited it. |
"frame" | both | A frame stream produced (server) or applied (client). |
"recovery" | client | A Loading boundary the server gave up on, re-rendered as fresh DOM on the client; joins its "boundary" by id. |
Once the attribution engine is enabled, its records ("interaction", "hold", "navigation", "rerun", and the timeline records behind the Performance panel tracks) arrive on the same channel.
Log the boundaries that kept a shopper waiting:
import { OBSERVE } from "solid-js";
OBSERVE?.records.subscribe("boundary", (event) => { if (event.durationMs < 200) return; console.log( `<Loading> at ${event.ownerPath?.join(" › ")} waited ${Math.round(event.durationMs)}ms`, event.outcome );});Render /orders with a slow database and the line reads <Loading> at <App> › <Orders> › <Loading> waited 640ms settled.
A record holds only data: ids, names, an outcome, at on the performance.now() clock, durations, and counts.
Live objects (the request, the response, the arguments, the original error) come in a second argument to the listener, never on the record, so you can send a record off the device as it is.
- A client
"call"and the server"invocation"it caused share anid; the difference between their durations is network time. - The
"request"and"call"records of one call share the sameliveobject, which is filled in as the call proceeds, so a listener that keeps it from the request can read the outcome later. - Request and response bodies are only captured for a listener that asks:
subscribe("call", fn, { bodies: true }). - An invocation made while a boundary renders names that boundary, so you can see which calls a wait was made of.
Listeners run synchronously inside the runtime, as soon as the record is complete. A listener must not write signals; if one throws, the error goes to the console and the other listeners still run. Subscribe from a module that loads before the app; there is one channel per process, so the subscription receives records from every copy of the runtime in the bundle.
What each interaction cost
When a click feels slow, attribution tells you what it waited on. It is the same tool Debugging reactivity uses in development, and on the observe build you can enable it in production:
import { OBSERVE } from "solid-js";import { attribution } from "solid-js/attribution";
const release = attribution.enable({ values: "labels" });
OBSERVE?.records.subscribe("interaction", (event) => { if (event.settledMs === undefined || event.settledMs < 300) return; console.log( `${event.name} on ${event.target} took ${Math.round(event.settledMs)}ms to settle:`, event.holds.map( (hold) => `${hold.blockers.join(", ")} held ${Math.round(hold.holdMs)}ms` ) );});Click "Place order" and the line reads click on button#place-order "Place order" took 840ms to settle: ["placeOrder held 812ms"].
An interaction record includes:
- the handler's own time and the writes it made;
- the re-runs and creations those writes caused;
- when the last effect caused by the interaction ran (
settledMs); - the holds and navigations it caused.
A hold record names what the write waited for, for how long, and whether the screen showed the wait with isPending, latest, or an optimistic value.
silent is true when nothing showed the wait, which the shopper experiences as a click that did nothing; long is true when the wait lasted long enough that a fallback should have shown.
A router that wraps its location write in OBSERVE.attribution.withOrigin names its navigations by the matched route pattern, so all /orders/:id navigations group together.
The route the page first loaded on is named the same way, and a server "render" record carries it as route.
enable() turns attribution on and returns a function that turns it off again.
All tools on the page (an adapter, the Performance panel tracks, a diagnostics capture) share one instance.
Each tool calls enable() separately, the most detailed options win, and attribution stays on until every tool has turned it off.
attribution.disable() turns it off for everyone.
Record subscriptions belong to OBSERVE.records, so turning attribution off does not remove them; only the function subscribe returned does.
attribution.history("interaction"), history("hold"), history("navigation"), and history("rerun") return recent records from a buffer, for a console session that did not subscribe ahead of time.
feedback(), costs(), why(), and subscriptions() are separate exports of solid-js/attribution, so a build that only subscribes to records does not include them.
"rerun" records are only created while something uses them (a "rerun" listener, an imported helper such as costs, or the console log), so history("rerun") and why() are empty for runs before that; subscriptions() reads the current dependencies and always works.
What leaves the process
Records name things: component labels, the name option you gave a scope, store paths, route patterns, server-function ids.
Beyond names, four fields carry data from the page, and a tool that ships records off the device decides what to do with each:
targeton an interaction and on a call's origin: the element astag#id "text", with up to 30 characters of its text content.prevandvalueon a change record and on a held write: previews of the values, strings cut at 40 characters.to,from, andparamson a navigation: the concrete URL and the bound parameters.data.erroron the server's error findings (SSR_RENDER_ERROR_CONTAINED,SERVER_ERROR_SANITIZED): the error as thrown.
The values option of enable() controls the first two when the record is created, so nothing downstream has to remove them:
values | prev / value | target | Default in |
|---|---|---|---|
"full" | previews | element and text: button#save "Save" | dev build |
"labels" | absent | text kept on a button or an a only | |
"none" | absent | element only: button#save | observe build |
When several tools enable attribution, the most restrictive level wins, so a production adapter that passes values: "none" keeps it even if a panel asks for "full".
If your tool exports records, pass the level explicitly instead of relying on the default.
values does not affect to, from, params, or data.error: a tool that exports them should handle them like any URL or captured exception.
A tool that renders inside the app it watches, like a diagnostics panel or devtools, marks its root as its own, so its effects and stores never appear as findings about the app:
import { createRoot, getOwner, OBSERVE } from "solid-js";
createRoot(() => { OBSERVE?.exclude(getOwner()!); // the panel's signals, stores, and effects});A tool that renders the app inside its own shell, <DevToolbar><App /></DevToolbar>, excludes the shell and includes the app again with OBSERVE.include(owner) at the app's root; each part of the tree follows its nearest marked ancestor.
Common problems
OBSERVE is undefined in production
The production build was resolved.
Check that the bundler applied the observe condition to the environment that is undefined; solid({ observe: true }) applies it to every environment, and a custom server that runs unbundled needs node --conditions=observe.
The paths say computed and effect but never a component
The compiler's sourceNames option is off, so components have no labels to record.
solid({ observe: true }) turns it on; with another setup, pass sourceNames: true to the compiler.
Under vite dev the labels are present by default.
No Server-Timing entry and no <meta> on the page
The runtime did not know the trace was recorded: the incoming traceparent had no sampled flag, or there was none and no provider returned one.
Install a provider, or send a sampled traceparent from the edge.
Otherwise, the response has a Cache-Control a shared cache may store, which withholds the trace on purpose.
My tool's own effects show up as findings
Mark the tool's root with OBSERVE.exclude(getOwner()!) as it is created.
Writes into the excluded subtree stay excluded wherever they come from; do not route them through runWithOwner, which makes them writes in an owned scope.
Recap
- Errors are reported on every build through
configureClientErrorsandconfigureServerErrors, once per error object, with where the error was thrown (ownerPath) and where it was caught (boundaryPath). - The server hook's return value is what the client receives; return a reference, not the error.
- Records, traces, and attribution need the observe build:
solid({ observe: true }), or theobservecondition andsourceNamesby hand. OBSERVE.recordsdelivers finished, serializable records from the runtime and from attribution; live objects come in a separate argument, and a listener must not write signals.- The runtime carries a sampled or provided trace into the browser on
Server-Timingand<meta>; no middleware. attribution.enable()thenOBSERVE.records.subscribe("interaction", …)shows what each click waited on; the summary tables are separate exports you pay for only when you import them.valuesonenable()decides whether records carry value previews and element text; an exporter passes it explicitly.- Mark a tool's own root with
OBSERVE.excludeso it never reports on itself.
Next steps
- Build an observability adapter: the contracts a tool author relies on, for an error monitor or a tracing SDK.
- Debugging reactivity: the same records read at a console in development, and the diagnostics they feed.
- Arguments and security: what a server function can trust from the request, including the trace it forwards.
- Boundaries: what
ErroredandLoadingdo with a failure before the hook hears about it.