Skip to content

📈 Open source, privacy-first web analytics — a cookie-less Google Analytics alternative with built-in error tracking and performance monitoring. Self-host it or use our cloud. Get started for free!

fix: keep session replays continuous across navigations

Blue Mouse848fedf2fee2
diff --git a/backend/apps/cloud/src/analytics/analytics.service.ts b/backend/apps/cloud/src/analytics/analytics.service.ts
index b92ac28b1..612110aa8 100644
--- a/backend/apps/cloud/src/analytics/analytics.service.ts
+++ b/backend/apps/cloud/src/analytics/analytics.service.ts
@@ -150,6 +150,34 @@ const MAX_SESSION_REPLAY_BYTES_PER_REPLAY = 150 * 1024 * 1024
const MAX_SESSION_REPLAY_DURATION_MS = 30 * 60 * 1000
const SESSION_REPLAY_CLEANUP_BATCH_SIZE = 500
const SESSION_REPLAY_CHUNK_FETCH_CONCURRENCY = 6
+const SESSION_REPLAY_CHUNK_INDEX_RANGE = MAX_SESSION_REPLAY_CHUNKS_PER_REPLAY
+const RESERVE_REPLAY_START_LUA = `
+local activeReplayKey = KEYS[1]
+local proposedReplayId = ARGV[1]
+local chunkIndexRange = tonumber(ARGV[2])
+local ttl = tonumber(ARGV[3])
+
+local replayId = redis.call("HGET", activeReplayKey, "replayId")
+local nextChunkIndex = tonumber(redis.call("HGET", activeReplayKey, "nextChunkIndex") or "0")
+
+if replayId == false or replayId == nil or replayId == "" then
+ replayId = proposedReplayId
+ nextChunkIndex = 0
+end
+
+local allocatedChunkIndex = nextChunkIndex
+redis.call(
+ "HSET",
+ activeReplayKey,
+ "replayId",
+ replayId,
+ "nextChunkIndex",
+ allocatedChunkIndex + chunkIndexRange
+)
+redis.call("EXPIRE", activeReplayKey, ttl)
+
+return { replayId, tostring(allocatedChunkIndex) }
+`
const RESERVE_REPLAY_USAGE_LUA = `
local reservationKey = KEYS[1]
local counterKey = KEYS[2]
@@ -1872,9 +1900,11 @@ export class AnalyticsService {
await this.recordSessionActivity(psid, pid, resolvedProfileId)
const retention = this.getSessionReplayRetention(project)
+ const replayStart = await this.reserveActiveReplayStart(pid, psid, replayId)
return {
- replayId,
+ replayId: replayStart.replayId,
+ nextChunkIndex: replayStart.nextChunkIndex,
psid,
privacy,
...retention,
@@ -1912,6 +1942,10 @@ export class AnalyticsService {
return `session-replay:usage-count:${dayjs.utc().format('YYYY-MM')}:${accountId}`
}
+ private getActiveReplayKey(pid: string, psid: string) {
+ return `session-replay:active:${pid}:${psid}`
+ }
+
private getReplayUsageTtlSeconds() {
return Math.max(60, dayjs.utc().endOf('month').diff(dayjs.utc(), 'second'))
}
@@ -1933,6 +1967,36 @@ export class AnalyticsService {
)
}
+ private getActiveReplayTtlSeconds() {
+ return Math.max(60, Math.ceil(MAX_SESSION_REPLAY_DURATION_MS / 1000))
+ }
+
+ private async reserveActiveReplayStart(
+ pid: string,
+ psid: string,
+ replayId: string,
+ ) {
+ const result = await redis.eval(
+ RESERVE_REPLAY_START_LUA,
+ 1,
+ this.getActiveReplayKey(pid, psid),
+ replayId,
+ SESSION_REPLAY_CHUNK_INDEX_RANGE,
+ this.getActiveReplayTtlSeconds(),
+ )
+ const [resolvedReplayId, nextChunkIndex] = Array.isArray(result)
+ ? result
+ : [replayId, 0]
+
+ return {
+ replayId:
+ typeof resolvedReplayId === 'string' && resolvedReplayId
+ ? resolvedReplayId
+ : replayId,
+ nextChunkIndex: Number(nextChunkIndex) || 0,
+ }
+ }
+
private getReplayChunkTimestamps(events: Record<string, unknown>[]) {
const timestamps = events
.map((event) =>
diff --git a/backend/apps/cloud/src/analytics/dto/session-replay.dto.ts b/backend/apps/cloud/src/analytics/dto/session-replay.dto.ts
index c02584dbf..5bae2e7e0 100644
--- a/backend/apps/cloud/src/analytics/dto/session-replay.dto.ts
+++ b/backend/apps/cloud/src/analytics/dto/session-replay.dto.ts
@@ -64,7 +64,7 @@ export class SessionReplayChunkDto extends SessionReplayStartDto {
@Type(() => Number)
@IsInt()
@Min(0)
- @Max(100000)
+ @Max(4294967295)
chunkIndex: number
@IsArray()
diff --git a/backend/apps/cloud/src/analytics/session-replay-export.service.ts b/backend/apps/cloud/src/analytics/session-replay-export.service.ts
index 438594c28..a6d87886e 100644
--- a/backend/apps/cloud/src/analytics/session-replay-export.service.ts
+++ b/backend/apps/cloud/src/analytics/session-replay-export.service.ts
@@ -46,7 +46,7 @@ export type SessionReplayExportJobData =
exportId: string
pid: string
psid: string
- replayId: string
+ replayId?: string
}
| {
type: 'cleanup'
@@ -57,7 +57,7 @@ export type SessionReplayExportJobData =
export interface SessionReplayExportState extends SessionReplayExportResponse {
pid: string
psid: string
- replayId: string
+ replayId?: string
objectKey?: string
createdAt: string
updatedAt: string
@@ -155,8 +155,9 @@ export class SessionReplayExportService {
this.validateReplayMetadata(replay.eventCount, replay.replayDuration)
+ const exportReplayId = replayId || 'session'
const exportId = hash(
- `${EXPORT_RENDERER_VERSION}:${pid}:${psid}:${replay.replayId}:${replay.eventCount}:${replay.replayDuration}`,
+ `${EXPORT_RENDERER_VERSION}:${pid}:${psid}:${exportReplayId}:${replay.eventCount}:${replay.replayDuration}`,
)
const existing = await this.getState(exportId)
@@ -181,7 +182,7 @@ export class SessionReplayExportService {
exportId,
pid,
psid,
- replayId: replay.replayId,
+ replayId,
status: 'queued',
progress: 0,
filename: this.getFilename(psid),
@@ -200,7 +201,7 @@ export class SessionReplayExportService {
exportId,
pid,
psid,
- replayId: replay.replayId,
+ replayId,
},
{
jobId: exportId,
diff --git a/packages/tracker-js/src/Lib.ts b/packages/tracker-js/src/Lib.ts
index b745bc8f0..046a3d847 100644
--- a/packages/tracker-js/src/Lib.ts
+++ b/packages/tracker-js/src/Lib.ts
@@ -34,6 +34,11 @@ type RrwebModule = RrwebGlobal & {
type SessionReplayPreloadOption = boolean | { rrwebUrl?: string }
+interface SessionReplayStartResponse {
+ replayId: string
+ nextChunkIndex: number
+}
+
declare global {
interface Window {
rrweb?: RrwebGlobal
@@ -297,6 +302,7 @@ const DEFAULT_SESSION_REPLAY_FLUSH_INTERVAL = 5000
const DEFAULT_SESSION_REPLAY_MAX_EVENTS = 100
const DEFAULT_SESSION_REPLAY_MAX_CHUNK_BYTES = 512 * 1024
const DEFAULT_SESSION_REPLAY_MAX_EVENT_BYTES = 5 * 1024 * 1024
+const DEFAULT_SESSION_REPLAY_MAX_DURATION_MS = 30 * 60 * 1000
const DEFAULT_SESSION_REPLAY_PRIVACY: SessionReplayPrivacy = 'total'
const DEFAULT_SESSION_REPLAY_SAMPLING = {
mousemove: 50,
@@ -853,6 +859,11 @@ export class Lib {
return defaultSessionReplayActions
}
+ const maxDurationMs =
+ typeof options.maxDurationMs === 'number' && options.maxDurationMs > 0
+ ? options.maxDurationMs
+ : DEFAULT_SESSION_REPLAY_MAX_DURATION_MS
+
if (!this.shouldSampleSessionReplay(options.sampleRate)) {
return defaultSessionReplayActions
}
@@ -869,13 +880,15 @@ export class Lib {
}
const privacy = this.getSessionReplayPrivacy(options.privacy)
- const replayId = this.createReplayId()
- const started = await this.sendSessionReplayStart(replayId, privacy)
+ const proposedReplayId = this.createReplayId()
+ const started = await this.sendSessionReplayStart(proposedReplayId, privacy)
if (!started) {
return defaultSessionReplayActions
}
+ const replayId = started.replayId
+
const flushIntervalMs =
typeof options.flushIntervalMs === 'number' && options.flushIntervalMs > 0
? options.flushIntervalMs
@@ -901,16 +914,12 @@ export class Lib {
maxBytesPerEventCandidate >= 1
? maxBytesPerEventCandidate
: DEFAULT_SESSION_REPLAY_MAX_EVENT_BYTES
- const maxDurationMs =
- typeof options.maxDurationMs === 'number' && options.maxDurationMs > 0
- ? options.maxDurationMs
- : null
const idleTimeoutMs =
typeof options.idleTimeoutMs === 'number' && options.idleTimeoutMs > 0
? options.idleTimeoutMs
: null
- let chunkIndex = 0
+ let chunkIndex = started.nextChunkIndex
let stopped = false
let events: RrwebEvent[] = []
let eventsByteLength = 0
@@ -1023,12 +1032,10 @@ export class Lib {
window.addEventListener('pagehide', flushOnPageExit)
document.addEventListener('visibilitychange', flushOnHidden)
- if (maxDurationMs) {
- maxDurationTimer = setTimeout(
- () => void stopSessionReplay(),
- maxDurationMs,
- )
- }
+ maxDurationTimer = setTimeout(
+ () => void stopSessionReplay(),
+ maxDurationMs,
+ )
if (idleTimeoutMs) {
SESSION_REPLAY_ACTIVITY_EVENTS.forEach((eventName) => {
@@ -1448,7 +1455,7 @@ export class Lib {
private async sendSessionReplayStart(
replayId: string,
privacy: SessionReplayPrivacy,
- ): Promise<boolean> {
+ ): Promise<SessionReplayStartResponse | null> {
try {
const apiBase = this.getApiBase()
const response = await fetch(`${apiBase}/log/session-replay/start`, {
@@ -1472,9 +1479,38 @@ export class Lib {
}),
})
- return response.ok
+ if (!response.ok) {
+ return null
+ }
+
+ try {
+ const result = (await response.json()) as Partial<{
+ replayId: unknown
+ nextChunkIndex: unknown
+ }>
+ const resolvedReplayId =
+ typeof result.replayId === 'string' && result.replayId
+ ? result.replayId
+ : replayId
+ const resolvedChunkIndex =
+ typeof result.nextChunkIndex === 'number' &&
+ Number.isFinite(result.nextChunkIndex) &&
+ result.nextChunkIndex >= 0
+ ? Math.floor(result.nextChunkIndex)
+ : 0
+
+ return {
+ replayId: resolvedReplayId,
+ nextChunkIndex: resolvedChunkIndex,
+ }
+ } catch {
+ return {
+ replayId,
+ nextChunkIndex: 0,
+ }
+ }
} catch {
- return false
+ return null
}
}
diff --git a/packages/tracker-js/tests/sessionReplay.test.ts b/packages/tracker-js/tests/sessionReplay.test.ts
index ae04a9b85..e89b89913 100644
--- a/packages/tracker-js/tests/sessionReplay.test.ts
+++ b/packages/tracker-js/tests/sessionReplay.test.ts
@@ -167,6 +167,78 @@ describe('Session replay tracking', () => {
expect(stopRecording).toHaveBeenCalledTimes(1)
})
+ test('uses backend replay id and chunk index across page loads without browser storage', async () => {
+ const replayId = 'server-replay-id'
+ const setItemSpy = jest.spyOn(Storage.prototype, 'setItem')
+ const getItemSpy = jest.spyOn(Storage.prototype, 'getItem')
+ let startCount = 0
+
+ fetchMock.mockImplementation((url) => {
+ if (String(url).includes('/session-replay/start')) {
+ const nextChunkIndex = startCount === 0 ? 0 : 1200
+ startCount += 1
+
+ return Promise.resolve({
+ ok: true,
+ json: async () => ({ replayId, nextChunkIndex }),
+ })
+ }
+
+ return Promise.resolve({ ok: true })
+ })
+
+ const { recordOptions } = usePackageRrweb()
+ const { init, startSessionReplay } = await loadTracker()
+
+ init(PROJECT_ID, { devMode: true })
+ const firstActions = await startSessionReplay({ flushIntervalMs: 60_000 })
+
+ recordOptions().emit({ type: 2, timestamp: 100 })
+ await firstActions.flush()
+
+ const firstChunkCall = fetchMock.mock.calls.find(([url]) =>
+ String(url).includes('/session-replay/chunk'),
+ )
+ const firstChunkBody = JSON.parse(firstChunkCall![1].body as string)
+ expect(firstChunkBody).toEqual(
+ expect.objectContaining({
+ replayId,
+ chunkIndex: 0,
+ }),
+ )
+
+ const secondModule = await loadTracker()
+ secondModule.init(PROJECT_ID, { devMode: true })
+ const secondActions = await secondModule.startSessionReplay({
+ flushIntervalMs: 60_000,
+ })
+ const startCalls = fetchMock.mock.calls.filter(([url]) =>
+ String(url).includes('/session-replay/start'),
+ )
+ expect(startCalls).toHaveLength(2)
+
+ recordOptions().emit({ type: 2, timestamp: 200 })
+ await secondActions.flush()
+
+ const chunkCalls = fetchMock.mock.calls.filter(([url]) =>
+ String(url).includes('/session-replay/chunk'),
+ )
+ const secondChunkBody = JSON.parse(chunkCalls[1][1].body as string)
+ expect(secondChunkBody).toEqual(
+ expect.objectContaining({
+ replayId,
+ chunkIndex: 1200,
+ }),
+ )
+ expect(setItemSpy).not.toHaveBeenCalled()
+ expect(getItemSpy).not.toHaveBeenCalled()
+
+ await secondActions.stop()
+ await firstActions.stop()
+ setItemSpy.mockRestore()
+ getItemSpy.mockRestore()
+ })
+
test('sampleRate can skip recording before loading rrweb', async () => {
const { init, startSessionReplay } = await loadTracker()