@maple-dev/browser 0.8.0 → 0.10.0

package/README.md

@@ -19,6 +19,7 @@ import { MapleBrowser } from "@maple-dev/browser"
 MapleBrowser.init({
 	ingestKey: "maple_pk_...", // public ingest key
 	serviceName: "acme-web",
+	region: "eu", // "us" (default) or "eu"; must match your organization's region
 	environment: "production",
 	replay: { enabled: true, sampleRate: 1.0 },
 	privacy: { maskAllInputs: true },
@@ -35,7 +36,46 @@ That single call:
   only once a session is sampled in, so a `sampleRate` below 1 costs the
   unsampled visitors nothing beyond the base SDK (see [Bundle size](#bundle-size));
 - writes session metadata at start (`active`) and on page hide (`ended`),
-  including the trace ids observed during the session.
+  including the trace ids observed during the session;
+- captures uncaught errors and unhandled promise rejections as error spans, so
+  browser crashes reach Maple's error tracking.
+
+## Errors
+
+Every uncaught error and unhandled rejection becomes a span with status `Error`
+and an `exception` event, which is the shape Maple fingerprints — so browser
+crashes group beside your server-side errors instead of in a silo.
+
+Errors your app _catches_ never reach the global handlers, because catching them
+is what stops them. Report those explicitly:
+
+```ts
+try {
+	render()
+} catch (error) {
+	MapleBrowser.captureException(error, { name: "browser.render_error" })
+}
+```
+
+Opt out of the global handlers with `tracing: { captureErrors: false }` — worth
+doing only when another tracker already owns them, or the same crash is recorded
+twice.
+
+A cross-origin script reports to the browser as a bare `"Script error."` with no
+stack and no filename. Those are dropped rather than recorded: they all
+fingerprint to one contentless issue that buries the real ones. Add
+`crossorigin` to the script tag to get the real error instead.
+
+### Failed HTTP requests
+
+`errors: { captureHttpStatus: [[500, 599]] }` makes those `fetch`/XHR responses errors, typed by
+status. By default a response status alone is not an error; a network failure always is.
+
+### Breadcrumbs
+
+The last 50 clicks, inputs, navigations and console lines are kept in memory and exported, as OTel
+log records linked to the error's span, only when an error is recorded. `breadcrumbs: false` turns
+this off; `logs: { captureConsole: ["warn", "error"] }` sends those console levels as logs right away.
 
 ## Bundle size
 
@@ -43,8 +83,9 @@ Bundled, minified and gzipped, as your bundler would ship it:
 
 |                  | gzipped | what it is                                                |
 | ---------------- | ------- | --------------------------------------------------------- |
-| **eager**        | ~32 kB  | every page load, before any sampling decision             |
-| ↳ our code alone | ~3.5 kB | the marginal cost if your app already ships OpenTelemetry |
+| **eager**        | ~40 kB  | every page load, before any sampling decision             |
+| ↳ our code alone | ~16 kB  | the marginal cost if your app already ships OpenTelemetry |
+| **deferred**     | ~9 kB   | logs SDK, Web Vitals, document timing, after `init()`     |
 | **lazy**         | ~61 kB  | rrweb — downloaded only by sessions sampled into replay   |
 
 The eager figure is ~90% OpenTelemetry. If your app already uses the OTel web
@@ -89,6 +130,96 @@ a separate analytics silo. Calls before `init()` finishes are queued.
 MapleBrowser.track("checkout_completed", { plan: "pro", seats: 12 })
 ```
 
+## Logs
+
+`MapleBrowser.logger` writes OpenTelemetry log records, linked to the active span and the session.
+Calls before `init()` are queued.
+
+```ts
+MapleBrowser.logger.info("checkout started", { "cart.items": 3 })
+```
+
+## Web Vitals
+
+LCP, CLS, INP, FCP and TTFB are reported as `browser.web_vital` OpenTelemetry log events
+(browser semantic conventions), linked to the `pageload` span and the session. Opt out with
+`webVitals: false`.
+
+## Replay on error
+
+`replay: { sampleRate: 0.05, onErrorSampleRate: 1 }` records 5% of sessions, and has every other
+session keep the last minute in memory, uploading it and recording the rest of the session only if
+an error is recorded.
+
+## Trace sampling
+
+`tracing: { sampleRate: 0.25 }` exports the traces of ~25% of sessions. The decision is per
+session, so a sampled session keeps all of its traces. Reported errors (uncaught errors, unhandled
+rejections, `captureException`) are always exported.
+
+## Regions
+
+Maple runs separate US and EU instances, and an ingest key only works in the
+region it was created in. Set `region: "eu"` for an organization on
+`app.eu.maple.dev`; the SDK then sends to `https://ingest.eu.maple.dev`. An
+explicit `endpoint` (a proxy, or self-hosted ingest) always wins over `region`.
+
+## Tracing across origins
+
+`fetch` and XHR spans carry the W3C `traceparent` header to same-origin requests only.
+When your API lives on another origin, list it so browser and backend spans
+join one trace, and allow the `traceparent` header in the API's CORS policy:
+
+```ts
+MapleBrowser.init({
+	// ...
+	tracing: { propagateTraceHeaderCorsUrls: [/^https:\/\/api\.example\.com\//] },
+})
+```
+
+## Navigations and data loading
+
+Call these from your router's hooks to make one click one trace: a navigation
+span, the data-loading spans under it, and the `fetch` spans they start.
+[maple.dev/docs/frontend](https://maple.dev/docs/frontend) shows where for each
+framework.
+
+```ts
+MapleBrowser.startNavigation(location.pathname) // a navigation starts
+const data = await MapleBrowser.traced("loader /projects/:id", () => load(id), {
+	isFailure: (error) => !isRedirect(error), // redirects aren't failures
+})
+MapleBrowser.endNavigation("/projects/:id") // the route is ready: its template
+```
+
+- The first `startNavigation` opens a `pageload` span, joined to the server
+  render's trace from a `Server-Timing: traceparent;desc="…"` entry or a
+  `<meta name="traceparent">` tag; later calls open `navigate` spans, and end
+  one still open as `app.navigation.interrupted`.
+- The document's `pageload` starts at navigation start, and gets child spans
+  from the Navigation Timing entry once the page has loaded: `documentFetch`
+  (with `dns`, `connect`, `request` and `response` under it), `domProcessing`
+  and `loadEvent`.
+- `traced` returns `fn`'s result and rethrows its error unchanged. Only requests
+  started before `fn`'s first `await` nest under its span. An error it recorded
+  isn't reported again by `captureException` or the global handlers.
+- All three are no-ops on the server, before `init()`, with tracing disabled or
+  without consent (`traced` then only runs `fn`).
+
+## React
+
+`@maple-dev/browser/react` has `MapleErrorBoundary`, `mapleReactErrorHandler()` for React 19's
+`createRoot` error options, and router adapters that call `startNavigation`/`endNavigation` for you:
+
+```ts
+import { instrumentReactRouter, instrumentTanStackRouter } from "@maple-dev/browser/react"
+
+instrumentReactRouter(createBrowserRouter(routes)) // navigate /projects/:id
+instrumentTanStackRouter(router) // navigate /projects/$projectId
+```
+
+Attach them after `MapleBrowser.init`: a navigation reported earlier uses up the page load.
+
 ## Linking a marketing site to your app
 
 The visitor id lives in localStorage **and** a cookie scoped to your registered
@@ -103,6 +234,18 @@ stay per-origin; `VisitorId` is the join key. Override the scope with
 attribute hooks (`data-rr-block`, `.rr-block`, `.rr-ignore`) to block elements
 or subtrees from capture.
 
+URLs are redacted before they leave the page: the values of credential-shaped
+query and fragment parameters (`token`, `code`, `access_token`, `password`, …)
+become `REDACTED` in session rows, events, network events, replay meta events
+and span attributes. Add your own rewriting with `privacy.sanitizeUrl`, for
+example to collapse ids in paths:
+
+```ts
+privacy: {
+	sanitizeUrl: (url) => url.replace(/\/users\/\d+/, "/users/:id")
+}
+```
+
 `privacy.requireConsent` holds all capture until `MapleBrowser.setConsent(true)`.
 Global Privacy Control is honored by default and suppresses the persistent
 visitor id; `doNotTrack` is not, unless `privacy.respectDoNotTrack` is set.

package/dist/console-BrjBnOiX.mjs

@@ -0,0 +1,73 @@
+import { O as safeEmit } from "./sink-BOR9_z4b.mjs";
+//#region ../browser-session/src/replay/capture/console.ts
+const LEVELS = [
+	"log",
+	"info",
+	"warn",
+	"error",
+	"debug"
+];
+const MAX_MESSAGE = 2e3;
+/** No array logged into a 2,000-character message needs more elements than this. */
+const MAX_ARRAY_ELEMENTS = 100;
+/**
+* Capture `console.*` calls as session events. Wraps each method, emits a
+* distilled record, then forwards to the original so the host app's console
+* behaves normally. Never throws into the call site.
+*/
+function installConsoleCapture(emit) {
+	const original = {};
+	const wrappers = {};
+	let active = true;
+	for (const level of LEVELS) {
+		const orig = console[level];
+		original[level] = orig;
+		const wrapper = (...args) => {
+			if (active) safeEmit(emit, {
+				type: "console",
+				level,
+				message: formatArgs(args)
+			});
+			orig.apply(console, args);
+		};
+		wrappers[level] = wrapper;
+		console[level] = wrapper;
+	}
+	return () => {
+		active = false;
+		for (const level of LEVELS) {
+			const orig = original[level];
+			if (orig && console[level] === wrappers[level]) console[level] = orig;
+		}
+	};
+}
+function formatArgs(args) {
+	const text = args.map((a) => {
+		if (typeof a === "string") return a;
+		if (a instanceof Error) return `${a.name}: ${a.message}`;
+		try {
+			return boundedStringify(a, MAX_MESSAGE) ?? String(a);
+		} catch {
+			return String(a);
+		}
+	}).join(" ");
+	return text.length > MAX_MESSAGE ? `${text.slice(0, MAX_MESSAGE)}…` : text;
+}
+/**
+* `JSON.stringify` that stops descending once roughly `budget` characters have
+* been produced. The message is cut to `MAX_MESSAGE` anyway, and serializing a
+* whole store object on every `console.log` first was a main-thread cost paid
+* on the host app's hot path. A replacer returning `undefined` skips a value
+* without visiting its children, so the walk is bounded by the budget.
+*/
+function boundedStringify(value, budget) {
+	let used = 0;
+	return JSON.stringify(value, (key, nested) => {
+		if (used > budget) return void 0;
+		used += key.length + (typeof nested === "string" ? nested.length : 4);
+		if (Array.isArray(nested) && nested.length > MAX_ARRAY_ELEMENTS) return nested.slice(0, MAX_ARRAY_ELEMENTS);
+		return nested;
+	});
+}
+//#endregion
+export { installConsoleCapture as t };