Skip to content
Skills Library
Programming · Learning & explanation

browser-telemetry-and-errors

/browser-telemetry-and-errors

What the small browser support packages are for and when feature code uses them: packages/react-rum (browser traces, error spans, navigation spans; the host starts it, features do not), packages/error-views (HandledErrorState, HandledErrorAlert, FormServerError, AggregateReadOnlyGate, resolveErrorCopy), the error presentation registry (now @langwatch/handled-error/presentation; packages/error-presentation is a deleted spelling), @langwatch/browser-host/errors (showErrorToast, applyHandledErrorToForm), and packages/design-system-internal (the paper look of internal consoles, not the product). U

Repository
langwatch ↗
Licence
Apache-2.0
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

What the small browser support packages are for and when feature code uses them: packages/react-rum (browser traces, error spans, navigation spans; the host starts it, features do not), packages/error-views (HandledErrorState, HandledErrorAlert, FormServerError, AggregateReadOnlyGate, resolveErrorCopy), the error presentation registry (now @langwatch/handled-error/presentation; packages/error-presentation is a deleted spelling), @langwatch/browser-host/errors (showErrorToast, applyHandledErrorToForm), and packages/design-system-internal (the paper look of internal consoles, not the product). U

Original author description

What the small browser support packages are for and when feature code uses them: packages/react-rum (browser traces, error spans, navigation spans; the host starts it, features do not), packages/error-views (HandledErrorState, HandledErrorAlert, FormServerError, AggregateReadOnlyGate, resolveErrorCopy), the error presentation registry (now @langwatch/handled-error/presentation; packages/error-presentation is a deleted spelling), @langwatch/browser-host/errors (showErrorToast, applyHandledErrorToForm), and packages/design-system-internal (the paper look of internal consoles, not the product). U

How it works

  1. packages/react-rum: the host's, not yours
  2. The registry and readHandledError
  3. packages/error-views: what to render
  4. @langwatch/browser-host/errors: toasts and forms
  5. packages/design-system-internal: not the product
  6. Traps
Original SKILL.md headings · 77 lines, 756 words
SKILL.md preview
---
name: browser-telemetry-and-errors
description: "What the small browser support packages are for and when feature code uses them: packages/react-rum (browser traces, error spans, navigation spans; the host starts it, features do not), packages/error-views (HandledErrorState, HandledErrorAlert, FormServerError, AggregateReadOnlyGate, resolveErrorCopy), the error presentation registry (now @langwatch/handled-error/presentation; packages/error-presentation is a deleted spelling), @langwatch/browser-host/errors (showErrorToast, applyHandledErrorToForm), and packages/design-system-internal (the paper look of internal consoles, not the product). Use when someone says 'show an error', 'toast the error', 'error.message', 'HandledError in the UI', 'form server error', 'field errors from the server', 'error page', 'RUM', 'browser tracing', 'browser.error span', 'react-rum', 'error-views', 'error-presentation', 'readHandledError', 'design-system-internal', 'console UI', 'haven hub styling', or 'aggregate read-only notice'."
user-invocable: true
---

# Browser telemetry and errors

Record: `dev/docs/ARCHITECTURE.md` section 10.2 (browser telemetry, the paragraph "Browser telemetry"), section 12 (errors),
section 15 and 16 (deleted and renamed names). The component choice and tokens are the `design-system` skill; where a
browser file goes is `browser-module`. This page is the four support packages and the one rule that ties the errors
together: **a screen renders a failure from the code-keyed registry, never from `error.message`.**

## packages/react-rum: the host's, not yours

`@langwatch/react-rum` correlates browser traces with backend traces (ADR 058, `dev/docs/adr/058-full-stack-trace-correlation-browser-rum.md`).
It exports `startBrowserTracing`, `startBrowserErrorCapture`, `startNavigationSpan`, `NavigationContextManager`, the session
helpers and the constants (`RUM_DEFAULT_SAMPLE_RATIO`, `RUM_TRACES_PATH`, `RUM_SESSION_HEADER`).

- It is on by default wherever a collector is configured. Console errors, uncaught errors and rejected promises leave as
  `browser.error` spans through our RUM endpoint, which forwards them to the collector over OTLP and to PostHog when PostHog is configured.
- Only `@langwatch/browser-host` depends on it: `packages/browser-host/src/telemetry/browser-tracing.ts`
  (`useBrowserTracing`, fed resolved public config) and `navigation-tracing.ts` (one span per navigation).
- **Feature code never imports it.** A module's browser does not start tracing, create a provider or add its own error
  listener; the shell already does. Throwing or rejecting is how a failure reaches RUM. Error text is sanitised and capped in
  the package (`sanitiseErrorMessage`, `BROWSER_ERROR_MAX_LENGTH`), so do not worry about leaking a URL query; do put nothing
  secret in a message anyway.
- Change it only when the task is the telemetry itself (sampling, a new span). It is a framework package.

## The registry and `readHandledError`

