Skip to content

Browser Error Beacon

When a storefront script fails in a shopper's browser, nobody on our side would otherwise know: the page still renders, a button simply does nothing. The error beacon reports those failures, tagged with the shop, so they show up in Grafana next to the server's own errors. It carries no personal data, sets no cookies and stores nothing in the browser.

It is part of step 3 of the Front-End Direction, alongside the Storefront Asset Build.

In short

  • client-errors.js is loaded first in every theme's head, and in the head of each standalone page that writes its own (sign-in, registration, password, review, messaging and shop-closed pages). It listens for uncaught errors and unhandled promise rejections, and reports the ones thrown by the shop's own scripts.
  • A report goes to POST /api/client-errors on the shop's own host, as JSON, with navigator.sendBeacon.
  • The server scrubs the report again, then counts it in badger.client.errors{siteId,kind} and writes one WARN log line naming the shop and the release.
  • It is on for every shop. A global setting switches it off everywhere.

The script

web-mvc/src/main/resources/resources/settBuilder/themes/shared/js/client-errors.js, about 3 KB minified (1.5 KB compressed). Each theme's fragment/head.html includes Nova's fragment/client-errors :: beacon before any other script, so the beacon is listening before the others run. The script tag goes through #assets.url, so it is served as a hashed, immutable copy when the build made one.

Pages with their own head

Most pages take their <head> from the theme's fragment/head.html, which includes the beacon. A few write a whole <head> themselves, and each includes the same fragment, after its charset and viewport metas and ahead of its other scripts:

  • nova/ui/auth-head.html: the shared head of the forgot, reset and change password pages in every theme (through each theme's fragment/auth-head), the payment link page, the Gift Aid declaration, the legal document snapshot, the review pages and the mailing-list confirmation and unsubscribe pages. Its authStyles fragment has no beacon of its own, since a page that writes its own head (registration) includes the beacon itself.
  • nova/registration.html (sign in and register), nova/demoLogin.html, nova/loginError.html and nova/shopClosed.html.

ClientErrorBeaconInterceptor is registered for every storefront route (it has no path patterns), so these pages get the model attribute like any other; where a page renders without it the fragment prints nothing and the page is unaffected.

ClientErrorBeaconHeadsTest (web-mvc) fails when a storefront template that writes its own <head> lacks the fragment, has a script ahead of it, or is replaced by a head fragment the test doesn't know (it checks fragment/head, fragment/auth-head and ui/auth-head where they are defined). Pages that must go without are listed, each with a reason, in web-mvc/src/test/resources/beacon-exempt-heads.txt; a line whose page now includes the beacon fails the test until it is removed. ClientErrorBeaconStandalonePagesTest renders these heads and checks the script comes once, first, and not at all without the model attribute.

It reads its settings from data-* attributes on its own tag:

Attribute Meaning
data-endpoint Where reports go: /api/client-errors
data-sample The percentage of page views that report (0 to 100)
data-release The platform release, to match a stack to its source maps
data-page-type The kind of page: the controller's pageType where it sets one (collection, searchResults), otherwise the template's name (product, checkout-payment); absent when neither is a short word

The values come from the model: ClientErrorBeaconInterceptor adds clientErrorBeacon to every rendered page while the beacon is on, and the head prints nothing without it. The script shows the shopper nothing, so it has no storefront text.

What it reports:

  • Only the shop's own scripts. An error counts when its stack, or the file the browser names, leads to a script under /settBuilder/ on the page's own origin, or to an inline script in the page. Errors from browser extensions, other sites' tags, and cross-origin "Script error." events are ignored. A rejection whose reason has no stack (Promise.reject('x')) can't be traced to a script and is ignored too.
  • At most five reports a page view, and the same error from the same place only once.
  • A sample of page views: the script decides once per page whether this view reports at all.

A report:

{"v": 1, "kind": "error", "message": "TypeError: x is undefined",
 "asset": "themes/nova/js/fragments.js", "line": 12, "col": 34,
 "frames": [{"asset": "themes/nova/js/fragments.js", "line": 12, "col": 34, "fn": "addToBasket"}],
 "pageType": "product", "release": "0.99.0"}
  • asset is the script's path under /settBuilder/ with the content hash, query and origin removed, inline for a script in the page, or other. The page's own URL is never sent: an inline script's frames say inline, and the page is described by pageType alone.
  • A frame from anywhere else is sent as other with no line, column or function.
  • The message is cut to 300 characters and the stack to 10 frames.

If the browser refuses a JSON beacon, the script sends the same body with fetch(..., {keepalive: true, credentials: 'omit'}).

The endpoint

ClientErrorController (web-mvc) serves POST /api/client-errors:

  • Tenant from the host. The shop is the one TenantResolutionFilter resolved from the Host header, read through SiteContextProducer. A report can't name a shop.
  • No visitor, no cookies. The path is listed in StatelessPaths: UserResolutionFilter skips it, so no visitor is looked up, created or saved and no BDGR_USR cookie is written; OrderResolutionFilter skips it in turn; and TenantResolutionFilter doesn't set the site cookie. The browser still sends the shop's existing cookies with a same-origin beacon, and nothing reads them.
  • JSON only. Storefront CSRF protection is off, and another site can't send a JSON body without a CORS preflight, so other sites can't post reports through a shopper's browser. Any other content type, or none, gets 415 with an empty body; the controller answers it itself, so it is never rendered as an error page.
  • Always 204. Whatever becomes of a report (counted, dropped, unreadable), the answer is 204 No Content with no body.
  • Size limit. A body over 8 KB is dropped without being read, whether it declares its length or not. A real report is well under 2 KB.
  • Rate limits. Each pod takes at most 30 reports a minute from one shop (with a burst of 30) and 600 a minute in all (burst 300). Reports over either limit are dropped, not queued.
  • With the beacon switched off, the body isn't read at all.

It is a storefront endpoint, like /api/cookie-consent, and deliberately not part of the REST API's OpenAPI specification: the beacon must be same-origin with the page so that the shop comes from the host, and the REST API is on another host.

ClientErrorService (commerce-core) does the work, so the controller only reads the request.

Scrubbing

ClientErrorScrubber runs on every report before it is counted or logged. The browser script already leaves out page URLs and other sites' scripts; the server can't trust that, so it removes again anything that could identify a person:

In a message Becomes
The query string and fragment of any URL or path removed (/search?q=... → /search)
Email addresses <email>
JSON web tokens, and runs of 20 or more letters and digits that include a digit (keys, hex ids) <token>
UUIDs <id>
UK postcodes <postcode>
Runs of four or more digits, with spaces, dots or dashes between them (card, phone, order numbers) <n>
Quoted values longer than 32 characters or with a space in them (a name, an address) "<value>"
Line breaks and other control or formatting characters a space

The message is then cut to 300 characters. The other fields are kept only when they have the expected shape: a script path ending .js or .mjs with no .. (else other), a page type of letters, digits and dashes, a release number, and a function name of up to 64 characters with no long number in it. Lines and columns outside 0 to 10,000,000 become 0. A report whose kind isn't error or rejection is dropped.

Where reports go

  • Metric: badger.client.errors, exported as badger_client_errors_total, tagged siteId and kind (error or rejection). It isn't tagged with the script: per-shop tags already set the cardinality limit, as for the performance monitor.
  • Dropped reports: badger.client.errors.dropped, exported as badger_client_errors_dropped_total, tagged reason (invalid, rate_limited). Not tagged by shop.
  • Log: one WARN line per counted report, from ClientErrorServiceImpl:

    Client error 3fa2c19b04de on site shop-a: kind=error release=0.99.0 page=product at themes/nova/js/fragments.js:12:34 message="TypeError: x is undefined" stack=[addToBasket themes/nova/js/fragments.js:12:34]
    

    The first value is a fingerprint: the same error from the same place has the same one, so a Loki search can group them. The line names the shop and the release, never the shopper: no address, user agent, cookie, user id or page URL. The hashed copies' source maps map a line and column back to the source.

See Observability for how both reach Grafana.

Settings

Two global settings (System > Global configuration, group client-errors-config):

Key Default Meaning
client-error-beacon-enabled true The kill switch. Off, no page loads the script and reports still arriving from open pages are ignored unread
client-error-beacon-sample-percent 100 The percentage of page views that report. At 0 no page loads the script

There is no per-shop setting: the beacon is a platform check, the same for every shop.

The beacon needs no cookie consent, and Cookiebot is told to leave it alone (data-cookieconsent="ignore"):

  • It sets and reads no cookies and uses no browser storage (no localStorage, sessionStorage or IndexedDB). The server sets no cookie in its answer.
  • It sends no identifier: no visitor id, session id or fingerprint of the device. The fingerprint in the log line describes the error, not the browser.
  • A report carries no personal data: the page URL is never sent, and anything in a message that could identify someone is removed on the server before it is counted or logged.

So nothing is stored on the shopper's device and nothing that identifies them leaves it, which is what consent rules for cookies and similar technologies are about. This reasoning should be checked again whenever the payload changes.

Not covered

  • Pages served by the separate auth application (auth module, its own host) don't load the beacon: it reports to the shop's own host, and that application is not a shop.
  • The storefront error pages (error/4xx.html, 5xx.html, shopNotFound.html) don't load it: they are rendered on the error dispatch, often with no shop resolved, and run no script of their own. Nor does error/admin.html, the back office's error page.
  • Errors before the beacon's script has run (a failing script earlier in the head than the beacon, such as a shop's own tag added through a meta-tag extension) aren't seen.
  • Rate limits are per pod, so the cluster-wide caps are the per-pod caps times the number of web pods.

