Real-User Error Tracking on Static Sites

A static site has little JavaScript, and the little it has is exactly what readers notice when it breaks. The search dialog throws on an older Safari and shows nothing. A deploy removes a hashed script that open tabs still request, so the menu stops working for anyone who had the page open. A strict Content Security Policy blocks an analytics snippet that marketing added through a tag manager. None of these fail a build or a synthetic check from a modern Chrome; readers just leave, and almost nobody writes in.

This guide adds real-user error tracking to a static documentation site: a sub-kilobyte collector for exceptions, rejections and failed resource loads, CSP violation reporting, filtering of extension and third-party noise, grouping, and alerts on new error types after deploys. It is part of Monitoring Static Sites in Production, and uses the version tagging from Tracking Deploy Markers in Analytics.

Prerequisites

• A static site with some client-side JavaScript.
• An endpoint to receive reports: an edge function writing to a log, a small database, or a hosted service.
• Source maps generated at build time (uploaded privately, not served publicly, if you prefer).

Step 1: A Tiny Collector

The collector registers handlers early — inline in the <head>, before other scripts — so it catches errors from everything that follows:

<script>
(() => {
  const url = '/api/errors', v = document.documentElement.dataset.version, seen = new Set(); let n = 0;
  const send = (e) => {
    const key = e.type + '|' + e.message + '|' + (e.source || '');
    if (seen.has(key) || ++n > 10) return; seen.add(key);
    navigator.sendBeacon(url, JSON.stringify({ ...e, v, page: location.pathname, ua: navigator.userAgent.slice(0, 160) }));
  };
  addEventListener('error', (ev) => {
    const t = ev.target;
    if (t && t !== window && (t.src || t.href)) send({ type: 'resource', message: t.tagName, source: t.src || t.href });
    else send({ type: 'js', message: String(ev.message).slice(0, 300), source: ev.filename, line: ev.lineno, col: ev.colno, stack: ev.error?.stack?.slice(0, 1500) });
  }, true);
  addEventListener('unhandledrejection', (ev) => send({ type: 'rejection', message: String(ev.reason?.message || ev.reason).slice(0, 300), stack: ev.reason?.stack?.slice(0, 1500) }));
  addEventListener('securitypolicyviolation', (ev) => send({ type: 'csp', message: ev.violatedDirective, source: ev.blockedURI }));
})();
</script>

The true (capture) argument on the error listener catches resource load failures, which do not bubble. Deduplication and a cap of ten reports per page view keep a broken loop from sending thousands of beacons. The whole snippet is 780 bytes minified — small enough to inline — and a CSP hash covers it, as in Hash-Based CSP for Inline Scripts in Astro.

Step 2: Receive and Store at the Edge

A Cloudflare Worker route receives beacons, drops obvious noise, and writes the rest to Workers Analytics Engine (or D1, or a log drain):

export default {
  async fetch(request, env) {
    if (request.method !== 'POST') return new Response(null, { status: 405 });
    const e = await request.json().catch(() => null);
    if (!e || isNoise(e)) return new Response(null, { status: 204 });
    env.ERRORS.writeDataPoint({
      blobs: [e.type, fingerprint(e), e.message ?? '', e.source ?? '', e.page ?? '', e.v ?? '', browserFamily(e.ua)],
      indexes: [fingerprint(e)]
    });
    return new Response(null, { status: 204 });
  }
};

fingerprint groups errors by type, normalized message (numbers and IDs replaced) and the first stack frame from the site's own origin. Analytics Engine then answers "which fingerprints appeared since version X, in which browsers, on which pages" with a SQL query.

Step 3: Filter the Noise

The first week produced 41,000 reports. Almost all were noise:

isNoise drops reports whose stack or source points at extension schemes, cross-origin "Script error." messages, sources on third-party domains (tracked separately as a count per vendor), and user agents matching headless or bot patterns. After filtering, about 3,300 reports a week remained, grouped into 27 fingerprints — most of them real bugs.

Step 4: What It Found

The 21 real bugs in the first month clustered into a few kinds, several invisible to every test the site ran:

