Browser observability

Why local debugging runs out

Your machine is fast, your connection is good, your cache is warm, and you have the exact state you just created. None of that is true for the person filing the bug — and most of the time nobody files one at all. They leave.

Observability is the set of things you put in place so that a session you were not in can still tell you what happened.

Catching what escapes

window.addEventListener("error", (e) => {
  report({ message: e.message, stack: e.error?.stack, source: e.filename, line: e.lineno });
});

window.addEventListener("unhandledrejection", (e) => {
  report({ message: String(e.reason?.message ?? e.reason), stack: e.reason?.stack });
});

Two listeners, and the second is the one people forget. A rejected promise with no .catch never touches window.onerror, so an entire class of async failure goes unrecorded until you add it.

A third exists for resources: window.addEventListener("error", fn, true) with capture on fires for images and scripts that fail to load, which regular error handling misses entirely.

Source maps, and why the stack is unreadable without them

TypeError: e.b is not a function
    at t (main.9f2a1c.js:1:48213)

That is what a minified stack tells you: nothing. A source map maps those positions back to your real files and line numbers.

Send context, not just the error

report({
  message, stack,
  release: __APP_VERSION__,     // which deploy
  url: location.pathname,
  userAgent: navigator.userAgent,
  breadcrumbs: recentActions,   // the last ~20 things that happened
});

The single most useful field is the release. "This started at 14:20 on Tuesday, which is when 4.12 shipped" answers more bugs than any stack trace, because most production bugs are explained by the diff.

Breadcrumbs — a rolling buffer of navigations, clicks, network calls and console messages — are the second. An error message tells you what broke; breadcrumbs tell you what the person was doing.

Rate-limit your own reporting

let sent = 0;
function report(payload) {
  if (sent++ >= 5) return;                 // per session
  fetch("/api/client-error", {
    method: "POST",
    body: JSON.stringify(payload),
    keepalive: true,                        // survives the page unloading
  }).catch(() => {});
}

A render loop that throws every frame will happily send ten thousand reports and take your logging endpoint down with it. Cap per session. And keepalive matters: without it, a report fired as the user navigates away is cancelled — which is exactly when errors happen.

Dry run: report() across seven calls in one session

sent++ reads the value before incrementing, so the fifth call still gets through — 5 >= 5 only turns true starting on the sixth. Five real reports per session, then silence, which is exactly what stops a throwing render loop from taking the logging endpoint down with it.

Field data beats lab data

import { onLCP, onINP, onCLS } from "web-vitals";

onINP((m) => send({ name: m.name, value: m.value, rating: m.rating, route }));

Read the 75th percentile, never the mean. An average hides the quarter of your users on a mid-range Android phone, and they are the ones leaving. A metric that is fine on average and terrible at p75 is the most common performance situation there is.

Finding what blocked the main thread

new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (entry.duration > 50) send({ type: "long-task", duration: entry.duration });
  }
}).observe({ type: "longtask", buffered: true });

Anything over 50ms on the main thread is a task the browser could not interrupt, which means input during it felt dead. Long tasks are what a bad INP is made of, and this is how you find them in the field rather than guessing on your laptop.

What to do before you debug

1. When did it start? Check the release timeline before opening any code.
2. Who is affected? One browser, one country, one device class narrows it enormously.
3. Can you turn it off? A feature flag or a rollback converts an incident into an investigation you can do calmly.
4. Then reproduce — with 4× CPU throttling and a slow network, not on your machine as it is.

The privacy part, which is not optional

Error payloads pick up more than you intend: URLs with tokens in the query string, form values in breadcrumbs, email addresses in a stack's local variables. Session replay records the screen. Strip, mask and allow-list before sending, and know what your privacy policy actually promises — this is the one area where a debugging convenience can become a legal problem.