Checking it

  • web-mvc/src/test/js/client-errors.test.js (run by npm test, and by Maven in the test phase) covers which errors are reported, the payload, the cap, de-duplication, sampling, sending, and that the script touches no cookie or storage.
  • ClientErrorScrubberTest and ClientErrorServiceImplTest (commerce-core) cover the scrubbing, the metric, the log line, the kill switch and the rate limits.
  • ClientErrorBeaconInterceptorTest and ClientErrorBeaconFragmentTest (web-mvc) cover the script tag: when it is printed, and its settings. ClientErrorBeaconHeadsTest and ClientErrorBeaconStandalonePagesTest cover which templates carry it.
  • ClientErrorControllerTest and StatelessPathsTest (web-mvc) cover the endpoint: 204 every time, JSON only, the size limit, the kill switch, and that the tenant, user and order filters together write no cookie and create no visitor.
  • On a running stack, open a shop page and, in the browser console, fake an error from one of the shop's scripts (an error thrown from the console itself is ignored, as it isn't one):

    dispatchEvent(new ErrorEvent('error', {message: 'test', lineno: 1, colno: 1,
      filename: location.origin + '/settBuilder/js/test.js'}))
    

    The network panel shows the POST /api/client-errors answered 204, the web log shows the Client error line, and badger_client_errors_total appears at the web pod's /actuator/prometheus.