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.jsis 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-errorson the shop's own host, as JSON, withnavigator.sendBeacon. - The server scrubs the report again, then counts it in
badger.client.errors{siteId,kind}and writes oneWARNlog 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'sfragment/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. ItsauthStylesfragment 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.htmlandnova/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"}
assetis the script's path under/settBuilder/with the content hash, query and origin removed,inlinefor a script in the page, orother. The page's own URL is never sent: an inline script's frames sayinline, and the page is described bypageTypealone.- A frame from anywhere else is sent as
otherwith 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
TenantResolutionFilterresolved from theHostheader, read throughSiteContextProducer. A report can't name a shop. - No visitor, no cookies. The path is listed in
StatelessPaths:UserResolutionFilterskips it, so no visitor is looked up, created or saved and noBDGR_USRcookie is written;OrderResolutionFilterskips it in turn; andTenantResolutionFilterdoesn'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
415with 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 is204 No Contentwith 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 asbadger_client_errors_total, taggedsiteIdandkind(errororrejection). 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 asbadger_client_errors_dropped_total, taggedreason(invalid,rate_limited). Not tagged by shop. -
Log: one
WARNline per counted report, fromClientErrorServiceImpl: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.
Cookie consent¶
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,sessionStorageor 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 (
authmodule, 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 doeserror/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 bynpm test, and by Maven in thetestphase) covers which errors are reported, the payload, the cap, de-duplication, sampling, sending, and that the script touches no cookie or storage.ClientErrorScrubberTestandClientErrorServiceImplTest(commerce-core) cover the scrubbing, the metric, the log line, the kill switch and the rate limits.ClientErrorBeaconInterceptorTestandClientErrorBeaconFragmentTest(web-mvc) cover the script tag: when it is printed, and its settings.ClientErrorBeaconHeadsTestandClientErrorBeaconStandalonePagesTestcover which templates carry it.ClientErrorControllerTestandStatelessPathsTest(web-mvc) cover the endpoint:204every 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-errorsanswered204, the web log shows theClient errorline, andbadger_client_errors_totalappears at the web pod's/actuator/prometheus.