Skip to content

feat(web): add browser and server diagnostics - #254

Draft
omznc wants to merge 5 commits into
mainfrom
feat/web-diagnostics
Draft

omznc wants to merge 5 commits into
mainfrom
feat/web-diagnostics

Conversation

@omznc

@omznc omznc commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

What

A production check found three faults that PostHog could not explain: a minified React error #418 on /:orgSlug/time, a Firefox "NetworkError when attempting to fetch resource" with no request, and enterOrganization calls that hung for 60 s. This PR adds the data to find such faults.

  • Web vitals. lib/posthog-client.ts sets capture_performance: { web_vitals: true, __preview_web_vitals_soft_navs: true }. A client web_vitals boolean wins over the project's $web_vitals_enabled_server_side. The default attribution covers INP and LCP. CLS is left out because its attribution keeps detached DOM nodes and can leak memory in an SPA. The proxy already forwards the lazy /static/web-vitals*.js script, because it matches the static prefix.
  • Soft navigations. __preview_web_vitals_soft_navs makes each router change its own measurement. It needs no Origin-Trial token or flag. The README of web-vitals 6.2.1 (the version posthog-js loads) says the feature is in Chromium from version 151, and src/lib/softNavs.ts guards on PerformanceObserver.supportedEntryTypes and says the API "was launched to stable unflagged". Other browsers measure the page load, as before. In Chrome, the metrics of the first page are final at the first soft navigation.
  • Hydration errors. src/client.tsx is the default Start client entry plus onRecoverableError. It calls posthog.captureException with react_component_stack, html_lang, html_translated (Chrome page translation) and pathname, then console.error. It does not call reportError, so an error is not captured twice by the error event autocapture.
  • Slow server functions. captureFailure times next(). A call of SLOW_SERVER_FN_MS (1000 ms) or more sends server_fn_slow (server_fn_id, server_fn_name, server_fn_file, duration_ms, threw), also when the call throws. A call still pending at PENDING_SERVER_FN_MS (10 s) sends server_fn_slow at that mark with pending: true, so a call that never ends is also reported; it sends no second slow event when it ends. The error report and the slow report share one session read, and one request sends at most one slow event.
  • Network failures. The .client() half of the function middleware wraps the fetch of the server function (next({ fetch })). Only a TypeError that the fetch itself rejects with sends server_fn_network_error (server_fn_id, message, online). The error is rethrown unchanged. A TypeError that a handler threw on the server, and a non-2xx answer such as a 502 from the proxy, send nothing. A fetch with an aborted signal, and a fetch that fails after pagehide (Firefox and Safari reject in-flight fetches on unload), send nothing either.
  • Docs: docs/domains/deployment.md and apps/web/CLAUDE.md.

Checks

bun run typecheck, bun run check (warnings only, none new), bun run test (web: 333 pass, with tests for the slow-call threshold and the fetch wrapper), bun run complexity, cccc with limits 15/10 on the changed files, bun run build in apps/web.

The build bundle holds the new handler and event names, nothing from posthog-node or @farmer/core, and prune-client-assets.ts prunes nothing.

Known limits

  • The component names in the stack are minified, because the build uploads no sourcemaps.
  • server_fn_network_error holds the hash id of the server function. The server build file __23tanstack-start-server-fn-resolver-*.js maps that id to a name. server_fn_slow holds the id and the name, so the events join on server_fn_id.
  • In a nested in-process call, the one slow event of a request is for the inner call, which ends first.

Not verified

A local run sends no PostHog events (production-only gate), so no event was seen end to end. Chrome translation, soft navigation vitals and a real network failure were not tried in a browser.

A production check found three faults that PostHog could not explain:
a minified React error #418 with no component name, a Firefox network
error with no request, and a server function that hung for 60 s.

- Turn on web vitals with attribution and soft navigations in
  posthog-js. The client value wins over the project's remote setting.
- Add src/client.tsx, the default Start client entry plus an
  onRecoverableError that captures the error with the component stack,
  the page language and the Chrome translation flag.
- Send a server_fn_slow event from the server function middleware for
  a call of 1 s or more, also when the call throws.
- Send a server_fn_network_error event when the fetch of a server
  function fails before an answer. The error is rethrown unchanged.
The posthog-js default already attributes INP and LCP only. CLS
attribution keeps detached DOM nodes and can leak memory in an SPA, so
the explicit value true is removed and a comment says why.
The client middleware caught any TypeError from next(). That also
matched a TypeError that a handler threw on the server, which TanStack
sends back and throws again, and it missed a 502 with an HTML body.

- Wrap the fetch of the server function and pass it through next().
  Only a rejection of the fetch itself sends the event. The error is
  rethrown unchanged.
- Name the client event property server_fn_id, because the value is the
  hash. Add the same property to server_fn_slow so that the events join.
- Read the session one time for a call, for the error report and the
  slow report together. One request sends one slow event.
- Remove the clock parameter of captureFailure. The test controls
  performance.now and waits on a condition, not on a fixed time.
- Add tests for the client fetch wrapper.
The slow report was sent from a finally block, so a call that never
ended sent nothing. This hid the 60 s enterOrganization hang.

Send server_fn_slow with pending: true when a call is still pending
after 10 s. Clear the timer when the call ends. Do not send a second
slow report for the same call at the end.
Firefox and Safari reject an in-flight fetch with a TypeError when the
page reloads or the user leaves. These were reported as network errors.

Skip the report when the request signal is aborted or when the page is
unloading. Set the flag on pagehide and clear it on pageshow.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant