Initialization

⚠️

Not available yet. The TracePath browser SDK is not published, so nothing on this page can be installed or run today. It documents the planned configuration surface. To send telemetry to TracePath now, use OpenTelemetry over OTLP/HTTP.

The browser SDK will be initialized once at application startup, before any event is captured, with a connection string identifying your project and the TracePath ingest endpoint. Initialization installs the global handlers, so nothing else has to be wired up for uncaught errors to be reported.

Options Reference

Option	Type	Default	Description
`debug`	`boolean`	`false`	Log dropped events and failed uploads to the browser console. Captured events are not logged
`debounceMs`	`number`	`1500`	Milliseconds to wait before sending batched events
`retryDelayMs`	`number`	`10000`	Milliseconds to wait before retrying failed uploads
`version`	`string`	`undefined`	Your application version (shown in the TracePath dashboard)
`ignoreErrors`	`Array<string \| RegExp>`	see Error Filtering	Patterns that suppress an error before capture
`beforeCapture`	`(exception) => boolean`	`undefined`	Callback to suppress errors programmatically. Return `false` to drop
`sessionRecording`	`boolean`	`true`	Enable the rrweb session recorder. Required for both per-exception clips and always-on recording
`sessionRecordingSegmentDuration`	`number`	`30000`	Length of each rrweb segment in milliseconds. Always-on recording uploads one row per segment, so a longer value means fewer rows at the cost of replay granularity
`attributes`	`Record<string, string>`	`{}`	Initial context for sessions and exceptions, such as `userId`, `email` or `tenant`
`recordAllSessions`	`boolean`	`false`	Always-on session recording: upload every segment continuously and create a parent session row, not just exception-bound clips. See Sessions
`captureLogs`	`boolean`	`true`	Mirror `console.{debug,log,info,warn,error}` into the rolling log buffer that ships with each clip or segment
`captureNetwork`	`boolean`	`true`	Record `fetch` and `XMLHttpRequest` calls as network actions
`captureNavigation`	`boolean`	`true`	Record History API push / replace / pop transitions as navigation actions
`eventsWindowMs`	`number`	`10000` (`30000` with `recordAllSessions`)	Rolling window the log and action buffers retain
`eventsMaxCount`	`number`	`200` (`600` with `recordAllSessions`)	Hard cap on entries kept independently in the log and action buffers
`captureHttpServerErrors`	`boolean`	`false`	Report every `fetch` response with status >= 500 as a synthetic exception. 4xx is never included, and it is wired into the `fetch` wrapper only, so `XMLHttpRequest` (including `$.ajax()` and browser Axios) does not trigger it

Auto-Capture Behavior

Initializing the SDK installs the global handlers for you. Uncaught errors (window.onerror) and unhandled promise rejections (window.onunhandledrejection) are captured automatically in every JS package: core, React, Vue, Svelte and jQuery alike.

Do not add your own window.addEventListener("error") or "unhandledrejection" listener that also reports to TracePath. The SDK's handlers are already attached, so every error would be reported twice and show up with double the count in the Issues feed.

The framework packages add render-time capture on top of this: the React provider doubles as an error boundary, and the Vue plugin installs app.config.errorHandler. Explicit capture calls are only needed where an error never becomes uncaught, such as inside a try/catch or an event handler that swallows it.

Error Filtering

By default the SDK ignores common non-actionable errors: 4xx HTTP errors, network errors and timeouts. These are usually expected application behaviour (form validation returning 422, an auth redirect from 401) rather than bugs worth tracking.

Default patterns

The following are ignored out of the box:

"Failed to fetch" (Chrome), "Load failed" (Safari), "NetworkError when attempting to fetch resource" (Firefox), "Network Error" (Axios), "Network request failed" (React Native style)
"The operation was aborted" (AbortController), any message matching /timeout/i
Axios-style 4xx errors matching /status code 4\d{2}/
jQuery and custom 4xx errors matching /failed: 4\d{2}/

Setting ignoreErrors to an empty array opts out of all of it and captures everything. Setting it to your own array replaces the defaults rather than extending them; the SDK exports the default list so you can spread it into your own and keep both. Strings match via includes(), regular expressions via .test().

beforeCapture

beforeCapture receives the full exception object, including its attributes, and returns false to suppress it. It runs after ignoreErrors: if a pattern already suppressed the error, the callback is not called. If the callback itself throws, the error is captured normally, which is the safe default.

Debug Mode

With debug: true the SDK logs what it throws away: errors suppressed by ignoreErrors, a beforeCapture callback that threw, and failed uploads. Captured events produce no console output at all, so an empty console does not mean the SDK is broken. To confirm an event was captured, watch for the ingest request in the Network tab, or force a flush and open the Issues page.

Custom Attributes

The SDK auto-collects browser context (url, userAgent, viewport and similar) on every session and exception. App-level identifiers — userId, tenant, feature flags — are set through an imperative scope API and then ride along every subsequent event, with a matching call to clear them on logout or a tenant switch.

Layering on each event is defaults < global scope < per-call: an attribute passed with a specific exception wins over a global one of the same name.

With recordAllSessions: true, changing a global attribute mid-session also refreshes the live session row immediately rather than waiting for the session to close. See Sessions for the full attribute model.

Multiple Environments

Use a separate TracePath project, and therefore a separate project token, per environment. Selecting the connection string from an environment variable at build time keeps staging errors out of your production Issues feed.

Overview Exceptions