Design a frontend logging and error SDK

Requirements exploration

Every frontend team ships bugs that only appear on real devices: a Safari version the team never tested, a browser extension that rewrites the page, a slow phone where a race finally loses. Without an SDK in the page, those bugs are invisible. The server logs show a healthy 200 for the HTML, and the user sees a blank screen.

So the job sounds simple: catch errors, send them home. But the error a browser hands you is often useless on its own. It may say only Script error., or point to line 1, column 48,213 of a minified file, or be one of 40,000 copies of the same bug. Most of the design is about turning raw browser failures into something an engineer can act on, while staying small, private, and harmless.

A few words first: an event here is one captured error or log line, with its context. An issue is a group of events that the backend decides are the same bug. A release is one deployed build of the app, named by a version or a commit hash. Symbolication means turning a minified location like app.4f9c.js:1:48213 back into checkout/Cart.tsx:88 using a source map.

Questions to ask first

• Is this SDK for our own app, or a product other companies install? Our own app means one framework, one build pipeline, and we control the source maps. A product like Sentry means any framework, any bundler, and much stricter rules about bundle size and never breaking the host.
• Errors only, or logs too? Errors are rare and precious. Logs (info, warn, debug) can be 100 times more frequent and need levels, sampling, and a cost story.
• How much traffic? 2 million daily users with 6 page views each is 12 million page views. If 2% of views hit at least one error, that's 240,000 error events a day before dedupe. One bad release can multiply that by 50 in an hour.
• Do we build our own pipeline? We should assume the analytics-style transport (batching, sendBeacon, offline queue) already exists or is shared. That's covered in the analytics SDK guide, so here we focus on what's special about errors.
• Which privacy rules apply? Error payloads are full of accidental personal data: emails in URLs, tokens in request bodies, names in messages. Under GDPR, that can count as personal data even inside a log.
• Do we want session replay? It's the most useful and most expensive feature, with big privacy and bundle-size costs. We should know early whether it's in scope.

Functional requirements

• Capture uncaught errors, unhandled promise rejections, failed resource loads (images, scripts, CSS), errors caught by React error boundaries, and failed network requests.
• A public API: captureException(error), captureMessage(text, level), log.info / warn / error(message, fields), setUser, setTag, addBreadcrumb.
• Attach a trail of breadcrumbs: the last navigations, clicks, console lines, and requests before the error.
• Attach context: release, environment, route, a hashed user id, session id, browser and OS, active feature flags.
• Produce stack traces that the server can symbolicate with private source maps and group into issues.
• Scrub personal data before anything leaves the browser.
• Join frontend events to backend traces with a correlation id sent on our API requests.

Non-functional requirements

Out of scope, and why

• The transport layer in detail. Batching, the loader stub queue, sendBeacon and fetch with keepalive, offline queues, and consent are the same as in the analytics SDK guide. We reuse them and only note where errors need different rules.
• Performance metrics like LCP and INP. That is real user monitoring, a sibling product. We'll touch it only where it shares context with errors.
• The backend storage engine. We describe what the dashboard needs from the client, not how to build a columnar store.

What makes this hard

An analytics SDK sends facts the app chose to send. An error SDK sends facts nobody chose: things went wrong in places we didn't expect. That flips several assumptions, and each one drives a later chapter.

• Failures come through many doors. A thrown error, a rejected promise, a broken image, a crash inside a React render, a 500 from the API, a console.error from a library. Each reaches us through a different browser hook, and some reach none by default.
• The raw data is bad. The browser gives a stack trace as a plain string, in a different format per engine, pointing into minified code. For scripts from another origin it may give nothing but Script error.
• Volume is bursty, not steady. Analytics traffic follows users. Error traffic follows bugs: zero for a week, then 50,000 events in ten minutes after a bad deploy, often the same error repeated in a loop.
• The payload is dangerous. Error messages, URLs, and request bodies were never designed to be logged. They contain emails, tokens, and card numbers by accident.
• The SDK runs during the crash. It must work when the app is in its worst state: memory leaking, a loop throwing, the network down. And it must not make that state worse.
• The value is in the grouping. 40,000 events are useless. One issue that says "new in release 4.12, 3,100 users, Cart.tsx line 88, after clicking Pay" is what an engineer can fix.

