@bucker/browser
Browser capture. Named exports only, integrations importable from their own entry points, no side effects at import time — the package is tree-shakable by construction and a test enforces its byte budget in CI.
Distribution note. The package is build-ready, not yet published. It carries a
publishConfig(pointing atdist/, split per subpath) alongside a source-pointing top-levelmain/types/exports— the split matters because several other workspace packages import the SDKs by source with no build step, while a published consumer cannot compile./srcand needs the compileddist/.pnpm build/prepackrunscripts/build-package.mjs, which refuses to finish if the built output does not match whatpublishConfig.exportspromises. Inside the monorepo it resolves throughworkspace:*;create-buckeralready emits the install command for the published name. What remains is an actualnpm publish, a human decision covered insdks/PUBLISHING.md— not code readiness.
Init
import { init } from '@bucker/browser'
init({
dsn: import.meta.env.VITE_BUCKER_DSN,
environment: import.meta.env.MODE,
release: __APP_VERSION__,
})
Call it once, as early as your entry allows. init() returns the Client and also
installs it as the current client, so the module-level helpers work anywhere after.
Options
Everything on ClientOptions, plus the browser-specific ones:
| Option | Default | Meaning |
|---|---|---|
dsn |
— | Required. A DSN still holding the documentation placeholder (<publicKey>, PUBLIC_KEY, …) disables the SDK with a warning rather than sending to a project that does not exist |
release |
— | Stamped on every event, and required for release health: without it no session is sent (the server discards release-less sessions), and the SDK says so once in the console |
environment, dist, serverName, platform |
— | Stamped on every event |
sampleRate |
1 |
Applied per event before the envelope is built; drops are accounted for in the client report |
maxBreadcrumbs |
SDK default | Ring-buffer size |
maxValueLength |
SDK default | Caps any single captured string. Bounds sizes, never semantics |
beforeSend |
— | Last chance to mutate or drop an event; a drop is accounted for |
beforeBreadcrumb |
— | Same, per breadcrumb |
beforeSendSpan, beforeSendLog |
— | Same, for spans (@bucker/sdk-core/tracing) and structured-log records (/logging); return null to drop. Counted as before_send |
inAppInclude / inAppExclude |
— | Substring matchers forcing frames in or out of in_app; include wins |
integrations |
defaultIntegrations() |
Replaces the default set entirely |
autoUnloadFlush |
true |
Set false to skip the pagehide/visibilitychange beacon flush |
maxBufferBytes |
SDK default | Transport queue ceiling |
tunnel |
— | A same-origin path (/bucker) to send envelopes to instead of the ingest host. See Sending through your own origin |
random, now |
Math.random, Date.now |
Testing seams for deterministic sampling and timestamps |
Default integrations
defaultIntegrations() returns
[globalHandlersIntegration(), breadcrumbsIntegration(), httpContextIntegration()].
globalHandlersIntegration — window.onerror and unhandledrejection. Both are
recorded with handled: false and a distinct mechanism type, because "the app
crashed" and "someone caught this and reported it" group differently and the
distinction cannot be recovered later. An onerror that fires with no Error object
(cross-origin scripts) still produces an event built from filename/line/column — a
location-only crash beats no crash.
breadcrumbsIntegration — console, fetch, XMLHttpRequest, history navigation
and DOM clicks. Every source is a monkey patch and every patch is reversible: the
integration keeps the original and restores it on teardown.
DOM click crumbs carry a micro-DOM chain (microDomChain, exported from
@bucker/browser/microdom) — a compact ancestor description rather than a full
selector dump.
httpContextIntegration — the page the error happened on and the browser that
raised it: request.url is location.href, and request.headers carries
User-Agent and, when there is one, Referer. This is what fills an issue's Request
panel for a browser event. Both URLs are masked the same way breadcrumb URLs are:
userinfo is dropped and every query and fragment value becomes [Filtered],
while the keys stay — /cart?token=abc&page=2 arrives as
/cart?token=[Filtered]&page=[Filtered]. A request already on the event (from
setRequest, a scope, or your own event processor) is left untouched.
Transport
Two send paths share one queue:
- normal —
fetchwithkeepalive; - unloading —
navigator.sendBeacon, the only delivery a browser guarantees after the page is gone.installUnloadFlushflips a flag onpagehide/visibilitychange; the transport reads it rather than swapping implementations, because there is no time to negotiate anything at that point.
sendBeacon caps a payload at 64 KB (BEACON_MAX_BYTES), so splitForBeacon splits
oversized queues rather than losing them.
Both paths send Content-Type: text/plain;charset=UTF-8, not the envelope type, and
authenticate in the query string, so every send is a CORS-simple request with no
preflight. For the beacon that is not an optimisation: the Beacon spec makes every
beacon credentialed, the ingest host answers preflights with Access-Control-Allow-Origin: *
and no credentials (deliberately — there is nothing to protect with cookies there), and a
credentialed request can never pass that preflight. The browser would drop the POST while
sendBeacon still returned true. Ingest reads the body as raw bytes whatever the type
says.
Envelopes ride two priority lanes. Errors take the critical lane and flush first; logs, spans, replay and attachments take bulk. A bulk item never shares an envelope with an error item — one oversized attachment causing a 413 that also kills the error event is a footgun we deliberately do not inherit.
Rate limits (429 + Retry-After / X-Sentry-Rate-Limits) are honoured per category,
and everything dropped is reported back as a client_report with a reason
(ratelimit_backoff, queue_overflow, sample_rate, before_send, …).
Filtering noise before it costs quota
ignoreErrors, denyUrls, allowUrls and thirdPartyFrames drop an event in the SDK,
before sampling and before it is sent. In the browser they live in their own entry point
(the root bundle is at its size budget), so you add the integration:
import { defaultIntegrations, init } from '@bucker/browser'
import { inboundFiltersIntegration } from '@bucker/browser/filters'
init({
dsn,
integrations: [
...defaultIntegrations(),
inboundFiltersIntegration({
ignoreErrors: ['ResizeObserver loop', /^Script error\.?$/],
denyUrls: [/^chrome-extension:\/\//, /extensions\//],
thirdPartyFrames: 'drop', // or 'tag'
}),
],
})
| Option | Meaning |
|---|---|
ignoreErrors |
Drop when the message, an exception value, or Type: value matches. A string is a substring, a RegExp is tested |
denyUrls |
Drop when the top-most frame's file matches |
allowUrls |
Drop when the top-most frame's file matches none of these. An event with no frames is kept |
thirdPartyFrames |
A frame with no registered Debug ID is third-party. 'drop' discards an event whose frames are all third-party; 'tag' keeps it with tags.third_party_code. Does nothing until the bundler plugin has registered a chunk, since nothing can be told apart before that |
Every drop is a client_report with reason event_processor, so the dashboard still shows
how much noise the list sheds. Server SDKs (@bucker/node) take the same four options on
init() directly.
Sending through your own origin (tunnel)
Ad blockers match ingest hostnames. A blocked ingest is invisible by construction: nothing
arrives, so nothing is counted, and the outcome vocabulary cannot show it. tunnel sends the
browser's envelopes to a path on your origin and lets your server forward them:
init({ dsn: process.env.NEXT_PUBLIC_BUCKER_DSN, tunnel: '/bucker' })
// app/bucker/route.ts (Next.js App Router)
import { tunnelRoute } from '@bucker/node/nextjs'
export const POST = tunnelRoute({ dsns: [process.env.NEXT_PUBLIC_BUCKER_DSN] })
The envelope still carries the DSN in its header, so the SDK adds no auth query string. The route
reads only the project id from that header and forwards to the DSN you listed with its
host and key: a request naming any other project gets a 403, and the route cannot be aimed at
another host. Bodies are capped at the protocol's envelope ceiling, redirects are refused, and the
upstream body is never relayed (only the status and Retry-After / X-Sentry-Rate-Limits, so the
SDK's backoff still works). @bucker/node/tunnel exports the same handler for any Request ->
Response runtime (Hono, Workers, Deno, Bun).
What it costs, honestly:
- Every browser event becomes a request to your host (a serverless invocation on Vercel), and
you pay for it. Pair it with
sampleRate,ignoreErrorsand the unload-time beacon limits. - The ingest sees your server's address as the client, not the visitor's.
- A path called
/buckeris as blockable as a hostname if everyone uses it. Pick your own.
Script-tag delivery (no bundler)
For WordPress, static HTML and CMS templates that cannot npm install. There is deliberately
no server-configured loader: a lazy "error-only" stub loses the breadcrumbs and early
fetches that happen before the real SDK arrives. The files below are the whole SDK, loaded
eagerly from a CDN you pin to a version.
The classic script (recommended; it is the one that takes SRI):
<script
src="https://cdn.jsdelivr.net/npm/@bucker/browser@0.1.0/dist/0.1.0/bucker.min.js"
integrity="sha384-…"
crossorigin="anonymous"
data-dsn="https://<publicKey>@us.ingest.bucker.io/<projectId>"
data-release="site@2026.10.17"
data-environment="production"
></script>
data-dsn initialises the SDK as the tag runs (also data-release, data-environment,
data-tunnel). Without it nothing runs, and you call Bucker.init({ dsn }) yourself; the whole
SDK is the global Bucker, including Bucker.inboundFiltersIntegration for deny lists.
Get the integrity value for the version you pin from the build (pnpm --filter @bucker/browser build prints it and writes dist/<version>/bucker.min.js.integrity), or compute it from the file you are
about to reference:
curl -s https://cdn.jsdelivr.net/npm/@bucker/browser@0.1.0/dist/0.1.0/bucker.min.js \
| openssl dgst -sha384 -binary | openssl base64 -A
Pin an exact version, never @latest or a range: SRI on a moving file breaks the day it
moves, and an unpinned third-party script on every page is a supply-chain hole you chose.
There is no unversioned path to pin by accident. The build publishes the script only as
dist/<version>/bucker.min.js, beside bucker.min.js.integrity (its SHA-384 value) and the
source map, with the version copied from the package's package.json; an unversioned bucker.min.js directly under dist
does not exist. The SDK itself never fetches code at run time: no import() of a URL and no
<script> element created from code appears in any entry point or in the script-tag build
(test/no-mutable-path.test.ts), so every feature is code you imported and your SRI hash covers.
The ES module (no SRI):
<script type="module">
import { init } from 'https://cdn.jsdelivr.net/npm/@bucker/browser@0.1.0/+esm'
init({ dsn: 'https://<publicKey>@us.ingest.bucker.io/<projectId>' })
</script>
An inline module script cannot carry integrity, and jsDelivr's +esm is generated on request and
bundles the protocol's schema library, so it is several times larger than the classic script. Use
it when you already author modules; use the classic script otherwise.
The classic script is about 42 KB minified (about 15.7 KB gzipped) and has its own budget in
test/iife.test.ts; every opt-in entry point has a gzip budget as well as a minified one
(test/size.test.ts). It stubs the schema library the server uses for validation (the SDK only
serialises), which is why it is a fraction of the size of the ES module.
User feedback
import { captureException } from '@bucker/browser'
import { captureFeedback } from '@bucker/browser/feedback'
const eventId = captureException(error)
captureFeedback({ message, email, associatedEventId: eventId })
@bucker/browser/feedback is its own entry point (the root bundle is at its budget). It sends a
Sentry-shaped feedback item that the server stores and links to the issue. The embeddable widget
and the post-error report dialog are @bucker/browser/feedback-widget, a separately budgeted entry;
see User feedback. The widget's optional screenshot (allowScreenshot, a file the user picks, never an automatic capture) is stored only on a project that opted in to screenshots. @bucker/browser/attachments exposes addAttachment; the
files ride their own bulk envelope and show on the event's Attachments panel. See
@bucker/node.
Feature flags
Records which flags an error saw, so an issue can answer "which flag broke this". The server reads
contexts.flags from every event and rolls it up per issue; this is the producer. Flag SDKs
(LaunchDarkly, Statsig, Unleash, Flagsmith…) come through their OpenFeature providers, so one hook
covers them and this package depends on none of them:
import { OpenFeature } from '@openfeature/server-sdk' // or @openfeature/web-sdk
import { openFeatureHook } from '@bucker/browser/flags'
OpenFeature.addHooks(openFeatureHook())
Evaluations are recorded on the current scope, so on a server a request's flags land on that request's errors only. A flag evaluated again keeps its latest record; at most 50 are kept (the server's own ceiling), stalest first out.
Hook contract v2. The hook's finally stage (OpenFeature 0.9 passes it the full evaluation
details, for a failed evaluation too) records { flag, variant, reason, version, provider, valueDigest, evaluatedAt, requestId?, definitionsLoadedAt? }, so "variant B of checkout at
version 7 raised this error" is a join on stored keys. The value is customer data: it is kept
(as result) only for booleans and strings of 40 characters or fewer, and anything else, an object,
a number or a longer string, is reduced to its SHA-256 valueDigest. A failed evaluation is
recorded with reason ERROR and its error code, and suspect ranking ignores it: the caller got the
default, not a decision the flag system made. version is read from the provider's
flagMetadata.version. With an OpenTelemetry span active, the hook also adds the semantic-convention
feature_flag.evaluation event to it (feature_flag.key, feature_flag.result.variant,
feature_flag.result.reason, feature_flag.provider.name, feature_flag.version), which is how a
trace shows which variants a request saw: the server folds the events into one bucker.flags
attribute on the trace's local root span, and spans from a non-Bucker OpenTelemetry SDK that carry
feature_flag.* attributes or events are read the same way. Without OpenFeature, call
recordFlagEvaluation(flag, result) yourself (the v1 shape, no variant). The Python and Dart hooks
are not part of this release.
Tracking consent
setTrackingConsent('granted' | 'pending' | 'revoked') gates everything the SDK sends (errors,
sessions, spans, logs, replay, client reports), because it sits on the transport, not on capture:
import { init } from '@bucker/browser'
import { setTrackingConsent, trackingConsentIntegration } from '@bucker/browser/consent'
init({ dsn, integrations: [...defaultIntegrations(), trackingConsentIntegration({ initial: 'pending' })] })
// later, from your consent banner:
setTrackingConsent('granted') // or 'revoked'
pending: nothing leaves the page. Requests wait in a bounded buffer (50 by default); past it the oldest is evicted and counted asqueue_overflow.granted: the buffer is sent, in order, and sends flow.revoked: the buffer is discarded, nothing is sent, and the release-health session is ended (a later grant starts a new one). This is deliberately not reported in the client report: a report is itself telemetry, and withdrawn consent asks for silence.
To gate the very first events, install the integration at init as above. Calling
setTrackingConsent without it installs the gate from that moment on. Requests already handed to the
network when consent is revoked cannot be recalled.
Offline queue
A tab that goes offline loses its in-memory buffer when it closes, including the errors that explain
why it was offline. @bucker/browser/offline keeps unsent envelopes in IndexedDB and replays them,
oldest first, when the network returns or the app next starts:
import { offlineQueue } from '@bucker/browser/offline'
const offline = offlineQueue({ maxEntries: 30, maxAgeMs: 24 * 60 * 60 * 1000 })
init({
dsn,
fetchImpl: offline.fetch,
integrations: [...defaultIntegrations(), offline.integration],
})
It wraps fetch rather than the core transport so a failure becomes "queued durably" before it
is counted as a network_error drop (otherwise one envelope would be reported lost and delivered).
Anything the queue gives up on, because of the size cap or maxAgeMs, is counted as
cache_overflow in the client report, per category. A 429 or 5xx on replay keeps the entry; any
other 4xx removes it (the server will never accept that payload).
Limits, stated: the unload-time sendBeacon path does not go through fetch, so an envelope beaconed
while offline as the page closes is not queued; and where IndexedDB is unavailable (some private
windows) it falls back to memory, with one console warning, which is not durable.
Automatic spans (@bucker/browser/tracing)
import { defaultIntegrations, init } from '@bucker/browser'
import { browserTracingIntegration } from '@bucker/browser/tracing'
init({
dsn,
tracesSampleRate: 0.1,
integrations: [...defaultIntegrations(), browserTracingIntegration()],
})
Opt-in, in its own entry point with its own size budget (about 10 KiB minified on its own, because
it carries the tracer the default bundle does not), so a page that does not trace pays nothing.
With no tracesSampleRate or tracesSampler it patches nothing.
| Span | When | Notes |
|---|---|---|
pageload <path> |
navigation start to the load event, plus an idle window |
Navigation Timing as attributes (http.ttfb_ms, dom.content_loaded_ms, load_ms) |
navigation <path> |
pushState, replaceState, popstate to a new URL |
A new trace; ends the previous page span |
fetch <METHOD> <path>, xhr <METHOD> <path> |
each request | Child of the current page span; carries the status code |
Names and attributes carry the path only: query strings and fragments are dropped. A traceparent
header is added to same-origin requests only; list cross-origin hosts in tracePropagationTargets
(strings match as substrings, RegExps are tested), because a header on a cross-origin request
triggers a CORS preflight and tells a third party your trace ids. Options: pageload,
navigation, fetch, xhr (each default on), idleTimeoutMs (default 1000). teardown()
restores every patched global.
Capturing by hand
import { captureException, captureMessage, addBreadcrumb, setUser, setTag,
setContext, setExtra, flush, close } from '@bucker/browser'
captureException(error, { mechanism: { type: 'checkout', handled: true } })
captureMessage('cart reconciliation skipped', 'warning')
addBreadcrumb({ category: 'checkout', message: 'coupon applied', level: 'info' })
setUser({ id: 'u_123' }) // pass null to clear
setTag('tier', 'pro')
await flush(2000) // true when the queues drained in time
Scope is exported for advanced use; getCurrentScope() returns the active one.
Session replay
Bucker replay records what the user did, not what the screen showed: navigations, clicks, inputs (masked by default), requests, console errors, scrolls and vitals. It never captures the screen, the DOM or text nodes, and that is by design — there is no video for a misconfiguration to leak, so the privacy answer to your DPO is "Bucker cannot capture your users' screens". What you get instead is the replay list (find sessions by user, URL, browser, release, errors, rage and dead clicks), a scrubbable player linked to traces, logs and backend errors, a shareable link at a timestamp with the network waterfall, and a transcript your coding agent can run as a repro script. The full capture inventory is in Session replay privacy.
Its own entry point, @bucker/browser/replay, so an application that never calls
replayIntegration() does not pay for it — the root bundle stays under the
CI-enforced byte budget:
import { init, defaultIntegrations } from '@bucker/browser'
import { replayIntegration } from '@bucker/browser/replay'
init({
dsn,
integrations: [...defaultIntegrations(), replayIntegration()],
})
By default it is error-triggered, not always-on: a ring buffer holds the last 30 seconds /
200 events of interaction (windowMs, maxEvents) and nothing leaves the page
until an error is captured, at which point the slice is sent on its own bulk-lane
envelope so a 413 on the replay bytes can never take the error event down with it.
Segments are rate-limited to one per minSegmentIntervalMs (default 5000) however
many errors fire in that window, and sampleRate (default 1) thins which errors
get a segment at all.
| Option | Default | Meaning |
|---|---|---|
maskAllText |
true |
Mask all page text and input values. false still never captures credential-shaped fields |
maxTextLength |
48 | Cap on captured input values and click labels before they are clipped. At most 255: a larger value is clamped, because the server bounds these fields at 256 characters and rejects the whole segment over it (a clipped value gains one …) |
sampleRate |
1 |
Share of errors that get a replay segment |
mask / unmask / block / ignore |
[] |
Selector-level privacy, below |
maskFn |
none | Last transformation over values leaving unmasked |
remoteConfig |
true |
Read the project's stricter-only replay settings at init |
sessionSampleRate |
0 |
Share of sessions recorded whole, error or no error (below) |
sessionIdleTimeoutMs / sessionMaxDurationMs |
15 min / 60 min | When a recorded session ends |
sessionFlushIntervalMs |
10000 | How often a recorded session uploads |
networkDetailAllowUrls |
[] |
URLs whose headers and bodies are captured (below) |
networkRequestHeaders / networkResponseHeaders |
[] |
Header names captured for those URLs |
networkCaptureBodies |
true |
Bodies of allowlisted requests |
consoleLevels |
['error', 'warn'] |
Console methods recorded |
deadClicks / deadClickTimeoutMs |
true / 7000 |
Mark clicks that change nothing |
vitals |
true |
LCP, FCP, TTFB, CLS and INP marks |
minSegmentIntervalMs |
5000 | Minimum gap between uploaded segments |
windowMs / maxEvents |
30s / 200 | Ring buffer bounds — how far back and how much |
console / fetch / xhr / history / dom |
true |
Per-source capture toggles |
rageClickThreshold / rageClickWindowMs |
3 / 1000 | Rage-click detection |
maxOverheadRatio |
0.02 | Recorder disables itself past this share of wall time |
Masking beyond maskAllText cannot be turned off: type="password",
autocomplete credential tokens, and name/id/aria-label patterns matching
password/token/cvv/ssn/… shapes are always redacted. The explicit opt-out is the
data-bucker-mask attribute (also data-private, data-sentry-mask), which hides
a whole subtree, not just the element carrying it. See
replay-privacy.md for the full capture-to-storage pipeline,
including what reaches the server and where server-side scrubbing happens.
Web vitals
@bucker/browser/web-vitals measures the Core Web Vitals of each page view from the
user's own browser:
import { init } from '@bucker/browser'
import { webVitals } from '@bucker/browser/web-vitals'
init({ dsn, tracesSampleRate: 0.2 })
webVitals()
When the page is first hidden (the user switches tab, navigates away or closes it), it
sends one span named pageload <page>, starting at the navigation, with these attributes:
| Attribute | Meaning | Unit |
|---|---|---|
web_vital.lcp |
Largest Contentful Paint | ms |
web_vital.inp |
Interaction to Next Paint: the slowest interaction, ignoring one per 50 | ms |
web_vital.cls |
Cumulative Layout Shift: the largest burst of layout shifts | none |
web_vital.fcp |
First Contentful Paint | ms |
web_vital.ttfb |
Time to First Byte | ms |
browser.page |
the page, with id-like path segments replaced (/orders/:id) |
|
bucker.op |
pageload |
A vital the browser did not report is left out, not sent as 0. Safari reports no LCP or
INP, and a page nobody clicked has no INP. The span is sampled like any other, so set
tracesSampleRate (or tracesSampler); with tracing off nothing is sent. Pass
pageName: () => myRouter.currentRoutePattern to name pages by your router's routes
instead of by path.
With session replay on, pass the replay's id so the player marks LCP, FCP and TTFB on the replay's timeline:
const replay = replayIntegration()
init({ dsn, tracesSampleRate: 0.2, integrations: [...defaultIntegrations(), replay] })
webVitals({ replayId: () => replay.replayId })
The Web vitals dashboard template shows p75 of each vital, overall and per page
(see dashboards.md). The vitals are ordinary span attributes, so Explore
and span alert rules can use them too (for example, p75 of web_vital.lcp where
bucker.op is pageload).
Finding replays
Explore › Replays lists every recorded session in the project, one row per session, with its first page, duration, pages visited, errors, rage clicks, dead clicks, browser and release. The search uses the same grammar as the issue stream:
| Key | Matches |
|---|---|
user: |
The id, email or username your code set on the scope. It is matched by its hash; the identity itself is never stored |
url: |
Any page template the session visited, * as a wildcard (url:/checkout*) |
browser: / release: / environment: |
browser:firefox*, release:web@2.* |
errors: / rage_clicks: / dead_clicks: / failed_requests: |
Counts, with >, >=, <, <= (errors:>0) |
duration: |
Seconds (duration:>60) |
started: |
A date or a relative time (started:-24h) |
is:session / is:error |
Recorded whole, or with an error captured |
has:user / has:issue / has:release |
The field is present |
Free text matches a page, the browser or the release. The query is kept in the URL, so
a filtered list is a link you can paste into a ticket. The player shows chapters, one
per navigation, headed by the page and counted: actions, errors, rage and dead clicks.
They are computed from the recording, with no generated text. Copy link at 0:42
copies a link that opens the same recording at the same moment (?segment= and ?t=
on the page's URL), from the issue's Replay tab or the standalone player. The
Network pane draws every request as a waterfall bar on one scale, failed requests
outlined. Click a row to seek to it, and unfold its headers and body when network detail
was captured. To make user: work, set
the user on the scope (setUser({ id })) before errors happen. A replay that has no user
of its own takes the user of the error it is linked to.
Recording whole sessions
sessionSampleRate (default 0, off) records that share of sessions in full, error
or no error, for UX problems that never throw: a confusing flow, a dead end, a form
people abandon. A sampled session uploads a segment every sessionFlushIntervalMs
(default 10 s), when an error is captured (stamped with its id, so it links to the
issue), and when the tab is hidden for good (pagehide, through the beacon-aware
transport). An unsampled session keeps error-triggered replay exactly as above.
replayIntegration({ sessionSampleRate: 0.05 }) // 5% of sessions, recorded whole
The session lives in a first-party session cookie, bucker_replay, so it continues
across page loads in the same tab and is sampled once rather than on every navigation.
It ends after sessionIdleTimeoutMs (default 15 minutes) without activity, and the next
activity starts a new one. After sessionMaxDurationMs (default 60 minutes) the tab
goes back to error-only replay until the next session. Session segments are billed in
the same replay unit as error segments. The project's Session recording rate
ceiling can lower this rate remotely and never raise it.
Masking by selector
Four selector lists refine maskAllText. Each matches the element and its
ancestors, so a selector on a container covers its whole subtree:
| Option | Effect |
|---|---|
mask |
Text and values inside are masked even with maskAllText: false |
unmask |
Under the default maskAllText: true, values inside are captured in the clear. Credential-shaped fields stay masked whatever this says |
block |
The subtree is opaque: a click or input inside it is recorded against the blocked element, with no label and no child selector |
ignore |
Clicks and input inside are not recorded at all |
replayIntegration({
unmask: ['#search'],
mask: ['.customer-name'],
block: ['#support-chat'],
// Runs on every value about to leave the page UNMASKED, and can only remove from it.
maskFn: (text) => text.replace(/\d(?=\d{4})/g, '*'),
})
An invalid selector matches nothing. A maskFn that throws masks the value.
Network detail, console levels, dead clicks and vitals
By default a request is recorded as method, URL template, status and timing, and nothing else. To capture headers and bodies, name the URLs and the headers:
replayIntegration({
networkDetailAllowUrls: ['/api/checkout', /\/api\/orders\//], // matched against the raw URL
networkRequestHeaders: ['content-type'],
networkResponseHeaders: ['x-request-id'],
networkCaptureBodies: true, // default; false keeps it to headers
})
For an allowlisted URL, headers are captured by name only. authorization, cookie,
set-cookie, x-api-key and other credential headers are dropped even when named. A
JSON body has its credential-shaped keys replaced with <masked>, and every body is cut
at 2048 characters. The response body is read from a clone after your code has the
response, so it never delays your own read. The organization's scrub rules run over all
of it before it is stored. A project that enforces masking switches network detail off,
because a body is page content.
consoleLevels (default ['error', 'warn']) widens console capture to info, log
or debug, still masked like any other console message.
A click followed by no DOM change and no navigation within deadClickTimeoutMs
(default 7000) is marked dead: the button that looks clickable and does nothing.
Clicks into fields are never marked. deadClicks: false turns this off.
LCP, FCP, TTFB, CLS and INP are recorded as numbers at the moment the browser reports
them, and appear as marks on the replay timeline. No element or URL is attached.
vitals: false turns this off.
Replays linked to backend traces
A request that carries a W3C traceparent header is recorded with its trace and span
ids, and so is one whose response carries a traceresponse. Ids only, no other header.
The player's Traces pane then opens that trace's waterfall and its logs, lists the
backend errors on the same trace, and marks them on the scrub bar. Errors from projects
the reader cannot open are left out. The recorder does not add the header itself:
adding a header to your requests changes their CORS preflight, so propagation stays
your decision. To propagate from the browser, add the header where you make requests:
import { getTraceHeaders } from '@bucker/sdk-core/tracing'
fetch('/api/checkout', { method: 'POST', headers: { ...getTraceHeaders() }, body })
Remote configuration
At init the integration reads the project's replay settings from
GET /api/<projectId>/replay-config (DSN-authenticated) and caches them for an hour.
They can only make recording stricter than your code: they can force
maskAllText on, add mask/block/ignore selectors, revoke unmask, and cap
sampleRate. They can never turn masking off or raise a rate. On a first visit,
recording waits for the response (at most 3 seconds) so nothing is captured under a
looser rule. If the fetch fails, your code's own configuration applies. Set
remoteConfig: false to skip the request.
The settings live in Settings › Projects › Session replay. Enforce masking is also checked at ingest: while it is on, a recording that arrives unmasked is refused and nothing is stored, whatever the SDK sent.
Not built yet
The breadcrumb DSL's richer compaction is not implemented. Local-variable capture is Node-only in design and not implemented there either — see sdk-node.md.