Session Replay
Use this skill when working on /sessions, replay ingest, replay storage, or
agent answers about browser recordings in the Analytics template.
Source Of Truth
- Replay ingest writes
session_recordingsandsession_replay_chunks. - The UI and agent must use
list-session-recordings,get-session-replay-summary, andget-session-replay-events. /sessions/:recordingIdis keyed bysession_recordings.id, notanalytics_events.session_id.environmentonlist-session-recordings(productionorbeta; omit for all) filters by the recording's host.betaalso covers PR previews and local runs, and a recording with no host counts as production. The Sessions page's traffic menu and row badge use the same rule, andview-screenreads?environment=.- Do not add actions that synthesize "sessions" from
analytics_events. Events can be linked beside a recording throughsession_id, but they are not playable replay rows by themselves.
Storage And Access
- Never expose object-storage URLs or raw
session_replay_chunksrows to the browser or agent. - Playback bytes must go through scoped server helpers that check
session-recordingaccess before reading private blob refs. - First-party SQL (
query-agent-native-analytics, dashboard panels) readssession_recordingsthrough the samesession-recordingaccess rule as the UI: the caller's own recordings, plus recordings in the active org that are org-visible or shared with the caller or that org. Any new SQL path over recordings must use that rule, not anorg_idmatch. - SQL inline chunks are a local/dev fallback only; production should use private or encrypted blob storage.
- A local Analytics app pointed at a production database must also use the key
that encrypted those replay blobs. Set
ANALYTICS_SECRETS_ENCRYPTION_KEYin an untracked local env file; do not replace the workspace-wideBETTER_AUTH_SECRETjust to read production replay storage. - When sharing a replay with an external agent, use
create-session-replay-agent-link. It mints a two-houragent_accessURL scoped to the recording, embeds a small SSR discovery payload on/sessions/:recordingId, and advertises/api/session-replay/agent-context.jsonplus bounded/api/session-replay/agent-events.jsonand/api/session-replay/agent-diagnostics.jsonreads. - When the link's creator has the Sessions triage Lab on, the context adds
keyMomentsandbuild. Each moment names what broke or what the person did, the route (null means unknown, in recordings from before route tracking), the steps before it, and aplayerUrl. That is the recording's frame page, which needs no sign-in: it stops just after the moment and fits the recording to the window, so the agent opens it in its own browser, waits for[data-replay-frame="ready"], and screenshots the page.[data-replay-frame="error"]means it could not be shown, andwindow.__anReplayFrame.reasonsays why.build.commitis the commit the page reported it was built from; anything holding the public replay key can report one, so it is a lead, not proof. Null means the recording did not report one.build.latestCommitappears when a reload moved the recording onto a newer deploy.keyMoments.completemeans every stored event was read; time the recorder never stored, such as while its uploads were paused, can still be missing. Failed agent runs and error toasts count as moments because neither reaches the console or network capture. A failed run's message is masked in newer recordings, so its moment carries the error code instead. - Do not make session recordings public just so an agent can inspect them. Tokenized agent links are the intended handoff path.
Console And Network Capture
- While recording, the core client (
session-replay.tsin@agent-native/core) patches console (log/info/warn/error/debug), windowerror/unhandledrejection,fetch, and XHR, and emits rrweb custom events taggedagent-native.consoleandagent-native.network. - Capture is on by default whenever session replay is enabled. Tune or disable
it with the
console/networkoptions on the session replay config; each accepts a boolean or an options object ({ maxEvents?: number });networkalso acceptscaptureErrorBodies(default true) andmaxErrorBodyLength(default 2048) to control the bounded 5xx response-body snippet. - Privacy bounds: request bodies and headers are never captured. Response
bodies are captured only as a bounded, redacted snippet for 5xx (server
error) responses, capped at
maxErrorBodyLengthchars; non-5xx and network-failure (status 0) responses never carry a body. URLs are scrubbed, messages are truncated, and recorder self-traffic (the replay ingest and tracking endpoints) is excluded. - Per-session budgets: 1000 console events and 2000 network events, with a truncation notice event once a budget is hit.
- On ingest,
deriveReplaySignalscomputes the realerrorCountfrom tagged console events plus the additivenetworkErrorCountcolumn onsession_recordings. Keep new columns additive. - Error, network-error, and rage-click deltas are added only for chunks newly stored by the ingest transaction, so retries do not count the same events twice. SQL increments keep concurrent uploads from overwriting those totals. Page counts remain max-based because the parser counts distinct URLs within each payload; older clients' cumulative overrides are also max-based.
App Events In Sessions
trackEventalso emits anagent-native.eventcustom event holding only{ name }(120 chars max, 1000 per replay, counted across page reloads). Telemetry names such aspageview,action.response, andsession statusstay unmarked; lifecycle aliases don't get a second marker. Never add event properties to the payload.- The replay viewer shows these markers, plus failed
/_agent-native/actions/<name>requests as "Action failed", only while the Sessions triage Lab is on. With the Lab off the viewer and the agent timeline keep their earlier shape. recordAnalyticsEventswrites the per-session event index (analytics_session_events) and a per-tenant coverage start inside the transaction that stores the events, in every sink mode. After that transaction commits it writes the daily catalog (analytics_event_catalog_daily) and each event's latest sighting (analytics_event_catalog_latest) best-effort, together in one short transaction, because the catalog lists events from the latest table. A catalog failure only warns, and the catalog never decides a filter. Lists, did/didn't filters, and the catalog read only these tables, never BigQuery. The catalog keeps the 1,000 most recently seen events, sorted by volume, and setstruncatedwhen it cut the list; its app flags still count every event in the range.- Indexes hold caller text raw, and one entry over Postgres's limit fails the
whole batch. Ingest cuts every indexed value with
server/lib/indexed-text.ts(event name, app, template, path) before any table sees it. A long user key keeps a prefix plus a hash of the whole value (boundedIdentity), so two users never merge into one. Row ids built from caller text go throughindexedRowId, which hashes an id that percent-encoding made too long. Session and recording ids are never cut, because a cut id could merge two sessions: replay ingest rejects session and recording ids over 256 characters, and an event's longer session id skips the session index. Bound any new indexed caller value there. - Public ingest (
/track,/api/analytics/replay) returns a thrown message only for an error built withrequestError(a numericstatusCode). Any other failure is logged and answered with a generic 500, because its message can quote internal database details. - Event filters exclude a session if any of its recordings started before the
tenant's coverage start, because one analytics session can span tabs.
Coverage starts only after a session write succeeds, and the reported start
is the latest among the viewer's tenants. "Didn't" also needs at least one
index row for the session and no gap marker: a failed index write rolls back
to a savepoint and records the batch's sessions in
analytics_session_event_gapsin the same transaction, so a later successful batch cannot make them look complete. If the marker cannot be written either, the batch fails and its events are not stored. Keep session index writes inside that transaction. Deploys ship code before the scheduled migration creates these tables, so untilanalytics_session_event_coverageexists ingest stores events unindexed and warns: with no coverage, no session can read as complete. Reads in that window report no coverage instead of failing: no event names, a null coverage start, an empty catalog, and no session matching an event filter. That is the only unmarked gap, and it holds only while the coverage table is the last index table a migration creates. The retention sweep removes a session's index rows together, once all of them are two days past replay retention, and its gap marker after that. The BigQuery-cutover purge leaves these tables alone.
Friction Signals
- Friction is derived at ingest into Analytics' own tables and read only
from them, in every sink mode. Replay signals (dead clicks, Sonner error
toasts, retry loops, leaving within 30 seconds of an error, stalled
requests over
STALLED_REQUEST_THRESHOLD_MS, 4xx and 5xx responses) come from the rrweb chunks inrecordSessionReplayChunks, one row per recording insession_recording_friction. Event signals (failed actions, agent failures, stuck chats, thumbs-down, quick backs, cancelled runs) and their trouble groups come from tracked events in a savepoint nested inside the event index savepoint, one row per session inanalytics_session_frictionplusanalytics_session_trouble. - A request the page aborted itself (status 0 with an error
isBenignAbortin core recognizes, or the recorder'sXMLHttpRequest aborted) is not a failure: it never feeds retry loops or leaving after an error. Neither is one the recorder markedpageLeaving: the browser cancels in-flight requests when the page navigates or reloads, with the same "Failed to fetch" as a network failure, so only the recorder can tell them apart. It still counts as a stalled request. Any other status-0 failure counts. - Never store page text or URLs: detector state keeps timestamps, rrweb node ids, and hashed request keys; quick backs compare hashed paths.
- One session id spans every tab, so a quick back compares pages only within
one page load (
page_load_idon each pageview). Pageviews from older clients send no id and are skipped: followed together, two tabs would look like one tab going back. - A replay row counts only while
processed_chunksequals the recording'schunk_count. Each batch continues from the stored detector state, whoselastSeqis the highest chunk measured; a seq the recorder lost is skipped. A batch that cannot be measured, or a chunk belowlastSeq, leaves the row behind and the recording reads as unmeasured until it ends. ThenremeasureReplayFrictionmeasures every stored chunk again in seq order; never continue a row that fell behind from fresh state. An event row counts only when the tenant's friction coverage began before every recording of the session and the session has neither an event index gap nor a friction gap (analytics_session_friction_gaps). A friction write failure rolls back only friction and records a friction gap; the index write stays. Only a failed friction gap insert fails the index savepoint. - Thumbs-down, cancelled runs, and quick backs are measured only for
sessions whose pageviews carried
agent_signals(AGENT_SIGNALS_PAGEVIEW_PROPERTYin core): older clients sampled stops, sent no ratings, and sent nopage_load_id. One session id spans every tab, so an old tab can share a session with a new one: any unmarked pageview or sampled stop setsagent_signals_missing, and both flags are OR-merged. Unlessagent_signals_measuredis set andagent_signals_missingis not, these counts read as null, stay out of the score, never match a filter, and sort last. A stop counts only when sent unsampled (sample_rateabsent or 1). - Reads must keep "unmeasured" (null) apart from "measured, no friction" (0).
Until the migration creates
analytics_session_friction_coverage(created last), ingest skips friction, filters match nothing, friction sorts fall back to newest, and details report every part as null. A friction filter or sort always returns the paginated shape withfrictionCoverageStartedAt, andview-screenpasses it on, so an empty match is read against coverage, never as zero. It covers the viewer's own org and personal tenants: the latest start among those with coverage, or null when one without coverage has recordings the viewer sees in the range. Recordings shared from other tenants read unmeasured on their own rows. errorIssueslinks occurrences inerror_events, which keeps only each issue's newest ones, then falls back to issues whoselast_session_recording_idis the recording, with a null count. A recording with errors Monitoring could capture and still no issue reads null (unknown), never [], unless its owner scope has no issues at all: it does not capture errors as issues, so [] is the truth there. Only captured exceptions can become issues, and a plainconsole.errornever does: the recorder marks console errorsexception: falseortrue, and the replay row counts the others inissue_errors, so a recording whose only errors were plain console errors reads []. A row measured before that column, or not measured from its start, falls back to the recording'serrorCount.- Agent failures group by a named cause from
AGENT_TROUBLE_CAUSESin core (no_model_connected,rate_limit,context_overflow,provider_error), else by error code, never by message text. Failed actions group by action and status. New causes need product approval; add them to that one list. - The score is a weighted sum with each signal capped at
SESSION_FRICTION_SIGNAL_CAP, computed per part at ingest and summed at read. Change weights only inSESSION_FRICTION_WEIGHTS. - Every friction surface is behind the Sessions triage Lab, in the UI and in
list-session-recordings,list-session-friction,view-screen, andget-session-replay-summary; a 403 names what the Lab gates (assertSessionsTriageLabEnabledtakes every feature the request used). With the Lab off, Sessions looks and behaves exactly as before; ingest still records friction. Waiting on the Lab state is shared with the speed filter; see "Performance In Sessions". - Without a friction filter or sort, the list loads without friction and its
rows read friction from
list-session-friction, one page of ids at most, through the recordings' access filter. A failed friction read then leaves the list in place with a retry. With a friction filter or sort, friction comes with the list and a failure is a list error. - The replay's dev tools show a Friction tab with every signal's count, its
trouble groups, and its issue links.
get-session-replay-summaryreturns the samefrictionfor the agent. A failed Lab state or friction read is reported aslabStateErrororfrictionError, never as no friction. Each is a fixed message, because the cause can quote database details; the server log keeps it. On the list,view-screenreports them beside the base list, and itsactiveFiltersecho the filters it applied, not the URL's. Its row excerpt drops trailing rows to stay under the agent's 50,000-character tool-result limit, so the page metadata after the rows always arrives; a cut setstruncated, andfullPageActionreads the whole page. Keep it that way when adding per-row fields: a bigger row means fewer rows, not a lost page.
Performance In Sessions
- Core's tracker sends one
web_vitalsevent per page view (route,navigation_type, and whichever ofttfb_ms,lcp_ms,inp_ms,clswere measured; an unmeasured metric is absent, never 0) and anagent-native.vitalsreplay marker with the same numbers.action.responsecarries therouteits request started on.routeis a React Router template such as/sessions/:id; when no manifest route matches it is omitted, never a raw path, which can hold slugs and emails. - Requests under
SLOW_REQUEST_THRESHOLD_MS(shared/slow-request.ts, 1 s) are sampled at 10% withsample_weight: 10; slow, failed, and 4xx responses always send with weight 1, so slow-request counts are exact. Use that constant for every "slow request" rule. Requests made while the page was hidden or cancelled are not counted. Slow requests (the app's own actions, 1 s, counted from events) are not friction's stalled requests (any captured replay request,STALLED_REQUEST_THRESHOLD_MS, 3 s): keep their names, fields, columns, and copy apart, and never show one number under the other's label. - Ingest strips NUL and replaces lone surrogates in
route,app, and the session id before hashing, as Postgres would store them; otherwise two values that store alike collide in one upsert and fail the batch. Measurements aboveperformanceCeiling(the open top bucket's floor: 64 s, CLS 5) are capped there rather than dropped, andsample_weightat 10,000. A session value at the ceiling is a floor: summaries list it inatLeastand the row hint shows it with ≥. recordSessionPerformancekeeps each session's worst vitals and its slow requests inanalytics_session_performance, inside the ingest transaction under a savepoint, with the same gap and coverage rules as the event index.recordRoutePerformanceadds weights to fixed histogram buckets inanalytics_route_performance_dailyafter commit, in its own short transaction. A failed write records a gap:session_id = ''marks a route day, read asincompleteDates; a session id marks that session, read asperformance.incompleteand kept byslow: anyonly, since missing data cannot rule it out;vitalsandrequestsneed a measured slow value. The slow filter correlates on each recording's own tenant. As with event friction, a share grants the recording, not its tenant's events: a recording shared from another tenant has no speed summary (null) and never matches a slow filter. A summary'sslowRequestsis null when the session made no measured request. A null summary is a session never measured: its row says "Speed not measured", and a slow match or a range from before coverage shows when speed coverage began, so it never reads as fast. Onlist-session-recordings,slowandincludePerformancealways return the paginated shape withperformanceCoverageStartedAt, as friction does. Bucket edges are positional, so changing them needs a newPERFORMANCE_HISTOGRAM_VERSION.- Percentiles interpolate inside one bucket. Past the first bucket each edge
is at most 28% above the last, so they are within about 28% of the exact
value; in the first bucket, within 1 ms (CLS 0.001). Keep that step when
adding edges, and keep every rating threshold an edge. A value in the open
top bucket is reported as
atLeast. A metric with no samples is null: no data, never fast. Before the migration createsanalytics_performance_coverage, ingest stores events without these aggregates and warns, the slow filter matches nothing, and reads report no coverage. - The replay's slow-request markers come from the
agent-native.slow_requestevents core records beside each slowaction.responsesomeone waited for, with that event's own duration, status, and outcome. Core and the timeline both apply the count's rule (isWaitedActionResponse, from core), so a marker matches exactly what the row counts and background requests never spend the replay's marker budget. Never derive them from replay network events: those stop timing at the response headers. Replays from clients without these events show no slow-request markers. slowandincludePerformanceonlist-session-recordings,list-session-performance,list-route-performance, the replay's vitals and slow-request markers, andperformanceonget-session-replay-summaryexist only while the Sessions triage Lab is on.- Lab state never holds up the base list. The page waits for it only when the
URL carries Lab-only conditions (did/didn't events, friction signals or
sorts,
slow,unused), with one wait for all of them, and for at most 5 s; a failed or hung read lists sessions without them and says so once, with a retry, rather than telling the user to turn on a Lab that may be on. Row speed hints load beside the list throughlist-session-performance, like row friction, keyed on the visible recording ids; when they fail the page says speed data could not load instead of showing no hints, apart from any friction failure.view-screenreads Lab state in its owntryand reads row friction and speed hints beside the base list, reportinglabStateError,frictionError, andperformanceErrorseparately; itsfullPageActionasks for both.
Made It, Didn't Use It
OUTPUT_USE_RULESinshared/output-use.tsis the one definition: per app, the output type, the events that make one, and the events that use it, each with aqualifiescheck on its properties. A use counts only for the sameoutput_idthe making event carried, withinOUTPUT_USE_WINDOW_DAYS(7). Opening an output never counts; a use shows it to people or takes it out of the app. Slides:generation_completedmakes a deck;presentation_endedwithslides_advanced≥ 1 andduration_ms≥MIN_PRESENTATION_MS(30 s), ordeck_exportedwithstatus: "completed"andslide_count≥ 1, uses it. A missing or non-numeric property never proves a use.- Adding an app means adding a rule whose used events need real use and whose
making event carries
output_id. Until then the event catalog flags it: an app withmakesOutputs(it sentgeneration_completed) and emptyusedItEventsis a gap, and entries carryoutputRole. Known holes: shared-audience presentations carry nooutput_id, and HTML export has no completion event. recordOutputOutcomesruns in the ingest transaction under a savepoint in every sink mode, so views never read raw events or BigQuery. Eachanalytics_output_outcomesrow keeps the earliest making, its session, and the earliest qualifying use; the upsert merges batches in any order. A failed outcome write records the batch's event-time span per tenant inanalytics_output_outcome_gaps, and so doesrecordLostOutputBatchwhen ingest fails to store a batch at all (sink lookup, volume limit, raw insert, index), since the tracker does not resend it. An output whose window overlaps a gap isunmeasured, neverunused, since the lost batch could hold its use. Outputs made before the tenant's coverage start are skipped. Before the migration createsanalytics_output_outcome_coverage(created last), ingest stores events without outcomes,unusedmatches nothing, and coverage is null.unusedonlist-session-recordingsmatches recordings whose own tenant's session made an output whose window has closed unused; a recording shared from another tenant never matches, nor does one a gap overlaps (a lost batch may have held an output it made). It returns the paginated shape withoutputsandomittedOutputsby recording id andoutputCoverageStartedAt. Statuses areused,unused,open(window still open), andunmeasured;urlis the recording's origin, its/<app>workspace mount when its first or last page is under it, and the rule'soutputPath. Recorded URLs come from the uploader, sourlis null unless the recording's replay key lists that origin (a key that accepts any origin links nothing) and both pages share it (a real recording never leaves its tab's origin). The app checks access when it opens.getSessionRecordingOutputsis the one reader. Per readable recording it gives[]for none, null when they are unknown (a recording from another tenant, since a share grants the recording, not its events, one whose tenant has not started output tracking, or one a gap overlaps), and at mostMAX_OUTPUTS_PER_RECORDINGoutputs, ranked unused first in SQL so a matched row always lists what it matched on;omittedOutputscounts the rest. Ids the viewer cannot read are absent.list-session-outputsreturns that shape and rejects a failed read.get-session-replay-summaryandview-screenon a replay both usewithSessionsTriage, which puts one recording'soutputs(andomittedOutputswhen some were left out) beside its friction and speed, and returnsoutputsErrorinstead when the read fails or skips the recording.- All of it is behind the Sessions triage Lab (
outputsin its 403). Rows link the first unused output beside the replay link, never inside it, and the replay header lists the recording's outputs with their status and says how many more it left out.
Agent Diagnostics Surface
buildSessionReplayAgentContextincludes adiagnosticssection: up to 50 console entries and 50 network entries, errors/failures first, with totals and truncated flags. Agent-context instructions steer agents to diagnostics as the primary debugging signal.- The agent timeline includes
console-error/network-errormarkers; error markers are kept preferentially under the 200-marker cap. App event, Web Vitals and slow-request markers belong to the Sessions triage Lab and stay off it (SESSIONS_TRIAGE_MARKER_TAGS); add any new Lab marker tag there. apis.diagnosticsadvertises the fuller bounded list:GET /api/session-replay/agent-diagnostics.json?id=<recordingId>&agent_access=<token>&kind=console|network|all&level=<level>&limit=<n>&offset=<n>&fromMs=<n>&toMs=<n>(limit defaults to 200, max 500). It uses the same recording-scopedagent_accesstoken as the other agent JSON APIs.offsetandfromMs/toMs(inclusive offsetMs window) enable full enumeration of a session's captured entries: page withoffset, or window withfromMs/toMsaround a timeline marker'soffsetMs. Providing any of these switches ordering to strictly chronological (no errors-first reshuffle) so pages are stable and disjoint.total/errorCount/warnCount/failedCountreflect the filtered (windowed/level/kind) population, not just the returned page, and each kind's response includeshasMorealongsidetruncatedso an agent can tell whether more entries remain. Route validation rejects negative/non-numericoffset/fromMs/toMsandfromMs > toMswith 400.
Dev Tools Panel
- The
/sessions/:recordingIdreplay player has a Dev Tools toggle that opens a panel with Console and Network tabs: filter chips, search, an error-count badge, and playback-time highlighting. - Rows expand inline under the selected line (Chrome-style). Expanding a row does not seek; use Jump to to move the playhead. Extend this panel instead of adding a separate debugging surface.
Playback Viewer
- Stream only when the manifest has dense, chronological chunk ranges and each available chunk's event count and timestamps match its manifest range. Start with the contiguous prefix from sequence 0, which must contain both rrweb Meta and FullSnapshot events. If any chunk is unavailable or any check fails, discard partial playback data and wait for the complete response before creating the normal player.
- For a validated prefix, create one
ReplayerwithliveMode: trueand keep that instance for the recording. Append later chunks withaddEvent; never rebuild the player as batches arrive, because that desynchronizes scrubbing and the playhead. Do not callstartLive(): retain rrweb's normal play/pause state machine. Use the recording summary for the full duration while chunks are still loading. - Keep backward and in-range seeks immediate. If playback reaches the loaded horizon, or a seek targets later data, pause and show buffering; continue at the exact buffered playhead after the contiguous prefix arrives. Do not skip inactive ranges past the loaded horizon. When the recording completes, restore normal end-of-recording behavior.
- Pass normal events to
Replayeruntouched. rrweb rebuilds them in a sandboxed iframe; pre-processing DOM, stylesheet, resource, or mutation payloads makes playback diverge from the captured page. In particular, never rewritehref,src,_cssText, CSSurl(), or Meta URLs toabout:blank; that exact remediation broke historical replay CSS in PR #2040. Handle request privacy at capture or the sandbox boundary instead of mutating stored rrweb events. Historical captures without inlined resources require live stylesheet/image/font requests for accurate rendering; the viewer accepts that fidelity tradeoff, uses rrweb's script-disabled sandbox plusreferrerpolicy="no-referrer", and must never add credentials or proxy those URLs through a privileged server. - Capture-time URL scrubbing must preserve load-bearing DOM resource attributes:
src,srcset,poster,data, andhrefonly on resource links such as stylesheets, preloads, and icons. Signed CDN query parameters are part of the resource identity; redacting them produces missing CSS, fonts, images, and oversized fallback icons. Keep scrubbing Meta/navigation URLs, anchor hrefs, and console/network diagnostics. Captured_cssTextand CSS@import/url()values must remain byte-identical. - rrweb rebuilds into an
about:srcdociframe, which inherits the Analytics document's CSP. Analytics currently sends no CSP header; if a future change adds restrictivestyle-src,font-src, orimg-srcdirectives, verify historical replays and resolve external imports/fonts at capture before blocking the recorded resource origins. Do not diagnose current font loss as CSP without checking the deployed response headers first. - Let rrweb own iframe sizing entirely via Meta / ViewportResize, and keep the
outer wrapper on the exact same raw dimensions for fit-to-stage scaling.
Player geometry and pointer coordinates are fully stock and untouched — do
not add width/aspect-ratio "recovery" heuristics or pointer-coordinate
projection. There is no such thing as a stored recording with corrupt
viewport geometry: a census of all production recordings found zero stored
widths >= 3,000px. The 2026-07 "ultra-wide replay" bugs (stages rendered
3,000–9,500px wide, frozen/teleporting cursors, giant icons) were caused
entirely by demo mode's fetch interceptor: its number redactor faked any
integer >= 1000 inside raw replay JSON at view time, corrupting Meta /
ViewportResize widths, pointer x/y coordinates, and numeric values inside
_cssTextand SVG attributes before rrweb ever saw the payload (heights below 1000 stayed real, which is why the symptom looked like a viewport problem rather than a redaction bug — two different sessions that both stored a 1,152px width read back as the same 4,491px, a deterministic salted-hash fingerprint of the redactor, not two coincidentally identical malformed recordings). This is fixed inpackages/core/src/demo/fetch-interceptor.ts: raw replay payload and manifest URLs are skipped from demo number redaction entirely, and must never be routed through it again. Do not reintroduce viewport clamping or pointer-coordinate projection in the player — they can now only corrupt genuine future recordings (for example, a real 3440x900 ultrawide browser window, or a short vertical window under 1,000px tall). - Keep rrweb's stock cursor stylesheet and its hotspot transform. During playback, hide the viewer's native pointer over Analytics' transparent click-to-pause overlay so it cannot masquerade as a frozen recorded cursor.
- Keep rrweb's recorded focus handling enabled. Focus and focus-visible state
affect menus, forms, and keyboard UX; disabling
triggerFocusmakes a valid snapshot diverge from the source page. insertStyleRulesmay suppress known toast/snackbar containers only. Never hide generic framework primitives such as[data-radix-popper-content-wrapper]: Radix dropdowns, selects, tooltips, and other real recorded product UI all share that wrapper.- Keep the realistic-fidelity purity/pass-through tests in
SessionDetailPage.spec.ts— raw event identity, raw viewport dimensions, and raw resize-state derivation (including the 3,189x885 tripwire against reintroducing a clamp) — as regression guards against reintroducing any viewport "recovery" or pointer-projection heuristic. Do not change their expectations merely to bless a new sanitizer or clamp; validate the affected replay in a browser first. An interim clamp for the exact 3,189x885 pair was also deleted once the view-time redaction root cause was proven; the earlier 3,000-3,999px band was rejected because it also catches real 3440px-wide displays. Neither the exact exception nor the band belongs in the player. - The event timeline soft-highlights the active marker, auto-scrolls it into view (pausing briefly after manual scroll), and supports search. It appears beside the player from ~880px content width upward.
- Dev Tools height is capped so the replay stage never collapses into a ribbon on short viewports; the scrubber playhead stays visually distinct from red error marker dots.
Debugging A User-Reported Bug
- Search the reporting user's email on
/sessionsto find their recordings. - Open the relevant session at
/sessions/:recordingIdand click Copy for agent to mint the two-hour tokenized link. - Paste the link to an agent. The agent fetches
/api/session-replay/agent-context.json, reads thediagnosticssection and timeline markers first, then drills intoapis.diagnostics(filtered bykind/level) andapis.eventsfor the fuller bounded lists as needed. - For human verification, open the Dev Tools panel in the replay player and jump-to-seek from the failing console or network row.
Capture Defaults
- Replay is on by default for signed-in hosted users when
VITE_AGENT_NATIVE_ANALYTICS_PUBLIC_KEYorconfigureTracking({ key })is present. The default sample rate is 100% of eligible sessions. - Replay remains off when no first-party analytics key is configured, and it is
not auto-enabled on localhost/local dev. Consumers can still enable replay
directly with
configureTracking({ key, endpoint, sessionReplay: { enabled: true } }). - Apps can opt out with
configureTracking({ sessionReplay: false }). - Agent-Native templates already call
configureTracking()in their roots; hosted template deployments only need the normal Agent-Native Analytics Vite/Netlify env vars on the recorded site. - Inputs are masked by default. Page text is visible unless marked with
.an-maskordata-an-mask. - UI rendering a run failure message or diagnostic details spreads
SESSION_REPLAY_MASK_PROPSfrom@agent-native/core/client/session-replay-privacyon the message element, including expanded details and failed tool rows. Keep headlines and recovery controls outside the mask. Thedata-an-maskmarker remains active when an app supplies its ownmaskTextSelector; selectors extend this privacy baseline. Do not rely on name redaction for run errors. Masking covers text only; the recorder keeps attributes, so leavetitleoff masked failure text. Wrap failed content that can render links or embedded frames, such as an MCP App or a failed activity summary, inSESSION_REPLAY_BLOCK_PROPS. - Use
.an-block,.an-ignore,data-an-block, ordata-an-ignorefor sensitive zones that should not be captured. - A definitive upload
409abandons only the conflicted replay identity and immediately starts rrweb again under a fresh per-tab id, producing a new Meta + FullSnapshot for long-lived SPA tabs. Recovery is limited to one restart until an upload succeeds so a misconfigured endpoint cannot loop; Analytics tracks the content-freesession replay upload rejectedlifecycle event so conflicts and recovery success are measurable. - Do not label an old recording "corrupt" from pointer coordinates, unknown mutation node ids, or changing Meta geometry alone. Those shapes can be legitimate with scrolling, iframes/shadow DOM, navigation, and resize. A historical-artifact notice needs a durable capture/ingest marker or another low-false-positive invariant; do not guess from playback heuristics.