So the SDK has four jobs, and the chapters follow them: catch every kind of failure. Enrich it with stack, breadcrumbs, and context so the server can symbolicate and group it. Protect the user and the host: scrub data, cap volume, never throw. Send it, reusing the transport we already have.

Capturing errors: every door a failure can come through

The naive SDK sets window.onerror = report and stops. On a real app that misses most failures. Picture a checkout page: a product image returns 404, a fetch to /api/pay returns 503, an await deep in the cart code rejects with nobody catching it, and a React component throws while rendering. window.onerror sees at most one of those four: only the render crash is a thrown script error, and an error boundary may catch it first.

The browser hooks, one by one

Resource errors are the surprise. An image's error event does not bubble, so a listener on window in the normal (bubbling) phase never hears it. But capture runs from window down to the target before the target's own handlers, so a listener registered with true as the third argument sees every failed img, script, and link on the page. To tell them apart from script errors, check event instanceof ErrorEvent: resource failures are a plain Event.

function installGlobalHandlers(hub: Hub) {
  const onError = safe((e: Event) => {
    if (e instanceof ErrorEvent) {
      hub.captureException(e.error ?? e.message, {
        mechanism: "onerror",
        filename: e.filename, lineno: e.lineno, colno: e.colno,
      });
      return;
    }
    const el = e.target as HTMLElement | null;
    if (el && el !== (window as unknown)) {
      hub.captureResourceError(el.tagName, (el as HTMLImageElement).src
        ?? (el as HTMLLinkElement).href);
    }
  });
  const onRejection = safe((e: PromiseRejectionEvent) =>
    hub.captureException(e.reason, { mechanism: "unhandledrejection" }));

  window.addEventListener("error", onError, true); // capture: sees resources
  window.addEventListener("unhandledrejection", onRejection);
  return () => {
    window.removeEventListener("error", onError, true);
    window.removeEventListener("unhandledrejection", onRejection);
  };
}

Rejections whose reason isn't an Error

Promise.reject("nope") and throw { code: 42 } are legal JavaScript. The reason then has no stack, and if we report it as is, every string-rejection in the app collapses into one useless issue.

So the SDK normalizes. If reason is an Error, use it; if it's a string, use it as the message; if it's an object, serialize a few keys safely, with a depth and length cap and a guard against cycles. Then mark the event as synthetic, so the server knows that any stack we add with new Error() points at the SDK, not at the bug.

Errors can also wrap other errors. Since ES2022, new Error("checkout failed", { cause: err }) keeps the original in error.cause. The SDK walks that chain up to a small limit and sends each link as its own exception with its own frames, so the low-level failure isn't lost behind the wrapper. Sentry's linked errors integration does this, following cause up to 5 levels by default.

React error boundaries and their limits

An error boundary is a React component that catches errors thrown while rendering the tree below it, shows a fallback, and lets the rest of the page live. It's the right place to report render crashes, because it also gives a componentStack: the chain of components that were rendering.

But boundaries only catch errors during rendering, in lifecycle methods, and in constructors. They do not catch errors in event handlers (onClick), in async code (setTimeout, an await after a fetch), or in the boundary itself. Those fall through to the global hooks.

React 19 made this easier to wire: createRoot accepts onUncaughtError (no boundary caught it), onCaughtError (a boundary did), and onRecoverableError (React recovered on its own, for example from a hydration mismatch). The SDK's React package passes its handlers there, so render errors are reported once, with the component stack, and aren't double-counted by the global listener.

Network failures and HTTP 5xx

A fetch that gets a 500 does not throw: the promise resolves with response.ok === false. If the app forgets to check, the user sees a spinner forever and the SDK sees nothing. So the fetch wrapper records every request as a breadcrumb (method, URL without query, status, duration) and turns 5xx responses on our own API into events, with a fingerprint by method plus route template (POST /api/orders/:id) so 10,000 failed orders form one issue.

A fetch that rejects means the request never completed: offline, DNS failure, CORS block, or an abort. The message is browser-specific: Failed to fetch in Chrome, NetworkError when attempting to fetch resource. in Firefox, Load failed in Safari. The SDK normalizes those three into one type, NetworkError, and skips AbortError, which the app caused on purpose.

console.error wrapping is a smaller version of the same idea: call the original first so DevTools still works, then record a breadcrumb, and only create an event if the argument is an Error (many libraries log warnings through console.error, and turning each into an issue is noise).

The "Script error." problem: muted cross-origin errors