A server failure arrives as a `HandledError` with a stable code. The customer copy, title, tips and docs link for each code
live in `packages/handled-error/src/presentation.ts` and `remediation.ts` (record section 12). Subpaths:
`@langwatch/handled-error/presentation` (`explainAnyError`, `explainHandledError`), `/read-handled-error` (`readHandledError`,
`readErrorTraceId`), `/app-codes`, `/docs-url`.
`@langwatch/error-presentation` is a deleted spelling (section 15); a stale `packages/error-presentation/dist` may still sit on disk. Do not import it.

A new code needs copy: add it to the registry in the same change as the contract's `HandledError` subclass, or the screen
shows the generic "We've been notified" line.

## packages/error-views: what to render

`@langwatch/error-views` (`packages/error-views/src/views.tsx`) is the React half over the registry. It uses the design system.

| You have                                                | Use                                                                                                                                                          |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| a whole page that failed to load                        | `<HandledErrorState error={error} fallbackTitle="Couldn't load datasets" />`                                                                                 |
| a failed read or action inside a page                   | `<HandledErrorAlert error={error} fallbackTitle=... onRetry={refetch} />` (`onRetry` adds a Try again button)                                                |
| a rejected form submit                                  | `<FormServerError form={form} />` in the form's whole-form slot                                                                                              |
| text copy without a component                           | `resolveErrorCopy({ error, title?, fallbackTitle? })`: title, description, tips, docsUrl, traceId; `ErrorActions` renders the trace id and docs link from it |
| a screen that must be read-only on an aggregate project | `<AggregateReadOnlyGate isAggregate={...}>` (`modules/dataset/browser/src/ui/sections/datasets.screen.tsx:22`)                                               |

The trace id is always offered. Keep the data you already have visible beside a failed refetch; show the alert, do not blank the page.

## @langwatch/browser-host/errors: toasts and forms

Host services, not components (`packages/browser-host/src/errors.ts`):

- `showErrorToast({ error, ...options })` for a failed action with no form. Never `toaster.create({ description: error.message })`.
- `applyHandledErrorToForm({ error, form, hasFormErrorSlot })` places the server's `meta.fieldErrors` on the fields and, when
  none apply and there is a whole-form slot, writes `root.serverError` (shown by `FormServerError`). It answers `true` when it
  placed something: then do not also raise a toast. Example: `modules/agent/browser/src/ui/sections/workflow-selector-drawer.tsx:1`.
- `markHandledGlobally` / `isHandledByGlobalHandler`: a global interceptor already reported this failure; do not report it again.
- Alert versus toast: an inline alert for a failure that belongs to the content on screen; a toast for a failed action whose
  context is gone. One failure is reported once.

## packages/design-system-internal: not the product

The paper look (cream paper, warm ink, one orange, serif headings) of the internal consoles: the haven hub and stack home,
the IdP simulator, the mail sink, the mail room and Storybook chrome (ADR 160, `packages/design-system-internal/README.md`).
React and CSS only, no Chakra, no product design system. Colours, fonts, radii and spacing come from its tokens and
`styles.css`; a console writes no literal of its own. The product UI never imports it; the only consumers are internal
consoles, `packages/design-system`'s Storybook tooling, `packages/mail`, `packages/sim-console`, `apps/*-web` and the haven
orb panel in `apps/ui/vite/haven-orb/`. If you are writing a customer screen, you want `design-system`.

## Traps

- Displaying `error.message`: the tRPC wire message is the code slug. Render from the registry.
- Importing `@langwatch/react-rum` in a module: the host owns it.
- Two copies of the form helper: `modules/auth/browser/src/model/apply-handled-error-to-form.ts` restates the host's
  `applyHandledErrorToForm`; prefer the host's in new code.

Versions

The database has no other skills named browser-telemetry-and-errors.

Database snapshot: 13.11.2026 · package version 30d93324a81d (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100otel-browser
    OpenTelemetry browser/RUM mechanics for SPAs and MPAs. Use for “browser OTel,” “frontend observability,” “Web Vitals,” `sdk-trace-web`, `WebTracerProvider`, `browser-sdk`, browser instrumentations, page-load or route tracing, sessions, clicks, console capture, JavaScript errors,…
  • 100cx-rum-setup
    Use this skill when the user asks to "add RUM", "set up RUM", "install the RUM SDK", "add Coralogix RUM to my app", "create a RUM API key", "RUM public key", "init Coralogix RUM", "CoralogixRum.init", "add the browser SDK", "real user monitoring", "frontend monitoring", "monitor…
  • 100cx-telemetry-querying
    Use this skill for any question involving telemetry data: "investigate an issue", "debug a problem", "find out why something is slow", "check error rates", "analyze user behavior", "understand a production incident", "query telemetry data", "look at logs", "search logs", "find…
  • 95go-error-handling
    Use when Go error handling with error wrapping, sentinel errors, and custom error types. Use when handling errors in Go applications.
  • 100ailang-packages
    Create, validate, and publish AILANG packages with correct conventions. Use when user asks to create a new package, fix package errors, add dependencies, publish to registry, or import packages. Also use when encountering `IMP010`, `LDR001`, `MOD010`, or `export type` errors…
  • 100ailang-packages
    Create, validate, and publish AILANG packages with correct conventions. Use when user asks to create a new package, fix package errors, add dependencies, publish to registry, or import packages. Also use when encountering IMP010, LDR001, MOD010, or export type errors during package development.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.