@maple-dev/browser 0.9.0 → 0.10.1

package/README.md

@@ -66,14 +66,27 @@ 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
+
+`fetch`/XHR responses with a 4xx or 5xx status are errors, typed by status, as the HTTP semantic
+conventions say for client spans. Narrow that with `errors: { captureHttpStatus: [[500, 599]] }`.
+A network failure is always an error.
+
+### 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
 
 Bundled, minified and gzipped, as your bundler would ship it:
 
 |                  | gzipped | what it is                                                |
 | ---------------- | ------- | --------------------------------------------------------- |
-| **eager**        | ~36 kB  | every page load, before any sampling decision             |
-| ↳ our code alone | ~13 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
@@ -118,6 +131,33 @@ 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
@@ -127,7 +167,7 @@ explicit `endpoint` (a proxy, or self-hosted ingest) always wins over `region`.
 
 ## Tracing across origins
 
-`fetch` spans carry the W3C `traceparent` header to same-origin requests only.
+`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:
 
@@ -138,6 +178,49 @@ MapleBrowser.init({
 })
 ```
 
+## 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

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 };