Sooner or later every error dashboard grows a top issue called Script error. with no stack, line 0, column 0, and tens of thousands of events. It's not one bug. It's every error from every script served from another origin, flattened into one line on purpose.

Browsers do this for safety. If a page could read the full error from any script it loads, an attacker's page could load a script from your bank's origin and learn things from its error messages (for example, whether a user is logged in, based on which error a JSON response produces when run as a script).

So the HTML spec says that when a script is loaded from another origin without CORS, its errors are muted: the error event gets the message Script error., an empty filename, line and column 0, and a null error object, so the real message and the stack are hidden.

Our own app hits this all the time, because the bundle usually lives on a CDN (cdn.shop.com or d1x.cloudfront.net) while the page is on www.shop.com. Different host means different origin. A micro-frontend shell that loads remotes from several teams' origins hits it once per remote (the micro-frontend shell guide covers attribution per app).

The fix: CORS for scripts

1. Add crossorigin="anonymous" to the script tag. The browser now fetches the script in CORS mode, without cookies.
2. Make the CDN answer with Access-Control-Allow-Origin: https://www.shop.com (or * for a public, cookie-less asset).
3. If the CDN caches responses for several origins, also send Vary: Origin, or always send *, so one origin's cached header isn't served to another.

Both halves are required, and getting only one wrong is worse than doing nothing. With the attribute but no header, the CORS check fails and the script doesn't run at all: the outage we were trying to debug becomes a real outage. That's why the change must ship header first, verified, then attribute.

Module scripts (type="module") are always fetched in CORS mode, so an app built that way already needs the header. For classic chunks loaded later, webpack's output.crossOriginLoading adds the attribute to each lazily loaded chunk, which is easy to forget.

For third-party scripts we don't control (a chat widget, an ad tag), we usually can't get the header. Two fallbacks: wrap the callbacks we pass into their APIs in our own try/catch (a caught error is never muted, which is one reason SDKs instrument addEventListener and timers), or simply drop Script error. events whose filename is empty, since without a stack nobody can act on them. Drop them, but count them: a sudden spike still says "something broke in a third-party script after 14:00".

Stack traces and grouping: one bug, one issue

Say release 4.12 ships a bug: Cart.tsx calls data.items.map when items is missing. In an hour it fires 40,000 times across Chrome, Firefox, and Safari. The engineer should see one issue with a count of 40,000. The naive grouping, "same message, same issue", produces at least three, because each engine words the same TypeError differently.

Messages also carry data: Order 18842 not found and Order 18843 not found are the same bug with different ids. So the message is a bad grouping key. The stack is a much better one, but only after two steps: parsing, and symbolication.

Parsing three stack formats

error.stack is not in the ECMAScript standard yet. A TC39 proposal to standardize the property itself is at Stage 3, but it deliberately leaves the string's format to each engine. V8 writes at addToCart (https://cdn.shop.com/app.4f9c.js:1:48213). SpiderMonkey and JavaScriptCore write addToCart@https://cdn.shop.com/app.4f9c.js:1:48213.

Anonymous functions, eval, async frames (V8 prefixes async ), and native code each add variants. V8 also keeps only 10 frames by default (Error.stackTraceLimit). An SDK can raise that limit for its own captures, to 50 for example, at a small cost per error.