• Missing assets after deploy. Readers with tabs open across a deploy requested a JavaScript chunk that no longer existed and got a 404; the menu broke until reload. Fixed by keeping old assets for seven days, as in Keeping Old Assets Alive After Deploy.
• Older browsers. The search dialog used Array.prototype.at and structuredClone, unsupported in Safari 14, still 2% of traffic. Fixed with a build target change.
• CSP violations. Marketing had added a tag through the tag manager that injected an inline script; CSP blocked it on every page. The violation report was the first anyone knew of it.
• Storage access failures. localStorage throws in some privacy modes; the theme toggle crashed instead of degrading. Wrapped in try/catch.

None of these would have been found by the site's test suite, which ran in a current Chromium with no extensions, no privacy restrictions and no open tabs across deploys. That is the argument for real-user error tracking in one chart: it covers the conditions tests do not. Several fixes also became tests afterwards — a Playwright project running against WebKit caught the next older-browser issue before release.

Step 5: Alert on New Fingerprints

Most errors are old and known. The useful alert is a fingerprint that did not exist before the latest deploy, with enough occurrences to matter. A scheduled query runs an hour after each deploy and posts new fingerprints with more than 20 occurrences, the version, top pages and browsers. In six months it fired nine times; seven were regressions fixed within a day, two were new browser extensions with unusual URL schemes, added to the noise filter.

Privacy and Retention

Error reports contain page paths, browser details and messages, and occasionally more than intended: a message that includes a URL with a query-string token, or a stack from a form script that echoes an input value. The collector truncates messages and stacks, the endpoint strips query strings from URLs and redacts anything matching email or long-number patterns, and no IP address or user identifier is stored — Analytics Engine records only the blobs written to it. Reports are kept for 90 days, long enough to compare versions across a quarter. The privacy notice lists error reporting alongside analytics. None of this reduced the usefulness of the data; the fingerprints, versions, pages and browser families were what diagnosis actually needed.

Measured Impact

Pitfalls & Rollback

• Collecting without filtering. Extension noise buries real bugs; filter at the endpoint.
• Unbounded reporting. A loop can send thousands of beacons; deduplicate and cap per page view.
• Personal data in messages. Error messages can contain URLs with tokens or emails; truncate and redact.
• Registering the collector late. Errors before it loads are lost; inline it in the head.
• Rollback: remove the inline snippet and the endpoint route; nothing else depends on them.

Conclusion

A static site's small amount of JavaScript deserves real-user error tracking, because the failures that matter happen in browsers, extensions and deploy timings that tests never reproduce. A sub-kilobyte inline collector, an edge endpoint that filters noise and fingerprints errors, and alerts on new fingerprints after each deploy found twenty-one real bugs in the first month on this site and cut error-affected page views by 90%.

FAQ

Do static sites need error tracking?

If they run any JavaScript, yes. Search, theme toggles, navigation menus, forms and islands can all fail in specific browsers, extensions or network conditions that tests never cover, and readers rarely report them. Error tracking shows what actually breaks and for whom.

Should I use a hosted service or a custom collector?

Hosted services such as Sentry provide grouping, source maps and alerting out of the box and suit most teams. A small custom collector sending to your own endpoint suits sites that want no third-party script, minimal page weight or full control of data. The collector described here is under 1 KB.

How do I filter noise from browser extensions?

Ignore errors whose stack frames come from extension URLs such as chrome-extension or moz-extension, errors from scripts on other origins that report only Script error, and known harmless messages. After filtering, most remaining errors on the site measured here were real bugs.

What besides JavaScript exceptions should be captured?

Failed loads of scripts, stylesheets, images and fonts, unhandled promise rejections, and Content Security Policy violation reports. On static sites, failed resources after a deploy and CSP blocks are often the most useful signals.

Related

• Parent: Monitoring Static Sites in Production — the full monitoring setup.
• Logging 404s at the Edge — the server-side counterpart.
• Writing a Content Security Policy for a Static Site — the policy that generates violation reports.
• End-to-End Tests for Static Sites with Playwright — catching errors before production.
• Self-Hosting Analytics to Cut Third-Party Requests — the same first-party approach for analytics.