The SDK parses the string into a list of frames: { function, filename, lineno, colno }, oldest call first or last by a fixed convention. Each frame is also tagged in_app: true or false: frames from our own bundle are in-app; frames from third-party scripts, browser extensions (chrome-extension://, moz-extension://, safari-web-extension://), and the SDK's own code are not.

Parsing on the client costs a few regular expressions per frame, well under a millisecond, and means the server gets a structured format no matter which engine produced it. Keep the raw string too, capped at a few KB, for formats the parser didn't recognize.

Normalization rules for the fallback are simple and worth naming: replace numbers, UUIDs, hex hashes, emails, and quoted strings in the message with placeholders (Order {n} not found), and map known per-engine messages to one canonical text. That second table is small but valuable: a few dozen entries cover the most common TypeError and ReferenceError shapes.

Source maps: readable stacks without publishing your source

A minified frame like app.4f9c.js:1:48213 means nothing to a person. A source map is a JSON file the bundler writes next to each output file. It maps every position in the minified code back to a file, line, column, and original name in the source, and it can embed the original source text itself (sourcesContent). With it, the server can show src/checkout/Cart.tsx:88 in CartList and even the five lines around it.

The format is standardized by Ecma as ECMA-426, and maps still carry "version": 3. sources lists the original files, names lists original identifiers, and mappings is one long string of Base64 VLQ (variable-length quantity) segments. Each segment links a generated column to a source file, line, column, and optionally a name, all stored as offsets from the previous segment to keep the file small.

The naive setup ships the maps publicly: the bundle ends with //# sourceMappingURL=app.4f9c.js.map, the map sits on the CDN, and the error server downloads it when needed. It works, and it hands your full, commented source code to anyone who opens DevTools. For many companies that's an IP and security problem: internal endpoints, feature names before launch, and comments that say what's broken.

What the server does with them

Symbolication runs in the ingestion pipeline, before grouping. For each frame: find the map (by debug ID, or release plus URL), binary-search the decoded mappings for the generated line and column, read the original file, line, column, and name, and attach a few lines of sourcesContent around it. A large app's map can run to many megabytes, so the server parses each one once and caches the decoded form in memory, keyed by ID.

Frames from files with no map stay minified and are marked so, which is itself a useful signal ("uploads failed for 4.13").

• Make the upload block the deploy. If upload fails, the release is unreadable. A CI step that fails the pipeline is cheaper than a week of minified stacks.
• Keep old maps. Users keep tabs open for days. Errors from release 4.10 still arrive after 4.13 ships, so keep maps for at least as long as you keep events, often 90 days.
• Set the release at build time, not by hand. Inject the git commit hash into the bundle (for example through a define constant), and use the same value for the upload. One source of truth means no mismatch.
• Don't forget lazy chunks and workers. Every output file needs its map uploaded, including code-split chunks and web worker bundles.

Breadcrumbs and context: what happened before the crash

A perfect stack trace says where the code broke. It rarely says why. CartList crashed on items.map, but the cause was three steps earlier: the user opened the cart in a second tab, removed the last item, came back, and clicked Pay, and the API returned 409 with an empty body. That story is what breadcrumbs record: a short trail of the last things that happened, attached to the error when it fires.

What to record, and what not to

Clicks deserve care. Recording the element's visible text is tempting ("clicked Delete account") but that text can be a person's name in a list. A stable selector or a data-track name is safer and still readable. Key presses are recorded as "input in #email", at most once per field per second, never with the key.

A ring buffer with a size cap

Breadcrumbs are recorded all the time but sent only with an error, so they live in memory in a ring buffer: a fixed-size array where each new entry overwrites the oldest. With a cap of 100 entries (also the default of Sentry's maxBreadcrumbs option), a long session never grows the buffer, and recording is a constant-time write.

Each entry is also capped: messages truncated to a few hundred characters, data limited to a handful of keys. A full trail is then around 10 to 20 KB before compression, which is a sensible part of one error event.

type Crumb = { ts: number; category: string; message: string; data?: Record<string, string | number> };

class Ring {
  private items: (Crumb | undefined)[];
  private next = 0;
  constructor(private size = 100) { this.items = new Array(size); }

  push(c: Crumb) {
    this.items[this.next] = c;
    this.next = (this.next + 1) % this.size;
  }
  snapshot(): Crumb[] {
    const tail = this.items.slice(this.next);
    const head = this.items.slice(0, this.next);
    return [...tail, ...head].filter((c): c is Crumb => c !== undefined);
  }
}

Should breadcrumbs survive a reload? Usually not, because memory only is cheaper and safer. The one exception is a crash that reloads the page (an out-of-memory tab, or a location.reload() in an error handler). Some SDKs write the last few crumbs to sessionStorage on pagehide so the next page load can report "the previous page crashed after these steps".

Keep it small and scrubbed; see the client-storage lesson for the limits.

Context: the fields that make an event searchable

• Release and environment: 4.12.0+9f3e1c2, production. Set once at init, injected at build time. Without them there's no regression tracking.
• User: a stable id, hashed with a salt (sha256(salt + userId) computed on the server, or an opaque internal id), never an email. It lets the dashboard count affected users and lets support look up one user's errors on request.
• Session id: random, per tab session. Joins errors, logs, and replay of the same visit.
• Route: the template (/orders/:id), not the URL. Templates group well and carry no ids.
• Feature flags: the evaluated flags for this user (checkout_v2: on). Half of "new in this release" bugs are really "new behind this flag". The feature flag SDK can hand its evaluations to the error SDK through a small hook.
• Browser and OS: parsed on the server from the User-Agent header, or from User-Agent Client Hints. navigator.userAgentData exists only in Chromium browsers, and its high-entropy fields (full version, platform version) need an async getHighEntropyValues call, so the SDK reads them once at startup and caches them.

Context is stored in a scope: a small object of tags, user, and extras that every event copies at capture time. Copying matters. If the scope were referenced instead, an event queued at 10:00 would show the route the user moved to at 10:01.

Scrubbing personal data before it leaves the browser

Look at what a single real error event can contain without anyone meaning it to. The URL: /reset?email=ana@mail.com&token=8f2c.... The message: Invalid card 4111 1111 1111 1111. A breadcrumb: GET /api/users/ana@mail.com, and a request body attached for debugging holds a full address.

Under GDPR, data that can identify a person, like an email address, counts as personal data even inside a log. Once it's in the error store it's copied into backups, search indexes, Slack alerts, and the laptops of everyone who opened the issue. Deleting it on request becomes nearly impossible.

So the rule is: scrub on the client, before the event is queued. Data that never leaves the browser can't leak from any of those places. The server scrubs again as a second line, because SDK versions in the wild are old and app code adds new fields, but the client pass is the one that matters.

The Luhn check on card-like numbers matters. Without it, every 16-digit order id becomes [card] and grouping breaks; with it, about 1 in 10 random digit strings still pass, which is an acceptable false-positive rate for a privacy filter. Scrubbing runs on every string field of the event once, just before queueing, with a cap on total string length so a 2 MB error message can't block the main thread with regex work.

What GDPR changes for the design

• Legal basis. Many teams treat error monitoring as needed to run a secure, working service (a legitimate interest), unlike marketing analytics, which usually needs consent. That argument only holds if the data is minimized. Session replay and full request bodies are much harder to justify without consent. This is a call for the company's privacy team; the SDK's job is to make the minimal mode the default and the richer modes opt-in.
• Minimization and retention. Send only what's needed to debug, and keep it only as long as needed: 30 to 90 days is common for error events.
• Deletion requests. If events carry a stable user id, the backend can find and delete one user's events. That's another reason to use an opaque id rather than an email.
• Region. EU customers often require that events are stored in the EU. That's a DSN or endpoint choice the SDK exposes, not something it can solve alone.

Noise control: dedupe, rate limits, filters, and sampling

Here's a common bad day. A component throws inside a requestAnimationFrame loop. It throws 60 times a second, on 20,000 open tabs. That's 1.2 million events a second aimed at our backend from one bug, each one the same.

The error vendor bills per event, the ingestion queue backs up, and real new issues from other users wait behind the flood. Noise control is how the client keeps that to a trickle without hiding anything new.

Every captured event walks through the same gates, in order, and can be dropped at each one. The order is chosen so the cheapest checks run first and nothing expensive (scrubbing, serializing) is spent on an event that will be dropped.

Ignore rules: errors that aren't ours

• Browser extensions. Password managers, ad blockers, and translators inject scripts into the page. Their errors show frames from chrome-extension://, moz-extension://, or safari-web-extension://. If every frame is from an extension, drop it.
• Known benign errors. ResizeObserver loop completed with undelivered notifications. (older Chrome: ResizeObserver loop limit exceeded) means a resize callback changed layout and the browser deferred some notifications to the next frame. It's almost never a user-visible bug.
• Script error. with no file, as discussed: drop, but count.
• Errors from old releases once a release is retired, and from bots (headless browsers, crawlers) identified by user agent.
• Aborted requests: AbortError from the app's own AbortController.

Ship these rules with defaults, let the app add its own (ignoreErrors: [/^Non-Error promise rejection/], denyUrls: [/googletagmanager\.com/]), and ideally fetch an updated list from the server, so a new benign error from a Chrome update can be silenced without a deploy.

Dedupe and per-issue rate limits

The client can compute a local fingerprint cheaply: error type plus the top three raw frames (file, line, column) plus the normalized message. It's not the server's grouping key (that needs source maps), but within one page load and one release it identifies "the same error again" well enough.

• Consecutive dedupe. If the new event's local fingerprint equals the previous one, drop it and increment a counter on the previous one. This alone collapses a render loop.
• Per-fingerprint budget. Keep a map of fingerprint to count for the page. Send the first 5 of each, then only a summary ("this error repeated 1,840 more times") on page hide.
• Global budget. A token bucket over all errors: for example 10 events per minute with a burst of 30, and a hard cap of 100 per page load. When the bucket is empty, events are counted, not sent.
• Server signal. If the collector answers 429 with Retry-After, the transport stops sending for that long. This is where the client respects the backend's own quota. Sentry's servers also send an X-Sentry-Rate-Limits header with a separate limit per data category, such as errors or replays.

Sampling without losing new issues

Analytics can sample uniformly: keep 10% of sessions and multiply counts by 10. Errors can't, because the rarest events are the most valuable. A crash that hits 3 users a day would vanish with 90% sampling. Sentry's sampleRate for errors defaults to 1.0, keeping every one, and the sampling here is biased:

• Keep 100% of fatal and error level events after dedupe and rate limits, which already removed the floods.
• Sample warning and logs by level (for example 10% of warn, 1% of info), decided once per session so a sampled session is complete, not full of holes.
• Always keep the first event of any fingerprint the client hasn't seen this session, and, if the server sends a list of known noisy fingerprints at startup, sample only those down.
• Send the sample rate with each event (sample_rate: 0.1) so the dashboard can scale counts back up honestly.

Structured logs and joining frontend to backend traces

Errors answer "what broke". Logs answer "what was the app doing": checkout started, payment provider timed out, retrying, cart migrated from v1 format. The naive frontend log is console.log("payment failed for " + orderId). It's a string, so nobody can filter by order, count by provider, or alert on it, and it only exists in a browser console nobody is watching.

A structured log is a JSON object with fixed fields, so the backend can index and query it. The SDK's log API takes a message template and fields separately, and adds context automatically. The frontend-logging lesson covers schemas, levels, and batching as concepts; here we only add what an error SDK changes.

log.warn("payment retry", { provider: "stripe", attempt: 2, orderId });

// queued as:
{
  "ts": "2026-10-21T11:42:07.118Z",
  "level": "warn",
  "message": "payment retry",
  "fields": { "provider": "stripe", "attempt": 2, "orderId": "ord_18842" },
  "release": "4.12.0+9f3e1c2",
  "env": "production",
  "session_id": "s_7b1e",
  "route": "/checkout/:step",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}

• Levels are debug, info, warn, error, fatal. Each level has its own sample rate and on/off switch, and production defaults to info and up.
• A constant message (payment retry, not payment retry for ord_18842) groups and counts well, and is far less likely to contain personal data.
• Fields go through the same scrubber as errors, with an allowlist of field names for anything that looks like user input.
• Remote level control: the SDK can fetch a config that turns on debug for one session id or one user, so support can debug a single customer without flooding everyone.
• Logs as breadcrumbs: every log line is also pushed to the breadcrumb ring, so an error carries the logs that led to it even when the logs themselves were sampled out.

Correlation ids and W3C Trace Context

The frontend error says POST /api/orders returned 500. The backend has a log line about a database timeout at the same minute. Matching by timestamp to tell whether they're the same request fails at 1,000 requests per second. What joins them is a correlation id that the browser creates and sends with the request, and that every backend service logs.

The standard for that id is W3C Trace Context: a traceparent header shaped 00- + 32 hex chars of trace id + - + 16 hex chars of parent span id + - + 2 hex chars of flags, for example 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01. The flags' lowest bit says whether the trace is sampled. OpenTelemetry and most tracing backends, Datadog included, read it, so one header joins the browser's click to the database query.

Two caveats. Sentry's SDKs use their own sentry-trace header by default, and its JavaScript SDK sends traceparent too only when propagateTraceparent is on (from version 10.10). OpenTelemetry's own browser instrumentation exists, but its docs still call client-side support experimental, so check what your backend tracer expects before you pick a header.

The fetch wrapper already sees every request, so it adds the header. Two rules keep this safe:

• Only to our own APIs. traceparent is not a CORS-safelisted header, so adding it to a cross-origin request triggers a preflight OPTIONS request, and if the server doesn't list it in Access-Control-Allow-Headers, the real request fails. Adding it to a third-party API would break that API call. So propagation targets are an explicit allowlist (Sentry calls this option tracePropagationTargets).
• Never trust it for anything but correlation. The backend must treat the incoming trace id as a hint, not as identity or authorization.

With the header in place, the error event stores trace_id, and the dashboard can link the frontend issue straight to the backend trace that failed. The same id also appears in the backend's error response body, which lets a support agent paste it from a screenshot.

The SDK's own safety: never throw, never loop, stay small

An error SDK is code that runs exactly when things are going wrong. If it throws, it either hides the original error or creates a new one, and it does so on every page of the app. Three failure modes deserve design, not just care.

1. Never throw out of the SDK

Every public method and every hook the SDK installs runs inside a try/catch that swallows the SDK's own failures. Serializing an unknown reason can throw (a cyclic object, a getter that throws, a Proxy), so serialization uses a guarded walker with a depth limit of about 5 and a size limit per field. Wrapped globals must behave exactly like the originals: same return value, same this, rethrow the app's error after reporting it, and keep a map from the original listener to the wrapped one so removeEventListener still works.

let internalErrors = 0;
let inSdk = false;

export function safe<A extends unknown[], R>(fn: (...a: A) => R) {
  return (...args: A): R | undefined => {
    if (inSdk) return undefined;      // re-entry: an error raised by our own code
    inSdk = true;
    try {
      return fn(...args);
    } catch {
      internalErrors++;               // sent as a counter in the next healthy batch
      return undefined;
    } finally {
      inSdk = false;
    }
  };
}

2. Never feed on yourself

Loops are the classic SDK outage. The send fails, the fetch wrapper sees a failed request and records an error, which gets queued and sent, which fails. Or the SDK logs a warning with console.error, which the console wrapper captures as an error. The defenses:

• The transport calls the original, unwrapped fetch saved at startup, so its own requests never appear as breadcrumbs or events.
• The SDK's own diagnostics go to the original console, and only when debug: true.
• The re-entry flag above: anything captured while the SDK is already running is dropped.
• Transport failures back off exponentially with jitter, and after a few failures in a row the transport stops trying for the rest of the page (a circuit breaker), keeping a small capped queue for the next page load.

3. Stay small, load the heavy parts later

The SDK must start before the app, or it misses errors during startup. That puts its bytes on the critical path of every page. The split that works:

Errors that happen before even the small core loads, such as a syntax error in the main bundle, are caught by a few lines inlined in the HTML that push to a plain array, the same stub-queue pattern the analytics SDK guide describes. The core drains it on startup.

Session replay, briefly

Session replay records the page as a stream of DOM changes (a full snapshot, then MutationObserver diffs, plus scroll, mouse, and input events) and plays it back like a video next to the error. Open-source rrweb is the base of several products. It's the most direct answer to "what did the user see", and it's expensive in every way: tens of KB of code, CPU on every DOM change, hundreds of KB to several MB of data per session, and the hardest privacy questions.

• Mask by default. Replace all text with placeholders and block images, video, and inputs unless an element is explicitly unmasked. Sentry's replay masks all text and blocks media by default; follow that.
• Record only some sessions. For example 1% of sessions in full, plus a rolling buffer of the last 60 seconds in memory for every session that's flushed only if an error happens. That second mode gives replays for most errors at a fraction of the cost.
• Respect consent. Replay is closer to analytics than to error monitoring. Gate it on consent where the law requires.

Architecture, data model, and the dashboard it feeds

With the decisions made, the SDK falls into a few modules with narrow jobs. The boundaries follow the pipeline: things that observe the page, one place that holds context, one processor that turns raw failures into safe events, and the shared transport.

One transport rule is specific to errors. A fatal event (the app's root boundary fell back, or an uncaught error during startup) skips batching and is sent at once with fetch and keepalive: true, because the user is likely about to reload or leave. Everything else rides the normal batch.

Keepalive has a hard limit: all of a page's in-flight keepalive requests share 64 KiB of body, and Chromium counts sendBeacon against the same quota. So the fatal event goes without replay data and with trimmed breadcrumbs. The analytics SDK guide covers the rest of page-hide delivery: visibilitychange, sendBeacon versus keepalive, and the offline queue.

The data flow continues past the browser: the collector validates the envelope and answers fast. Ingestion workers then symbolicate with the uploaded maps, scrub again, compute the server fingerprint, and upsert the issue. Only then do alert rules run. The client's whole contribution is a clean, structured, scrubbed event; everything that needs global knowledge happens on the server.

Data model and public interface

The event is the contract between SDK and backend, so it's versioned and kept flat enough to index. Everything lives in memory on the client except the small outbound queue, which the shared transport persists in IndexedDB as the analytics guide describes.

type StackFrame = { function?: string; filename: string; lineno: number; colno: number; in_app: boolean };

type ErrorPayload = {
  event_id: string;               // uuid, lets the server drop duplicates on retry
  ts: number;
  level: "fatal" | "error" | "warning";
  exception: { type: string; value: string; frames: StackFrame[]; synthetic?: boolean };
  mechanism: "onerror" | "unhandledrejection" | "react" | "fetch" | "console" | "manual";
  fingerprint?: string[];         // app override
  release: string; env: string; debug_ids?: Record<string, string>;
  user?: { id: string };          // opaque or hashed
  session_id: string; trace_id?: string; route: string;
  tags: Record<string, string>;   // flags, plan, locale
  breadcrumbs: { ts: number; category: string; message: string }[];
  repeat?: number; sample_rate: number; sdk: { name: string; version: string };
};

ErrorSdk.init({
  dsn: "https://ingest.example.com/p/42",
  release: __RELEASE__, environment: "production",
  sampleRates: { error: 1, warn: 0.1, info: 0.01, replay: 0.01, replayOnError: 1 },
  tracePropagationTargets: [/^https:\/\/api\.shop\.com/],
  allowUrls: [/cdn\.shop\.com/], ignoreErrors: [/^ResizeObserver loop/],
  beforeSend: (event) => event,       // return null to drop
});
ErrorSdk.setUser({ id: hashedUserId });
ErrorSdk.setTag("plan", "pro");
ErrorSdk.addBreadcrumb({ category: "cart", message: "synced" });
ErrorSdk.captureException(err, { fingerprint: ["payment-timeout"] });
ErrorSdk.log.warn("payment retry", { provider: "stripe", attempt: 2 });

The collector endpoint is POST /api/{project}/envelope with a newline-separated body: one envelope header line, then for each item (event, logs, replay chunk) an item header line and a payload line. It answers 200 with accepted ids, 413 when an item is too large (the SDK then drops the replay and breadcrumbs and retries once), and 429 with Retry-After. A public, write-only project key in the DSN identifies the project; it can't read anything, so it's safe to ship in the bundle.

The dashboard the client feeds

The SDK is judged by the screen an engineer opens at 2 a.m. Working backwards from that screen explains every field we send.

• Issue list: one row per fingerprint, sorted by users affected, with a sparkline of the last 24 hours. Needs the fingerprint inputs, user.id, and sample_rate to scale counts.
• Regressions by release: "first seen in 4.12" and "resolved in 4.11, back in 4.12". Needs release on every event, and a release record created at deploy time.
• Alerts: a new issue, a spike over the baseline (for example 10 times the hourly average), or crash-free sessions dropping under 99.5% after a deploy. Needs session start events too, not only errors, so the SDK sends a tiny session ping per session.
• Issue detail: symbolicated stack with source lines, breadcrumbs, tags broken down by browser, route, and flag, a link to the backend trace, and replay when present.

Crash-free sessions is the metric teams actually gate releases on, and it's the one field naive SDKs forget: without a count of healthy sessions, you know how many errors there were but not what share of users had a bad time.

Running it in the interview

In 45 minutes you can't cover every chapter. Spend about 5 minutes on scope (own app or product, errors or logs too, replay or not), 5 on what makes it hard, then draw the architecture with the event pipeline and walk one error through it in 5. Use the next 25 minutes on two or three deep dives the interviewer cares about: usually capture, grouping with source maps, and noise or privacy. Leave 5 for follow-ups.

1. Draw the browser with its failure doors on the left, the pipeline in the middle, the collector and ingestion on the right.
2. Say out loud which hook catches what, and name the three gaps: resource errors need the capture phase, boundaries miss handlers and async code, 5xx never throws.
3. Name Script error. and its fix before you're asked.
4. Explain grouping by symbolicated in-app frames, and why source maps are uploaded privately.
5. Close with safety: never throw, no feedback loops, small core, lazy replay.

Keep linking back to the transport you'd share with an analytics SDK instead of re-deriving batching and sendBeacon. Saying "same transport, different rules for priority and sampling" saves five minutes for the parts that are unique to errors.