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!

Add support for session replays to Swetrix CE

Blue Mouseacb3979547af
diff --git a/README.md b/README.md
index d92ae8680..11be3b5cf 100644
--- a/README.md
+++ b/README.md
@@ -81,7 +81,7 @@ Swetrix and Plausible are both privacy-first and open source; the main differenc
| Error tracking | βœ… | ❌ | ❌ |
| User profiles / identified users | βœ… | ❌ | ❌ |
| Feature flags & A/B experiments | βœ… | ❌ | ❌ |
-| Session replays | βœ… Cloud | ❌ | ❌ |
+| Session replays | βœ… | ❌ | ❌ |
| Revenue / MRR analytics | βœ… Cloud | ⚠️ ecommerce setup | ❌ |
| Ask AI / chat with your data | βœ… Cloud | ❌ | ❌ |
@@ -99,9 +99,10 @@ Your subscription directly funds maintenance and development of the open-source
### Self-hosting
-Prefer to run it yourself? Swetrix Community Edition (CE) ships the same core analytics: privacy-friendly traffic stats, custom events, sessions, funnels, performance and error tracking. Deploy the API and UI with Docker, connect MySQL / ClickHouse / Redis, and you're live.
+Prefer to run it yourself? Swetrix Community Edition (CE) ships the same core analytics: privacy-friendly traffic stats, custom events, sessions, session replays, funnels, performance and error tracking. Deploy the API and UI with Docker, connect ClickHouse / Redis, and configure a private S3-compatible bucket for replay recordings.
- **[Self-hosting guide β†’](https://swetrix.com/docs/selfhosting/how-to)**
+- **[Session replay storage setup β†’](https://swetrix.com/docs/selfhosting/session-replays)**
#### Cloud vs Community Edition
@@ -109,7 +110,7 @@ Prefer to run it yourself? Swetrix Community Edition (CE) ships the same core an
| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Infrastructure management** | βœ… Set up tracking in minutes. We manage server maintenance, upgrades and security for you. | ⚠️ You manage servers, installs, upgrades, scaling and backups. |
| **Core analytics (traffic, events, sessions, funnels, performance, errors)** | βœ… Included | βœ… Included |
-| **Session replays** | βœ… Included | ⚠️ Cloud only |
+| **Session replays** | βœ… Included | βœ… Included; requires S3-compatible storage |
| **Advanced features (Revenue, Experiments, AI)** | βœ… Included | ⚠️ Cloud only |
| **Teams & sharing** | βœ… Organisations, role-based access, direct invites, public and password-protected links. | ⚠️ Direct project invites, password-protected links and public projects only. |
| **Alerts & notifications** | βœ… Email, Slack, Telegram, Discord, webhook, web push | ⚠️ Not included |
diff --git a/backend/.env.example b/backend/.env.example
index 6722b2bc8..36df96d93 100644
--- a/backend/.env.example
+++ b/backend/.env.example
@@ -123,11 +123,15 @@ HETZNER_S3_BUCKET=
HETZNER_S3_ACCESS_KEY_ID=
HETZNER_S3_SECRET_ACCESS_KEY=
-# Hetzner S3 storage for Session Replays.
+# S3-compatible storage for Session Replays (Cloud and Community Edition).
# SESSION_REPLAY_S3_ENDPOINT is the location endpoint, for example https://fsn1.your-objectstorage.com.
# Do not include the bucket path in SESSION_REPLAY_S3_ENDPOINT.
SESSION_REPLAY_S3_ENDPOINT=
SESSION_REPLAY_S3_BUCKET=
+# Signing region. Defaults to the Hetzner location, or us-east-1 for other providers.
+SESSION_REPLAY_S3_REGION=
+# Set true for MinIO or providers requiring endpoint/bucket/key URLs.
+SESSION_REPLAY_S3_FORCE_PATH_STYLE=false
SESSION_REPLAY_S3_ACCESS_KEY_ID=
SESSION_REPLAY_S3_SECRET_ACCESS_KEY=
diff --git a/backend/apps/cloud/src/analytics/session-replay-s3.service.ts b/backend/apps/cloud/src/analytics/session-replay-s3.service.ts
index a7c8e4727..daaece44a 100644
--- a/backend/apps/cloud/src/analytics/session-replay-s3.service.ts
+++ b/backend/apps/cloud/src/analytics/session-replay-s3.service.ts
@@ -6,6 +6,7 @@ interface S3Config {
endpoint: string
bucket: string
region: string
+ forcePathStyle: boolean
accessKeyId: string
secretAccessKey: string
}
@@ -69,7 +70,12 @@ export class SessionReplayS3Service {
const endpointValue =
process.env.SESSION_REPLAY_S3_ENDPOINT || process.env.HETZNER_S3_ENDPOINT
const endpoint = endpointValue ? normalizeEndpoint(endpointValue) : ''
- const region = endpoint ? inferHetznerRegion(endpoint) : ''
+ const region =
+ process.env.SESSION_REPLAY_S3_REGION ||
+ (endpoint ? inferHetznerRegion(endpoint) : '') ||
+ 'us-east-1'
+ const forcePathStyle =
+ process.env.SESSION_REPLAY_S3_FORCE_PATH_STYLE === 'true'
const bucket =
process.env.SESSION_REPLAY_S3_BUCKET || process.env.HETZNER_S3_BUCKET
const accessKeyId =
@@ -87,6 +93,7 @@ export class SessionReplayS3Service {
endpoint,
bucket,
region,
+ forcePathStyle,
accessKeyId,
secretAccessKey,
}
@@ -119,7 +126,7 @@ export class SessionReplayS3Service {
)
if (!response.ok) {
- throw new Error(`Hetzner S3 PUT failed with status ${response.status}`)
+ throw new Error(`S3 PUT failed with status ${response.status}`)
}
}
@@ -131,7 +138,7 @@ export class SessionReplayS3Service {
}
if (!response.ok) {
- throw new Error(`Hetzner S3 GET failed with status ${response.status}`)
+ throw new Error(`S3 GET failed with status ${response.status}`)
}
return Buffer.from(await response.arrayBuffer())
@@ -149,7 +156,7 @@ export class SessionReplayS3Service {
}
if (!response.ok) {
- throw new Error(`Hetzner S3 GET failed with status ${response.status}`)
+ throw new Error(`S3 GET failed with status ${response.status}`)
}
if (!response.body) {
@@ -167,7 +174,7 @@ export class SessionReplayS3Service {
const response = await this.signedFetch('DELETE', key)
if (!response.ok && response.status !== 404) {
- throw new Error(`Hetzner S3 DELETE failed with status ${response.status}`)
+ throw new Error(`S3 DELETE failed with status ${response.status}`)
}
}
@@ -191,7 +198,7 @@ export class SessionReplayS3Service {
)
if (!response.ok) {
- throw new Error(`Hetzner S3 LIST failed with status ${response.status}`)
+ throw new Error(`S3 LIST failed with status ${response.status}`)
}
const xml = await response.text()
@@ -250,7 +257,7 @@ export class SessionReplayS3Service {
attempt < attempts - 1
) {
lastError = new Error(
- `Hetzner S3 ${method} failed with status ${response.status}`,
+ `S3 ${method} failed with status ${response.status}`,
)
continue
}
@@ -274,7 +281,7 @@ export class SessionReplayS3Service {
): Promise<Response> {
const config = this.getConfig()
if (!config) {
- throw new Error('Hetzner S3 session replay storage is not configured')
+ throw new Error('S3 session replay storage is not configured')
}
const hasStreamBody = body instanceof Readable
@@ -298,8 +305,12 @@ export class SessionReplayS3Service {
)
.join('&')
- endpoint.hostname = `${config.bucket}.${endpoint.hostname}`
- endpoint.pathname = `/${encodeKeyPath(key)}`
+ if (config.forcePathStyle) {
+ endpoint.pathname = `/${encodeURIComponent(config.bucket)}/${encodeKeyPath(key)}`
+ } else {
+ endpoint.hostname = `${config.bucket}.${endpoint.hostname}`
+ endpoint.pathname = `/${encodeKeyPath(key)}`
+ }
endpoint.search = canonicalQuery ? `?${canonicalQuery}` : ''
const headers: HeaderMap = {
diff --git a/backend/apps/community/src/analytics/analytics.controller.ts b/backend/apps/community/src/analytics/analytics.controller.ts
index 6c6400821..823c40a9f 100644
--- a/backend/apps/community/src/analytics/analytics.controller.ts
+++ b/backend/apps/community/src/analytics/analytics.controller.ts
@@ -1,3 +1,12 @@
+import type { Response as ExpressResponse } from 'express'
+import { SessionReplayExportService } from './session-replay-export.service'
+import {
+ GetSessionReplayDto,
+ GetSessionReplaysDto,
+ SessionReplayExportStartDto,
+ SessionReplayChunkDto,
+ SessionReplayStartDto,
+} from './dto/session-replay.dto'
import _isEmpty from 'lodash/isEmpty'
import _isArray from 'lodash/isArray'
import _map from 'lodash/map'
@@ -8,6 +17,9 @@ import utc from 'dayjs/plugin/utc'
import dayjsTimezone from 'dayjs/plugin/timezone'
import {
Controller,
+ Delete,
+ Param,
+ StreamableFile,
Body,
Query,
UseGuards,
@@ -210,6 +222,7 @@ const getPageFromReferrer = (referrer?: string | string[] | null) => {
export class AnalyticsController {
constructor(
private readonly analyticsService: AnalyticsService,
+ private readonly sessionReplayExportService: SessionReplayExportService,
private readonly logger: AppLoggerService,
private readonly gscService: GSCService,
private readonly experimentService: ExperimentService,
@@ -2999,4 +3012,288 @@ export class AnalyticsController {
const keywords = await this.gscService.getKeywords(pid, groupFrom, groupTo)
return { keywords }
}
+
+ @Post('session-replay/start')
+ @Public()
+ async startSessionReplay(
+ @Body() replayDTO: SessionReplayStartDto,
+ @Headers() headers,
+ @Ip() reqIP,
+ ) {
+ const { 'user-agent': userAgent, origin } = headers
+ const ip = getIPFromHeaders(headers) || reqIP || ''
+
+ await checkRateLimit(ip, 'session-replay-start', 120, 60)
+ await checkRateLimit(replayDTO.pid, 'session-replay-start', 2000, 60)
+
+ const botResult = await this.analyticsService.checkBot(
+ replayDTO.pid,
+ userAgent,
+ headers,
+ ip,
+ headers.referer || headers.referrer,
+ replayDTO.pg,
+ 'session_replay',
+ )
+
+ if (botResult.isBot) {
+ return BOT_RESPONSE
+ }
+
+ const project = await this.analyticsService.validate(replayDTO, origin, ip)
+ const { country } = getIPDetails(ip, replayDTO.tz)
+ this.analyticsService.checkCountryBlacklist(project, country)
+
+ this.logger.log(
+ `pid: ${replayDTO.pid}, replayId: ${replayDTO.replayId}`,
+ 'POST /analytics/session-replay/start',
+ )
+
+ return this.analyticsService.startSessionReplay(
+ project,
+ replayDTO.pid,
+ replayDTO.replayId,
+ replayDTO.privacy,
+ userAgent,
+ ip,
+ replayDTO.profileId,
+ )
+ }
+
+ @Post('session-replay/chunk')
+ @Public()
+ async uploadSessionReplayChunk(
+ @Body() replayDTO: SessionReplayChunkDto,
+ @Headers() headers,
+ @Ip() reqIP,
+ ) {
+ const { 'user-agent': userAgent, origin } = headers
+ const ip = getIPFromHeaders(headers) || reqIP || ''
+
+ await checkRateLimit(ip, 'session-replay-chunk', 600, 60)
+ await checkRateLimit(replayDTO.pid, 'session-replay-chunk', 5000, 60)
+
+ const botResult = await this.analyticsService.checkBot(
+ replayDTO.pid,
+ userAgent,
+ headers,
+ ip,
+ headers.referer || headers.referrer,
+ replayDTO.pg,
+ 'session_replay',
+ )
+
+ if (botResult.isBot) {
+ return BOT_RESPONSE
+ }
+
+ const project = await this.analyticsService.validate(replayDTO, origin, ip)
+ const { country } = getIPDetails(ip, replayDTO.tz)
+ this.analyticsService.checkCountryBlacklist(project, country)
+
+ this.logger.log(
+ `pid: ${replayDTO.pid}, replayId: ${replayDTO.replayId}, chunkIndex: ${replayDTO.chunkIndex}`,
+ 'POST /analytics/session-replay/chunk',
+ )
+
+ return this.analyticsService.storeSessionReplayChunk(
+ project,
+ replayDTO.pid,
+ replayDTO.replayId,
+ replayDTO.privacy,
+ replayDTO.chunkIndex,
+ replayDTO.events,
+ userAgent,
+ ip,
+ )
+ }
+
+ @Get('session-replays')
+ @Auth(true, true)
+ async getSessionReplays(
+ @Query() data: GetSessionReplaysDto,
+ @CurrentUserId() uid: string,
+ @Headers() headers: { 'x-password'?: string },
+ ) {
+ const { pid, period, from, to, filters, timezone = DEFAULT_TIMEZONE } = data
+
+ await this.analyticsService.checkProjectAccess(
+ pid,
+ uid,
+ headers['x-password'],
+ )
+
+ const take = this.analyticsService.getSafeNumber(data.take, 30)
+ const skip = this.analyticsService.getSafeNumber(data.skip, 0)
+
+ if (take > 150) {
+ throw new BadRequestException(
+ 'The maximum number of session replays to return is 150',
+ )
+ }
+
+ this.logger.log(
+ `pid: ${pid}, period: ${period}, take: ${take}, skip: ${skip}`,
+ 'GET /analytics/session-replays',
+ )
+
+ const [filtersQuery, filtersParams, appliedFilters, customEVFilterApplied] =
+ this.analyticsService.getFiltersQuery(
+ normalizeFiltersToV1Json(filters, 'traffic'),
+ DataType.ANALYTICS,
+ )
+
+ let timeBucket
+ let diff
+
+ if (period === 'all') {
+ const res = await this.analyticsService.calculateTimeBucketForAllTime(
+ pid,
+ ['pageview', 'custom_event', 'error'] as const,
+ )
+
+ timeBucket = res.timeBucket[0]
+ diff = res.diff
+ } else {
+ timeBucket = getLowestPossibleTimeBucket(period, from, to)
+ }
+
+ const safeTimezone = this.analyticsService.getSafeTimezone(timezone)
+ const { groupFromUTC, groupToUTC } = this.analyticsService.getGroupFromTo(
+ from,
+ to,
+ timeBucket,
+ period,
+ safeTimezone,
+ diff,
+ )
+
+ const paramsData = {
+ params: {
+ pid,
+ groupFrom: groupFromUTC,
+ groupTo: groupToUTC,
+ ...filtersParams,
+ },
+ }
+
+ const replays = await this.analyticsService.getSessionReplaysList(
+ filtersQuery,
+ paramsData,
+ safeTimezone,
+ take,
+ skip,
+ customEVFilterApplied,
+ )
+
+ return { replays, appliedFilters, take, skip }
+ }
+
+ @Get('session-replay')
+ @Auth(true, true)
+ async getSessionReplay(
+ @Query() data: GetSessionReplayDto,
+ @CurrentUserId() uid: string,
+ @Headers() headers: { 'x-password'?: string },
+ ) {
+ const { pid, psid, replayId } = data
+
+ await this.analyticsService.checkProjectAccess(
+ pid,
+ uid,
+ headers['x-password'],
+ )
+
+ this.logger.log(
+ `pid: ${pid}, psid: ${psid}, replayId: ${replayId || 'latest'}`,
+ 'GET /analytics/session-replay',
+ )
+
+ return this.analyticsService.getSessionReplay(pid, psid, replayId)
+ }
+
+ @Delete('session-replay')
+ @Auth(true, true)
+ async deleteSessionReplay(
+ @Query() data: GetSessionReplayDto,
+ @CurrentUserId() uid: string,
+ ) {
+ const { pid, psid, replayId } = data
+
+ await this.analyticsService.checkManageAccess(pid, uid)
+
+ this.logger.log(
+ `pid: ${pid}, psid: ${psid}, replayId: ${replayId || 'latest'}`,
+ 'DELETE /analytics/session-replay',
+ )
+
+ return this.analyticsService.deleteSessionReplay(pid, psid, replayId)
+ }
+
+ @Post('session-replay/export')
+ @Auth(true, true)
+ async startSessionReplayExport(
+ @Body() data: SessionReplayExportStartDto,
+ @CurrentUserId() uid: string | null,
+ @Headers() headers: { 'x-password'?: string; 'user-agent'?: string },
+ @Ip() requestIp: string,
+ ) {
+ const { pid, psid, replayId } = data
+
+ await this.analyticsService.checkProjectAccess(
+ pid,
+ uid,
+ headers['x-password'],
+ )
+
+ const ip = getIPFromHeaders(headers) || requestIp || ''
+ await checkRateLimit(uid || ip || pid, 'session-replay-export-user', 5, 60)
+ await checkRateLimit(pid, 'session-replay-export-project', 20, 60)
+
+ this.logger.log(
+ `pid: ${pid}, psid: ${psid}, replayId: ${replayId || 'latest'}`,
+ 'POST /analytics/session-replay/export',
+ )
+
+ return this.sessionReplayExportService.startExport(pid, psid, replayId)
+ }
+
+ @Get('session-replay/export/:exportId')
+ @Auth(true, true)
+ async getSessionReplayExport(
+ @Param('exportId') exportId: string,
+ @CurrentUserId() uid: string | null,
+ @Headers() headers: { 'x-password'?: string },
+ ) {
+ const exportState =
+ await this.sessionReplayExportService.assertExportAccess(exportId)
+
+ await this.analyticsService.checkProjectAccess(
+ exportState.pid,
+ uid,
+ headers['x-password'],
+ )
+
+ return this.sessionReplayExportService.getExport(exportId)
+ }
+
+ @Get('session-replay/export/:exportId/download')
+ @Auth(true, true)
+ async downloadSessionReplayExport(
+ @Param('exportId') exportId: string,
+ @CurrentUserId() uid: string | null,
+ @Headers() headers: { 'x-password'?: string },
+ @Response({ passthrough: true }) response: ExpressResponse,
+ ): Promise<StreamableFile> {
+ const exportState =
+ await this.sessionReplayExportService.assertExportAccess(exportId)
+
+ await this.analyticsService.checkProjectAccess(
+ exportState.pid,
+ uid,
+ headers['x-password'],
+ )
+
+ return this.sessionReplayExportService.downloadExport(exportId, response)
+ }
}
diff --git a/backend/apps/community/src/analytics/analytics.module.ts b/backend/apps/community/src/analytics/analytics.module.ts
index 413e1b5df..24ff05772 100644
--- a/backend/apps/community/src/analytics/analytics.module.ts
+++ b/backend/apps/community/src/analytics/analytics.module.ts
@@ -1,3 +1,10 @@
+import { BullModule } from '@nestjs/bullmq'
+import { SessionReplayS3Service } from './session-replay-s3.service'
+import {
+ SessionReplayExportService,
+ SESSION_REPLAY_EXPORT_QUEUE,
+} from './session-replay-export.service'
+import { SessionReplayExportProcessor } from './session-replay-export.processor'
import { Module, forwardRef } from '@nestjs/common'
import { AnalyticsService } from './analytics.service'
@@ -22,9 +29,17 @@ import { ProjectV2Controller } from './v2/controllers/project-v2.controller'
import { SeoV2Controller } from './v2/controllers/seo-v2.controller'
@Module({
- imports: [AppLoggerModule, ProjectModule, forwardRef(() => ExperimentModule)],
+ imports: [
+ AppLoggerModule,
+ forwardRef(() => ProjectModule),
+ forwardRef(() => ExperimentModule),
+ BullModule.registerQueue({ name: SESSION_REPLAY_EXPORT_QUEUE }),
+ ],
providers: [
AnalyticsService,
+ SessionReplayS3Service,
+ SessionReplayExportService,
+ SessionReplayExportProcessor,
AnalyticsV2Service,
SeoV2Service,
BotDetectionService,
diff --git a/backend/apps/community/src/analytics/analytics.service.ts b/backend/apps/community/src/analytics/analytics.service.ts
index 4c08a2e37..43240aa18 100644
--- a/backend/apps/community/src/analytics/analytics.service.ts
+++ b/backend/apps/community/src/analytics/analytics.service.ts
@@ -1,3 +1,4 @@
+import { gzipSync, gunzipSync } from 'zlib'
import crypto from 'crypto'
import _isEmpty from 'lodash/isEmpty'
import _split from 'lodash/split'
@@ -27,6 +28,7 @@ import dayjsTimezone from 'dayjs/plugin/timezone'
import isSameOrBefore from 'dayjs/plugin/isSameOrBefore'
import {
Injectable,
+ PayloadTooLargeException,
BadRequestException,
InternalServerErrorException,
HttpException,
@@ -51,6 +53,8 @@ import {
TRAFFIC_METAKEY_COLUMNS,
} from '../common/constants'
import { SaltService } from './salt.service'
+import { SessionReplayS3Service } from './session-replay-s3.service'
+import { SessionReplayPrivacyMode } from './dto/session-replay.dto'
import {
BotDetectionService,
BotEndpoint,
@@ -109,6 +113,170 @@ import { ProjectViewCustomEventDto } from '../project/dto/create-project-view.dt
import { UAParser } from '@ua-parser-js/pro-business'
import { extensions } from './utils/ua-parser'
+const SESSION_REPLAY_RETENTION_VALUES = [30, 90, 365, 1825] as const
+const MAX_SESSION_REPLAY_EVENTS_PER_CHUNK = 1000
+const MAX_SESSION_REPLAY_EVENT_BYTES = 5 * 1024 * 1024
+const MAX_SESSION_REPLAY_CHUNK_BYTES = 15 * 1024 * 1024
+const MAX_SESSION_REPLAY_CHUNKS_PER_REPLAY = 1200
+const MAX_SESSION_REPLAY_EVENTS_PER_REPLAY = 100000
+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 maxDurationMs = tonumber(ARGV[4])
+local time = redis.call("TIME")
+local currentTimeMs = tonumber(time[1]) * 1000 + math.floor(tonumber(time[2]) / 1000)
+
+local replayId = redis.call("HGET", activeReplayKey, "replayId")
+local replayStartTs = tonumber(redis.call("HGET", activeReplayKey, "replayStartTs") or "")
+local nextChunkIndex = tonumber(redis.call("HGET", activeReplayKey, "nextChunkIndex") or "0")
+
+if
+ replayId == false or replayId == nil or replayId == "" or
+ replayStartTs == nil or replayStartTs + maxDurationMs <= currentTimeMs
+then
+ replayId = proposedReplayId
+ replayStartTs = currentTimeMs
+ nextChunkIndex = 0
+end
+
+local allocatedChunkIndex = nextChunkIndex
+redis.call(
+ "HSET",
+ activeReplayKey,
+ "replayId",
+ replayId,
+ "replayStartTs",
+ tostring(replayStartTs),
+ "nextChunkIndex",
+ allocatedChunkIndex + chunkIndexRange
+)
+redis.call("EXPIRE", activeReplayKey, ttl)
+
+return { replayId, tostring(allocatedChunkIndex) }
+`
+const RESERVE_REPLAY_CHUNK_LUA = `
+local chunkSetKey = KEYS[1]
+local countersKey = KEYS[2]
+local firstTsKey = KEYS[3]
+local lastTsKey = KEYS[4]
+local maxChunks = tonumber(ARGV[1])
+local maxEvents = tonumber(ARGV[2])
+local maxBytes = tonumber(ARGV[3])
+local maxDurationMs = tonumber(ARGV[4])
+local chunkIndex = ARGV[5]
+local eventCount = tonumber(ARGV[6])
+local uncompressedBytes = tonumber(ARGV[7])
+local firstTimestamp = tonumber(ARGV[8])
+local lastTimestamp = tonumber(ARGV[9])
+local ttl = tonumber(ARGV[10])
+
+if redis.call("SADD", chunkSetKey, chunkIndex) == 0 then
+ return -4
+end
+
+local chunks = redis.call("HINCRBY", countersKey, "chunks", 1)
+local events = redis.call("HINCRBY", countersKey, "events", eventCount)
+local bytes = redis.call("HINCRBY", countersKey, "bytes", uncompressedBytes)
+
+if firstTimestamp ~= nil then
+ redis.call("ZADD", firstTsKey, firstTimestamp, chunkIndex)
+end
+
+if lastTimestamp ~= nil then
+ redis.call("ZADD", lastTsKey, lastTimestamp, chunkIndex)
+end
+
+local first = redis.call("ZRANGE", firstTsKey, 0, 0, "WITHSCORES")
+local last = redis.call("ZREVRANGE", lastTsKey, 0, 0, "WITHSCORES")
+local duration = 0
+
+if first[2] ~= nil and last[2] ~= nil then
+ duration = tonumber(last[2]) - tonumber(first[2])
+end
+
+local result = 1
+if chunks > maxChunks then
+ result = -1
+elseif events > maxEvents then
+ result = -2
+elseif bytes > maxBytes then
+ result = -3
+elseif duration > maxDurationMs then
+ result = -5
+end
+
+if result ~= 1 then
+ redis.call("SREM", chunkSetKey, chunkIndex)
+ redis.call("HINCRBY", countersKey, "chunks", -1)
+ redis.call("HINCRBY", countersKey, "events", -eventCount)
+ redis.call("HINCRBY", countersKey, "bytes", -uncompressedBytes)
+ redis.call("ZREM", firstTsKey, chunkIndex)
+ redis.call("ZREM", lastTsKey, chunkIndex)
+ return result
+end
+
+redis.call("EXPIRE", chunkSetKey, ttl)
+redis.call("EXPIRE", countersKey, ttl)
+redis.call("EXPIRE", firstTsKey, ttl)
+redis.call("EXPIRE", lastTsKey, ttl)
+return 1
+`
+const RELEASE_REPLAY_CHUNK_LUA = `
+local chunkSetKey = KEYS[1]
+local countersKey = KEYS[2]
+local firstTsKey = KEYS[3]
+local lastTsKey = KEYS[4]
+local chunkIndex = ARGV[1]
+local eventCount = tonumber(ARGV[2])
+local uncompressedBytes = tonumber(ARGV[3])
+
+if redis.call("SREM", chunkSetKey, chunkIndex) ~= 1 then
+ return 0
+end
+
+local chunks = redis.call("HINCRBY", countersKey, "chunks", -1)
+redis.call("HINCRBY", countersKey, "events", -eventCount)
+redis.call("HINCRBY", countersKey, "bytes", -uncompressedBytes)
+redis.call("ZREM", firstTsKey, chunkIndex)
+redis.call("ZREM", lastTsKey, chunkIndex)
+
+if chunks <= 0 then
+ redis.call("DEL", chunkSetKey, countersKey, firstTsKey, lastTsKey)
+end
+
+return 1
+`
+
+const mapLimit = async <T, R>(
+ items: T[],
+ limit: number,
+ fn: (item: T, index: number) => Promise<R>,
+): Promise<R[]> => {
+ const results: R[] = new Array(items.length)
+ const concurrency = Math.max(1, Math.min(limit, items.length))
+ let nextIndex = 0
+
+ const workers = Array.from({ length: concurrency }).map(async () => {
+ while (true) {
+ const current = nextIndex++
+ if (current >= items.length) {
+ break
+ }
+ results[current] = await fn(items[current], current)
+ }
+ })
+
+ await Promise.all(workers)
+ return results
+}
+
dayjs.extend(utc)
dayjs.extend(dayjsTimezone)
dayjs.extend(isSameOrBefore)
@@ -200,6 +368,9 @@ const JOURNEY_EXIT_TARGET = '__exit__'
// Event types that can be targeted by the data-deletion tool.
const DELETABLE_EVENT_TYPES = [...DATA_DELETION_EVENT_TYPES]
+const EVENT_TABLE_DELETION_TYPES = DELETABLE_EVENT_TYPES.filter(
+ (type) => type !== 'session_replay',
+)
// Sentinel bounds used when no explicit date range is given, so that
// session-scoped filters (entry/exit page, referrer) still resolve.
const DELETION_MIN_DATE = '2000-01-01 00:00:00'
@@ -556,6 +727,7 @@ export class AnalyticsService {
constructor(
private readonly projectService: ProjectService,
private readonly saltService: SaltService,
+ private readonly sessionReplayStorage: SessionReplayS3Service,
private readonly botDetectionService: BotDetectionService,
) {}
@@ -1857,26 +2029,21 @@ export class AnalyticsService {
DataType.ANALYTICS,
)
- from = from ? dayjs.utc(from).format('YYYY-MM-DD HH:mm:ss') : null
- to = to ? dayjs.utc(to).format('YYYY-MM-DD HH:mm:ss') : null
+ const dateRange = this.getDataDeletionDateRange(from, to)
+ from = dateRange.from
+ to = dateRange.to
- const hasRange = Boolean(from && to)
const params: Record<string, unknown> = {
pid,
- types: DELETABLE_EVENT_TYPES,
+ types: EVENT_TABLE_DELETION_TYPES,
groupFrom: from || DELETION_MIN_DATE,
groupTo: to || DELETION_MAX_DATE,
...filtersParams,
+ ...(from ? { from } : {}),
+ ...(to ? { to } : {}),
}
- let dateCondition = ''
- if (hasRange) {
- params.from = from
- params.to = to
- dateCondition = 'AND created BETWEEN {from:String} AND {to:String}'
- }
-
- const whereClause = `pid = {pid:FixedString(12)} AND type IN ({types:Array(String)}) ${dateCondition} ${filtersQuery}`
+ const whereClause = `pid = {pid:FixedString(12)} AND type IN ({types:Array(String)}) ${dateRange.condition} ${filtersQuery}`
const { data: countRows } = await clickhouse
.query({
@@ -1912,15 +2079,37 @@ export class AnalyticsService {
}
}
+ // Session replays aren't rows in the `events` table, so count them
+ // separately using the same date range + (filter-resolved) sessions.
+ const replayCount = await this.countMatchingSessionReplays(
+ pid,
+ filtersQuery,
+ filtersParams,
+ from,
+ to,
+ dateRange.condition,
+ )
+ if (replayCount > 0) {
+ counts.session_replay = replayCount
+ total += replayCount
+ }
+
if (total === 0) {
return { counts: {}, total: 0, timeline: { x: [], counts: [] } }
}
+ const timelineFrom = from || minCreated
+ const timelineTo = to || maxCreated
+
+ if (!timelineFrom || !timelineTo) {
+ return { counts, total, timeline: { x: [], counts: [] } }
+ }
+
const timeline = await this.buildDeletionTimeline(
whereClause,
params,
- hasRange ? from : minCreated,
- hasRange ? to : maxCreated,
+ timelineFrom,
+ timelineTo,
)
return { counts, total, timeline }
@@ -2001,48 +2190,66 @@ export class AnalyticsService {
throw new BadRequestException('No event types selected for deletion')
}
+ const eventTableTypes = _filter(safeTypes, (type) =>
+ _includes(EVENT_TABLE_DELETION_TYPES, type),
+ )
+
const [filtersQuery, filtersParams] = this.getFiltersQuery(
filters,
DataType.ANALYTICS,
)
- from = from ? dayjs.utc(from).format('YYYY-MM-DD HH:mm:ss') : null
- to = to ? dayjs.utc(to).format('YYYY-MM-DD HH:mm:ss') : null
+ const dateRange = this.getDataDeletionDateRange(from, to)
+ from = dateRange.from
+ to = dateRange.to
- const hasRange = Boolean(from && to)
const params: Record<string, unknown> = {
pid,
- types: safeTypes,
+ types: eventTableTypes,
groupFrom: from || DELETION_MIN_DATE,
groupTo: to || DELETION_MAX_DATE,
...filtersParams,
+ ...(from ? { from } : {}),
+ ...(to ? { to } : {}),
}
- let dateCondition = ''
- if (hasRange) {
- params.from = from
- params.to = to
- dateCondition = 'AND created BETWEEN {from:String} AND {to:String}'
+ if (_includes(safeTypes, 'session_replay')) {
+ await this.deleteMatchingSessionReplays(
+ pid,
+ filtersQuery,
+ filtersParams,
+ from,
+ to,
+ dateRange.condition,
+ )
}
- const commands: Promise<unknown>[] = [
- clickhouse.command({
- query: `ALTER TABLE events DELETE WHERE pid = {pid:FixedString(12)} AND type IN ({types:Array(String)}) ${dateCondition} ${filtersQuery}`,
- query_params: params,
- }),
- ]
+ const commands: Promise<unknown>[] = []
- // error_statuses carries no traffic columns, so it can only be cleared when
- // no field filters are applied (a full reset or a plain date-range reset).
- if (_includes(safeTypes, 'error') && _isEmpty(filtersQuery)) {
+ if (!_isEmpty(eventTableTypes)) {
commands.push(
clickhouse.command({
- query: `ALTER TABLE error_statuses DELETE WHERE pid = {pid:FixedString(12)} ${
- hasRange ? 'AND created BETWEEN {from:String} AND {to:String}' : ''
- }`,
- query_params: hasRange ? { pid, from, to } : { pid },
+ query: `ALTER TABLE events DELETE WHERE pid = {pid:FixedString(12)} AND type IN ({types:Array(String)}) ${dateRange.condition} ${filtersQuery}`,
+ query_params: params,
+ clickhouse_settings: { mutations_sync: '2' },
}),
)
+
+ // error_statuses carries no traffic columns, so it can only be cleared
+ // when no field filters are applied (a full or plain date-range reset).
+ if (_includes(safeTypes, 'error') && _isEmpty(filtersQuery)) {
+ commands.push(
+ clickhouse.command({
+ query: `ALTER TABLE error_statuses DELETE WHERE pid = {pid:FixedString(12)} ${dateRange.condition}`,
+ query_params: {
+ pid,
+ ...(from ? { from } : {}),
+ ...(to ? { to } : {}),
+ },
+ clickhouse_settings: { mutations_sync: '2' },
+ }),
+ )
+ }
}
await Promise.all(commands)
@@ -6606,6 +6813,7 @@ export class AnalyticsService {
psid,
chart: chartData,
timeBucket,
+ replay: await this.getSessionReplaySummary(pid, psid),
}
}
@@ -6671,6 +6879,20 @@ export class AnalyticsService {
AND created BETWEEN {groupFrom:String} AND {groupTo:String}
GROUP BY psidCasted, pid
),
+ replay_summary AS (
+ SELECT
+ toString(ifNull(psid, 0)) AS psidCasted,
+ pid,
+ countDistinct(replayId) AS replayCount,
+ min(firstEventTimestamp) AS firstReplayTimestamp,
+ max(lastEventTimestamp) AS lastReplayTimestamp,
+ max(expiresAt) AS replayExpiresAt
+ FROM session_replay_chunks
+ WHERE pid = {pid:FixedString(12)}
+ AND psid != 0
+ AND expiresAt > now()
+ GROUP BY psidCasted, pid
+ ),
session_duration_agg AS (
SELECT
psidCasted,
@@ -6716,12 +6938,26 @@ export class AnalyticsService {
dsf.sessionStart AS sessionStart,
dsf.lastActivity AS lastActivity,
sda.total_duration AS sdur,
- coalesce(nullIf(sda.profileId, ''), dsf.profileId) AS profileId
+ coalesce(nullIf(sda.profileId, ''), dsf.profileId) AS profileId,
+ COALESCE(rs.replayCount, 0) AS replayCount,
+ if(
+ COALESCE(rs.replayCount, 0) = 0,
+ NULL,
+ if(
+ isNull(rs.firstReplayTimestamp)
+ OR isNull(rs.lastReplayTimestamp)
+ OR rs.lastReplayTimestamp <= rs.firstReplayTimestamp,
+ ifNull(sda.total_duration, 0),
+ intDiv(rs.lastReplayTimestamp - rs.firstReplayTimestamp, 1000)
+ )
+ ) AS replayDuration,
+ rs.replayExpiresAt AS replayExpiresAt
FROM distinct_sessions_filtered dsf
LEFT JOIN pageview_counts pc ON dsf.psidCasted = pc.psidCasted AND dsf.pid = pc.pid
LEFT JOIN event_counts ec ON dsf.psidCasted = ec.psidCasted AND dsf.pid = ec.pid
LEFT JOIN error_counts errc ON dsf.psidCasted = errc.psidCasted AND dsf.pid = errc.pid
LEFT JOIN session_duration_agg sda ON dsf.psidCasted = sda.psidCasted AND dsf.pid = sda.pid
+ LEFT JOIN replay_summary rs ON dsf.psidCasted = rs.psidCasted AND dsf.pid = rs.pid
)
SELECT
se.psidCasted AS psid,
@@ -6741,7 +6977,10 @@ export class AnalyticsService {
ifNull(se.profileId, '') = '',
0,
if(isNull(fsp.firstPsid) OR fsp.firstPsid = '' OR fsp.firstPsid = se.psidCasted, 1, 0)
- ) AS isFirstSession
+ ) AS isFirstSession,
+ if(se.replayCount > 0, 1, 0) AS hasReplay,
+ se.replayDuration,
+ se.replayExpiresAt
FROM sessions_enriched se
LEFT JOIN first_session_per_profile fsp ON se.profileId = fsp.profileId
WHERE se.psidCasted IS NOT NULL
@@ -6770,6 +7009,7 @@ export class AnalyticsService {
customEVFilterApplied: boolean,
sessionEvent: SessionsListEventType = 'traffic',
primaryEventFilterQuery = '',
+ includeProfileMatchedEventsWithPsid = false,
): string {
if (customEVFilterApplied || sessionEvent === 'custom_event') {
return `
@@ -6801,12 +7041,12 @@ export class AnalyticsService {
toTimeZone(matching_custom_events.created, {timezone:String}) AS created_for_grouping
FROM sessions AS s FINAL
INNER JOIN (
- SELECT pid, profileId, cc, os, br, created
+ SELECT pid, psid, profileId, cc, os, br, created
FROM events
WHERE
pid = {pid:FixedString(12)}
AND type = 'custom_event'
- AND (psid IS NULL OR psid = 0)
+ ${includeProfileMatchedEventsWithPsid ? '' : 'AND (psid IS NULL OR psid = 0)'}
AND profileId IS NOT NULL
AND profileId != ''
AND created BETWEEN {groupFrom:String} AND {groupTo:String}
@@ -6815,6 +7055,7 @@ export class AnalyticsService {
) AS matching_custom_events
ON s.pid = matching_custom_events.pid
AND s.profileId = matching_custom_events.profileId
+ AND (matching_custom_events.psid IS NULL OR matching_custom_events.psid = 0 OR matching_custom_events.psid = s.psid)
WHERE matching_custom_events.created BETWEEN s.firstSeen AND addSeconds(s.lastSeen, 1)
`
}
@@ -8282,4 +8523,1069 @@ export class AnalyticsService {
pages: pageflows.get(String(session.psid)) || [],
}))
}
+
+ private buildSessionReplayDeletionWhere(
+ filtersQuery: string,
+ dateCondition: string,
+ ): string {
+ const psidFilter = _isEmpty(filtersQuery)
+ ? ''
+ : `AND psid IN (SELECT DISTINCT psid FROM events WHERE pid = {pid:FixedString(12)} ${dateCondition} ${filtersQuery})`
+
+ return `pid = {pid:FixedString(12)} ${dateCondition} ${psidFilter}`
+ }
+
+ private buildSessionReplayDeletionParams(
+ pid: string,
+ filtersParams: Record<string, unknown>,
+ from: string | null,
+ to: string | null,
+ ): Record<string, unknown> {
+ return {
+ pid,
+ groupFrom: from || DELETION_MIN_DATE,
+ groupTo: to || DELETION_MAX_DATE,
+ ...filtersParams,
+ ...(from ? { from } : {}),
+ ...(to ? { to } : {}),
+ }
+ }
+
+ private async countMatchingSessionReplays(
+ pid: string,
+ filtersQuery: string,
+ filtersParams: Record<string, unknown>,
+ from: string | null,
+ to: string | null,
+ dateCondition: string,
+ ): Promise<number> {
+ if (!this.sessionReplayStorage.isConfigured()) {
+ return 0
+ }
+
+ const where = this.buildSessionReplayDeletionWhere(
+ filtersQuery,
+ dateCondition,
+ )
+
+ const { data } = await clickhouse
+ .query({
+ query: `SELECT count(DISTINCT replayId) AS c FROM session_replay_chunks WHERE ${where}`,
+ query_params: this.buildSessionReplayDeletionParams(
+ pid,
+ filtersParams,
+ from,
+ to,
+ ),
+ })
+ .then((resultSet) => resultSet.json<{ c: string }>())
+
+ return Number(data[0]?.c) || 0
+ }
+
+ private async deleteMatchingSessionReplays(
+ pid: string,
+ filtersQuery: string,
+ filtersParams: Record<string, unknown>,
+ from: string | null,
+ to: string | null,
+ dateCondition: string,
+ ): Promise<void> {
+ const where = this.buildSessionReplayDeletionWhere(
+ filtersQuery,
+ dateCondition,
+ )
+ const params = this.buildSessionReplayDeletionParams(
+ pid,
+ filtersParams,
+ from,
+ to,
+ )
+
+ const { data: chunks } = await clickhouse
+ .query({
+ query: `SELECT DISTINCT objectKey FROM session_replay_chunks WHERE ${where}`,
+ query_params: params,
+ })
+ .then((resultSet) => resultSet.json<{ objectKey: string }>())
+
+ const objectKeys = chunks.map((chunk) => chunk.objectKey).filter(Boolean)
+
+ if (objectKeys.length && !this.sessionReplayStorage.isConfigured()) {
+ throw new InternalServerErrorException(
+ 'Session replay storage is not configured',
+ )
+ }
+
+ await mapLimit(objectKeys, SESSION_REPLAY_CHUNK_FETCH_CONCURRENCY, (key) =>
+ this.sessionReplayStorage.deleteObject(key),
+ )
+
+ await clickhouse.command({
+ query: `ALTER TABLE session_replay_chunks DELETE WHERE ${where}`,
+ query_params: params,
+ clickhouse_settings: { mutations_sync: '2' },
+ })
+ }
+
+ isValidSessionReplayRetentionDays(
+ value: number,
+ ): value is 30 | 90 | 365 | 1825 {
+ return SESSION_REPLAY_RETENTION_VALUES.includes(value as any)
+ }
+
+ private getSessionReplayRetention(project: Project): {
+ retentionDays: number
+ expiresAt: string
+ } {
+ const configuredRetentionDays = this.isValidSessionReplayRetentionDays(
+ project.sessionReplayRetentionDays,
+ )
+ ? project.sessionReplayRetentionDays
+ : 30
+ const retentionDays = configuredRetentionDays
+
+ return {
+ retentionDays,
+ expiresAt: dayjs
+ .utc()
+ .add(retentionDays, 'day')
+ .format('YYYY-MM-DD HH:mm:ss'),
+ }
+ }
+
+ private async resolveReplaySession(
+ pid: string,
+ userAgent: string,
+ ip: string,
+ ): Promise<{ psid: string; sid: string; isNewSession: boolean }> {
+ const [isNewSession, psid, sid] = await this.generateAndStoreSessionId(
+ pid,
+ userAgent,
+ ip,
+ )
+ return { psid, sid, isNewSession }
+ }
+
+ async startSessionReplay(
+ project: Project,
+ pid: string,
+ replayId: string,
+ privacy: SessionReplayPrivacyMode,
+ userAgent: string,
+ ip: string,
+ profileId?: string,
+ ) {
+ if (!this.sessionReplayStorage.isConfigured()) {
+ throw new InternalServerErrorException(
+ 'Session replay storage is not configured',
+ )
+ }
+
+ const { psid, sid, isNewSession } = await this.resolveReplaySession(
+ pid,
+ userAgent,
+ ip,
+ )
+ const resolvedProfileId = await this.generateProfileId(
+ pid,
+ userAgent,
+ ip,
+ profileId,
+ )
+
+ await this.recordSessionActivity(
+ sid,
+ psid,
+ pid,
+ resolvedProfileId,
+ isNewSession,
+ )
+
+ const retention = this.getSessionReplayRetention(project)
+ const replayStart = await this.reserveActiveReplayStart(pid, psid, replayId)
+
+ return {
+ replayId: replayStart.replayId,
+ nextChunkIndex: replayStart.nextChunkIndex,
+ psid,
+ privacy,
+ ...retention,
+ }
+ }
+
+ private getSessionReplayObjectKey(
+ pid: string,
+ psid: string,
+ replayId: string,
+ chunkIndex: number,
+ ): string {
+ const date = dayjs.utc()
+ return [
+ 'session-replays',
+ pid,
+ date.format('YYYY'),
+ date.format('MM'),
+ psid,
+ replayId,
+ `${chunkIndex}.json.gz`,
+ ].join('/')
+ }
+
+ private getActiveReplayKey(pid: string, psid: string) {
+ return `session-replay:active:${pid}:${psid}`
+ }
+
+ private getReplayLimitKeys(pid: string, psid: string, replayId: string) {
+ const prefix = `session-replay:limits:${pid}:${psid}:${replayId}`
+ return {
+ chunkSetKey: `${prefix}:chunks`,
+ countersKey: `${prefix}:counters`,
+ firstTsKey: `${prefix}:first`,
+ lastTsKey: `${prefix}:last`,
+ }
+ }
+
+ private getReplayLimitTtlSeconds(retention: { expiresAt: string }) {
+ return Math.max(
+ 60,
+ dayjs.utc(retention.expiresAt).diff(dayjs.utc(), 'second'),
+ )
+ }
+
+ 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(),
+ MAX_SESSION_REPLAY_DURATION_MS,
+ )
+ 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) =>
+ typeof event.timestamp === 'number' ? event.timestamp : null,
+ )
+ .filter((timestamp): timestamp is number => timestamp !== null)
+
+ return {
+ firstEventTimestamp: timestamps.length ? Math.min(...timestamps) : null,
+ lastEventTimestamp: timestamps.length ? Math.max(...timestamps) : null,
+ }
+ }
+
+ private async reserveReplayChunkStorage(
+ pid: string,
+ psid: string,
+ replayId: string,
+ chunkIndex: number,
+ eventCount: number,
+ uncompressedBytes: number,
+ retention: { expiresAt: string },
+ timestamps: {
+ firstEventTimestamp: number | null
+ lastEventTimestamp: number | null
+ },
+ ) {
+ const keys = this.getReplayLimitKeys(pid, psid, replayId)
+ const result = await redis.eval(
+ RESERVE_REPLAY_CHUNK_LUA,
+ 4,
+ keys.chunkSetKey,
+ keys.countersKey,
+ keys.firstTsKey,
+ keys.lastTsKey,
+ MAX_SESSION_REPLAY_CHUNKS_PER_REPLAY,
+ MAX_SESSION_REPLAY_EVENTS_PER_REPLAY,
+ MAX_SESSION_REPLAY_BYTES_PER_REPLAY,
+ MAX_SESSION_REPLAY_DURATION_MS,
+ chunkIndex,
+ eventCount,
+ uncompressedBytes,
+ timestamps.firstEventTimestamp ?? '',
+ timestamps.lastEventTimestamp ?? '',
+ this.getReplayLimitTtlSeconds(retention),
+ )
+
+ switch (Number(result)) {
+ case 1:
+ return {
+ ...keys,
+ chunkIndex,
+ eventCount,
+ uncompressedBytes,
+ duplicate: false,
+ }
+ case -1:
+ throw new PayloadTooLargeException('Session replay has too many chunks')
+ case -2:
+ throw new PayloadTooLargeException('Session replay has too many events')
+ case -3:
+ throw new PayloadTooLargeException('Session replay is too large')
+ case -4:
+ return {
+ ...keys,
+ chunkIndex,
+ eventCount,
+ uncompressedBytes,
+ duplicate: true,
+ }
+ case -5:
+ throw new PayloadTooLargeException('Session replay is too long')
+ default:
+ throw new InternalServerErrorException(
+ 'Unable to reserve session replay chunk',
+ )
+ }
+ }
+
+ private async releaseReplayChunkStorageReservation(reservation: {
+ chunkSetKey: string
+ countersKey: string
+ firstTsKey: string
+ lastTsKey: string
+ chunkIndex: number
+ eventCount: number
+ uncompressedBytes: number
+ }) {
+ await redis.eval(
+ RELEASE_REPLAY_CHUNK_LUA,
+ 4,
+ reservation.chunkSetKey,
+ reservation.countersKey,
+ reservation.firstTsKey,
+ reservation.lastTsKey,
+ reservation.chunkIndex,
+ reservation.eventCount,
+ reservation.uncompressedBytes,
+ )
+ }
+
+ private validateSessionReplayReadSize(replay: {
+ chunkCount: number
+ eventCount: number
+ uncompressedBytes: number
+ replayDuration: number
+ }) {
+ if (
+ replay.chunkCount > MAX_SESSION_REPLAY_CHUNKS_PER_REPLAY ||
+ replay.eventCount > MAX_SESSION_REPLAY_EVENTS_PER_REPLAY ||
+ replay.uncompressedBytes > MAX_SESSION_REPLAY_BYTES_PER_REPLAY ||
+ replay.replayDuration * 1000 > MAX_SESSION_REPLAY_DURATION_MS
+ ) {
+ throw new PayloadTooLargeException('Session replay is too large to load')
+ }
+ }
+
+ private validateSessionReplayEventSizes(events: Record<string, unknown>[]) {
+ const hasOversizedEvent = events.some((event) => {
+ try {
+ return (
+ Buffer.byteLength(JSON.stringify(event)) >
+ MAX_SESSION_REPLAY_EVENT_BYTES
+ )
+ } catch {
+ return true
+ }
+ })
+
+ if (hasOversizedEvent) {
+ throw new PayloadTooLargeException('Session replay event is too large')
+ }
+ }
+
+ async storeSessionReplayChunk(
+ project: Project,
+ pid: string,
+ replayId: string,
+ privacy: SessionReplayPrivacyMode,
+ chunkIndex: number,
+ events: Record<string, unknown>[],
+ userAgent: string,
+ ip: string,
+ ) {
+ if (!this.sessionReplayStorage.isConfigured()) {
+ throw new InternalServerErrorException(
+ 'Session replay storage is not configured',
+ )
+ }
+
+ if (events.length > MAX_SESSION_REPLAY_EVENTS_PER_CHUNK) {
+ throw new BadRequestException('Session replay chunk has too many events')
+ }
+
+ this.validateSessionReplayEventSizes(events)
+
+ const { psid } = await this.resolveReplaySession(pid, userAgent, ip)
+ const retention = this.getSessionReplayRetention(project)
+ const payload = JSON.stringify({ events })
+ const uncompressedBytes = Buffer.byteLength(payload)
+ const timestamps = this.getReplayChunkTimestamps(events)
+
+ if (uncompressedBytes > MAX_SESSION_REPLAY_CHUNK_BYTES) {
+ throw new PayloadTooLargeException('Session replay chunk is too large')
+ }
+
+ const chunkReservation = await this.reserveReplayChunkStorage(
+ pid,
+ psid,
+ replayId,
+ chunkIndex,
+ events.length,
+ uncompressedBytes,
+ retention,
+ timestamps,
+ )
+
+ if (chunkReservation.duplicate) {
+ return {
+ replayId,
+ psid,
+ chunkIndex,
+ eventCount: events.length,
+ ...retention,
+ countedUsage: false,
+ }
+ }
+
+ const objectKey = this.getSessionReplayObjectKey(
+ pid,
+ psid,
+ replayId,
+ chunkIndex,
+ )
+ const compressed = gzipSync(Buffer.from(payload))
+ try {
+ await this.sessionReplayStorage.putObject(objectKey, compressed)
+
+ await clickhouse.insert({
+ table: 'session_replay_chunks',
+ format: 'JSONEachRow',
+ values: [
+ {
+ pid,
+ psid,
+ replayId,
+ chunkIndex,
+ objectKey,
+ privacyMode: privacy,
+ eventCount: events.length,
+ uncompressedBytes,
+ compressedBytes: compressed.byteLength,
+ firstEventTimestamp: timestamps.firstEventTimestamp,
+ lastEventTimestamp: timestamps.lastEventTimestamp,
+ created: dayjs.utc().format('YYYY-MM-DD HH:mm:ss'),
+ expiresAt: retention.expiresAt,
+ },
+ ],
+ clickhouse_settings: { async_insert: 1, wait_for_async_insert: 1 },
+ })
+ } catch (reason) {
+ await Promise.allSettled([
+ this.releaseReplayChunkStorageReservation(chunkReservation),
+ this.sessionReplayStorage.deleteObject(objectKey),
+ ])
+ throw reason
+ }
+
+ return {
+ replayId,
+ psid,
+ chunkIndex,
+ eventCount: events.length,
+ ...retention,
+ countedUsage: false,
+ }
+ }
+
+ async getSessionReplaySummary(pid: string, psid: string, replayId?: string) {
+ const { data } = await clickhouse
+ .query({
+ query: `
+ SELECT
+ replayId,
+ argMax(privacyMode, latestCreated) AS privacyMode,
+ count() AS chunkCount,
+ sum(eventCount) AS eventCount,
+ sum(uncompressedBytes) AS uncompressedBytes,
+ min(firstEventTimestamp) AS firstEventTimestamp,
+ max(lastEventTimestamp) AS lastEventTimestamp,
+ max(chunkExpiresAt) AS replayExpiresAt,
+ max(latestCreated) AS lastCreated
+ FROM (
+ SELECT
+ replayId,
+ chunkIndex,
+ argMax(privacyMode, created) AS privacyMode,
+ argMax(eventCount, created) AS eventCount,
+ argMax(uncompressedBytes, created) AS uncompressedBytes,
+ argMax(firstEventTimestamp, created) AS firstEventTimestamp,
+ argMax(lastEventTimestamp, created) AS lastEventTimestamp,
+ argMax(expiresAt, created) AS chunkExpiresAt,
+ max(created) AS latestCreated
+ FROM session_replay_chunks
+ WHERE pid = {pid:FixedString(12)}
+ AND psid = toUInt64OrNull({psid:String})
+ ${replayId ? 'AND replayId = {replayId:String}' : ''}
+ AND expiresAt > now()
+ GROUP BY replayId, chunkIndex
+ )
+ GROUP BY replayId
+ ORDER BY lastCreated DESC
+ LIMIT 1
+ `,
+ query_params: { pid, psid, replayId: replayId || '' },
+ })
+ .then((resultSet) =>
+ resultSet.json<{
+ replayId: string
+ privacyMode: SessionReplayPrivacyMode
+ chunkCount: number
+ eventCount: number
+ uncompressedBytes: number
+ firstEventTimestamp: number | string | null
+ lastEventTimestamp: number | string | null
+ replayExpiresAt: string
+ }>(),
+ )
+
+ const replay = data[0]
+ if (!replay) {
+ return null
+ }
+
+ const first = Number(replay.firstEventTimestamp)
+ const last = Number(replay.lastEventTimestamp)
+ const duration =
+ Number.isFinite(first) && Number.isFinite(last) && last > first
+ ? Math.round((last - first) / 1000)
+ : await this.getSessionDurationFromClickHouse(psid, pid)
+
+ return {
+ hasReplay: true,
+ replayId: replay.replayId,
+ privacyMode: replay.privacyMode,
+ chunkCount: Number(replay.chunkCount) || 0,
+ eventCount: Number(replay.eventCount) || 0,
+ uncompressedBytes: Number(replay.uncompressedBytes) || 0,
+ replayDuration: duration || 0,
+ replayExpiresAt: replay.replayExpiresAt,
+ }
+ }
+
+ async getSessionReplay(
+ pid: string,
+ psid: string,
+ replayId?: string,
+ ): Promise<{
+ replay: Awaited<ReturnType<AnalyticsService['getSessionReplaySummary']>>
+ events: Record<string, unknown>[]
+ }> {
+ const replay = await this.getSessionReplaySummary(pid, psid, replayId)
+ const selectedReplayId = replay?.replayId
+
+ if (!selectedReplayId) {
+ return { replay: null, events: [] }
+ }
+
+ this.validateSessionReplayReadSize(replay)
+
+ const { data: chunks } = await clickhouse
+ .query({
+ query: `
+ SELECT
+ chunkIndex,
+ argMax(objectKey, created) AS objectKey
+ FROM session_replay_chunks
+ WHERE pid = {pid:FixedString(12)}
+ AND psid = toUInt64OrNull({psid:String})
+ AND replayId = {replayId:String}
+ AND expiresAt > now()
+ GROUP BY chunkIndex
+ ORDER BY chunkIndex ASC
+ `,
+ query_params: { pid, psid, replayId: selectedReplayId },
+ })
+ .then((resultSet) =>
+ resultSet.json<{ chunkIndex: number; objectKey: string }>(),
+ )
+
+ const chunkEvents = await mapLimit(
+ chunks,
+ SESSION_REPLAY_CHUNK_FETCH_CONCURRENCY,
+ async (chunk) => {
+ const compressed = await this.sessionReplayStorage.getObject(
+ chunk.objectKey,
+ )
+ if (!compressed) return []
+
+ const parsed = JSON.parse(gunzipSync(compressed).toString('utf8')) as {
+ events?: Record<string, unknown>[]
+ }
+
+ return Array.isArray(parsed.events) ? parsed.events : []
+ },
+ )
+
+ // Chunk index order is upload order, which can diverge from event time
+ // order (e.g. two tabs recording into the same replay). The replayer
+ // expects a monotonic timeline, so stable-sort by timestamp β€” the same
+ // normalisation the MP4 export applies.
+ const events = chunkEvents
+ .flat()
+ .sort((a, b) => (Number(a?.timestamp) || 0) - (Number(b?.timestamp) || 0))
+
+ return {
+ replay,
+ events,
+ }
+ }
+
+ async deleteSessionReplay(pid: string, psid: string, replayId?: string) {
+ if (!this.sessionReplayStorage.isConfigured()) {
+ throw new InternalServerErrorException(
+ 'Session replay storage is not configured',
+ )
+ }
+
+ const replay = await this.getSessionReplaySummary(pid, psid, replayId)
+ const selectedReplayId = replay?.replayId
+
+ if (!selectedReplayId) {
+ return { deleted: false, deletedChunks: 0 }
+ }
+
+ const { data: chunks } = await clickhouse
+ .query({
+ query: `
+ SELECT DISTINCT objectKey
+ FROM session_replay_chunks
+ WHERE pid = {pid:FixedString(12)}
+ AND psid = toUInt64OrNull({psid:String})
+ AND replayId = {replayId:String}
+ `,
+ query_params: { pid, psid, replayId: selectedReplayId },
+ })
+ .then((resultSet) => resultSet.json<{ objectKey: string }>())
+
+ const objectKeys = chunks.map((chunk) => chunk.objectKey).filter(Boolean)
+
+ await mapLimit(objectKeys, SESSION_REPLAY_CHUNK_FETCH_CONCURRENCY, (key) =>
+ this.sessionReplayStorage.deleteObject(key),
+ )
+
+ await clickhouse.command({
+ query: `
+ ALTER TABLE session_replay_chunks
+ DELETE WHERE pid = {pid:FixedString(12)}
+ AND psid = toUInt64OrNull({psid:String})
+ AND replayId = {replayId:String}
+ `,
+ query_params: { pid, psid, replayId: selectedReplayId },
+ clickhouse_settings: { mutations_sync: '2' },
+ })
+
+ return { deleted: true, deletedChunks: objectKeys.length }
+ }
+
+ async cleanupExpiredSessionReplays(
+ limit = SESSION_REPLAY_CLEANUP_BATCH_SIZE,
+ ): Promise<number> {
+ if (!this.sessionReplayStorage.isConfigured()) {
+ return 0
+ }
+
+ const { data } = await clickhouse
+ .query({
+ query: `
+ SELECT objectKey
+ FROM session_replay_chunks
+ WHERE expiresAt <= now()
+ LIMIT {limit:UInt32}
+ `,
+ query_params: { limit },
+ })
+ .then((resultSet) => resultSet.json<{ objectKey: string }>())
+
+ if (_isEmpty(data)) {
+ return 0
+ }
+
+ const objectKeys = data.map((row) => row.objectKey)
+
+ const deleteResults = await mapLimit(
+ objectKeys,
+ SESSION_REPLAY_CHUNK_FETCH_CONCURRENCY,
+ async (objectKey) => {
+ try {
+ await this.sessionReplayStorage.deleteObject(objectKey)
+ return true
+ } catch {
+ return false
+ }
+ },
+ )
+ const deletedObjectKeys = objectKeys.filter(
+ (_, index) => deleteResults[index],
+ )
+
+ if (_isEmpty(deletedObjectKeys)) {
+ return 0
+ }
+
+ await clickhouse.command({
+ query: `
+ ALTER TABLE session_replay_chunks
+ DELETE WHERE objectKey IN ({objectKeys:Array(String)})
+ `,
+ query_params: { objectKeys: deletedObjectKeys },
+ })
+
+ return deletedObjectKeys.length
+ }
+
+ async getSessionReplaysList(
+ filtersQuery: string,
+ paramsData: any,
+ safeTimezone: string,
+ take = 30,
+ skip = 0,
+ customEVFilterApplied = false,
+ ): Promise<object[]> {
+ const primaryEventsSubquery = this.buildSessionsListPrimaryEventsSubquery(
+ filtersQuery,
+ customEVFilterApplied,
+ 'traffic',
+ '',
+ true,
+ )
+
+ const filteredSessionsCTE =
+ _isEmpty(filtersQuery) && !customEVFilterApplied
+ ? `
+ filtered_sessions AS (
+ SELECT
+ psidCasted,
+ pid,
+ argMaxIf(profileId, created_for_grouping, profileId IS NOT NULL AND profileId != '') AS profileId,
+ any(cc) AS cc,
+ any(os) AS os,
+ any(br) AS br,
+ min(created_for_grouping) AS sessionStart,
+ max(created_for_grouping) AS lastActivity
+ FROM (${primaryEventsSubquery}) AS primary_events
+ GROUP BY psidCasted, pid
+ )`
+ : `
+ matched_sessions AS (
+ SELECT DISTINCT psidCasted, pid
+ FROM (${primaryEventsSubquery}) AS primary_events
+ WHERE psidCasted != '0'
+ ),
+ filtered_sessions AS (
+ SELECT
+ ms.psidCasted AS psidCasted,
+ ms.pid AS pid,
+ argMaxIf(e.profileId, toTimeZone(e.created, {timezone:String}), e.profileId IS NOT NULL AND e.profileId != '') AS profileId,
+ anyIf(e.cc, e.psid IS NOT NULL AND e.psid != 0) AS cc,
+ anyIf(e.os, e.psid IS NOT NULL AND e.psid != 0) AS os,
+ anyIf(e.br, e.psid IS NOT NULL AND e.psid != 0) AS br,
+ minOrNull(if(e.psid IS NOT NULL AND e.psid != 0, toTimeZone(e.created, {timezone:String}), NULL)) AS sessionStart,
+ maxOrNull(if(e.psid IS NOT NULL AND e.psid != 0, toTimeZone(e.created, {timezone:String}), NULL)) AS lastActivity
+ FROM matched_sessions ms
+ LEFT JOIN events e ON toString(ifNull(e.psid, 0)) = ms.psidCasted
+ AND e.pid = ms.pid
+ AND e.type IN ('pageview', 'custom_event', 'error')
+ AND e.psid IS NOT NULL
+ AND e.psid != 0
+ AND e.created BETWEEN {groupFrom:String} AND {groupTo:String}
+ WHERE ms.pid = {pid:FixedString(12)}
+ GROUP BY ms.psidCasted, ms.pid
+ )`
+
+ const query = `
+ WITH ${this.buildProfileAliasMapCTE()},
+ ${filteredSessionsCTE},
+ replay_summary AS (
+ SELECT
+ psidCasted,
+ pid,
+ replayId,
+ argMax(privacyMode, latestCreated) AS privacyMode,
+ count() AS chunkCount,
+ sum(eventCount) AS eventCount,
+ min(firstEventTimestamp) AS firstEventTimestamp,
+ max(lastEventTimestamp) AS lastEventTimestamp,
+ min(latestCreated) AS replayCreatedAt,
+ max(latestCreated) AS lastReplayCreatedAt,
+ max(chunkExpiresAt) AS replayExpiresAt
+ FROM (
+ SELECT
+ toString(ifNull(psid, 0)) AS psidCasted,
+ pid,
+ replayId,
+ chunkIndex,
+ argMax(privacyMode, created) AS privacyMode,
+ argMax(eventCount, created) AS eventCount,
+ argMax(firstEventTimestamp, created) AS firstEventTimestamp,
+ argMax(lastEventTimestamp, created) AS lastEventTimestamp,
+ argMax(expiresAt, created) AS chunkExpiresAt,
+ max(created) AS latestCreated
+ FROM session_replay_chunks
+ WHERE pid = {pid:FixedString(12)}
+ AND psid != 0
+ AND expiresAt > now()
+ AND created BETWEEN {groupFrom:String} AND {groupTo:String}
+ GROUP BY psidCasted, pid, replayId, chunkIndex
+ )
+ GROUP BY psidCasted, pid, replayId
+ ),
+ pageview_counts AS (
+ SELECT
+ toString(ifNull(psid, 0)) AS psidCasted,
+ pid,
+ count() as count
+ FROM events
+ WHERE pid = {pid:FixedString(12)} AND type = 'pageview' AND psid IS NOT NULL
+ AND psid != 0
+ AND created BETWEEN {groupFrom:String} AND {groupTo:String}
+ GROUP BY psidCasted, pid
+ ),
+ event_counts AS (
+ SELECT
+ toString(ifNull(psid, 0)) AS psidCasted,
+ pid,
+ count() as count
+ FROM events
+ WHERE pid = {pid:FixedString(12)} AND type = 'custom_event' AND psid IS NOT NULL
+ AND psid != 0
+ AND created BETWEEN {groupFrom:String} AND {groupTo:String}
+ GROUP BY psidCasted, pid
+ ),
+ error_counts AS (
+ SELECT
+ toString(ifNull(psid, 0)) AS psidCasted,
+ pid,
+ count() as count
+ FROM events
+ WHERE pid = {pid:FixedString(12)} AND type = 'error' AND psid IS NOT NULL
+ AND psid != 0
+ AND created BETWEEN {groupFrom:String} AND {groupTo:String}
+ GROUP BY psidCasted, pid
+ ),
+ session_duration_agg AS (
+ SELECT
+ psidCasted,
+ pid,
+ sum(session_duration) as total_duration,
+ argMax(sessionProfileId, lastActivity) as profileId
+ FROM (
+ SELECT
+ toString(psid) AS psidCasted,
+ pid,
+ sid,
+ dateDiff('second', min(firstSeen), max(lastSeen)) as session_duration,
+ max(lastSeen) as lastActivity,
+ argMax(coalesce(nullIf(pam.userProfileId, ''), s.profileId), lastSeen) as sessionProfileId
+ FROM sessions AS s
+ LEFT JOIN profile_alias_map pam ON s.profileId = pam.anonProfileId
+ WHERE pid = {pid:FixedString(12)}
+ GROUP BY psidCasted, pid, sid
+ )
+ GROUP BY psidCasted, pid
+ ),
+ replays_enriched AS (
+ SELECT
+ rs.psidCasted AS psidCasted,
+ rs.pid AS pid,
+ rs.replayId AS replayId,
+ rs.privacyMode AS privacyMode,
+ rs.chunkCount AS chunkCount,
+ rs.eventCount AS eventCount,
+ rs.firstEventTimestamp AS firstEventTimestamp,
+ rs.lastEventTimestamp AS lastEventTimestamp,
+ rs.replayCreatedAt AS replayCreatedAt,
+ rs.lastReplayCreatedAt AS lastReplayCreatedAt,
+ rs.replayExpiresAt AS replayExpiresAt,
+ fs.cc AS cc,
+ fs.os AS os,
+ fs.br AS br,
+ COALESCE(pc.count, 0) AS pageviews,
+ COALESCE(ec.count, 0) AS customEvents,
+ COALESCE(errc.count, 0) AS errors,
+ fs.sessionStart AS sessionStart,
+ fs.lastActivity AS lastActivity,
+ sda.total_duration AS sdur,
+ coalesce(nullIf(sda.profileId, ''), fs.profileId) AS profileId
+ FROM replay_summary rs
+ INNER JOIN filtered_sessions fs ON rs.psidCasted = fs.psidCasted AND rs.pid = fs.pid
+ LEFT JOIN pageview_counts pc ON rs.psidCasted = pc.psidCasted AND rs.pid = pc.pid
+ LEFT JOIN event_counts ec ON rs.psidCasted = ec.psidCasted AND rs.pid = ec.pid
+ LEFT JOIN error_counts errc ON rs.psidCasted = errc.psidCasted AND rs.pid = errc.pid
+ LEFT JOIN session_duration_agg sda ON rs.psidCasted = sda.psidCasted AND rs.pid = sda.pid
+ ),
+ first_session_per_profile AS (
+ SELECT
+ coalesce(nullIf(pam.userProfileId, ''), s.profileId) AS profileId,
+ argMin(toString(psid), firstSeen) AS firstPsid
+ FROM sessions AS s FINAL
+ LEFT JOIN profile_alias_map pam ON s.profileId = pam.anonProfileId
+ WHERE pid = {pid:FixedString(12)}
+ AND s.profileId IS NOT NULL
+ AND s.profileId != ''
+ GROUP BY profileId
+ )
+ SELECT
+ re.psidCasted AS psid,
+ re.replayId,
+ re.privacyMode,
+ re.chunkCount,
+ re.eventCount,
+ re.firstEventTimestamp,
+ re.lastEventTimestamp,
+ re.replayCreatedAt,
+ re.lastReplayCreatedAt,
+ re.replayExpiresAt,
+ re.cc,
+ re.os,
+ re.br,
+ re.pageviews,
+ re.customEvents,
+ re.errors,
+ re.sessionStart,
+ re.lastActivity,
+ if(dateDiff('second', re.lastActivity, now()) < ${LIVE_SESSION_THRESHOLD_SECONDS}, 1, 0) AS isLive,
+ re.sdur,
+ re.profileId AS profileId,
+ if(startsWith(ifNull(re.profileId, ''), '${AnalyticsService.PROFILE_PREFIX_USER}'), 1, 0) AS isIdentified,
+ if(
+ ifNull(re.profileId, '') = '',
+ 0,
+ if(isNull(fsp.firstPsid) OR fsp.firstPsid = '' OR fsp.firstPsid = re.psidCasted, 1, 0)
+ ) AS isFirstSession
+ FROM replays_enriched re
+ LEFT JOIN first_session_per_profile fsp ON re.profileId = fsp.profileId
+ ORDER BY re.lastReplayCreatedAt DESC, re.replayId DESC
+ LIMIT {take:UInt32}
+ OFFSET {skip:UInt32}
+ `
+
+ const { data } = await clickhouse
+ .query({
+ query,
+ query_params: {
+ ...paramsData.params,
+ timezone: safeTimezone,
+ take,
+ skip,
+ },
+ })
+ .then((resultSet) => resultSet.json<any>())
+
+ return data.map((row: any) => {
+ const firstTimestamp =
+ row.firstEventTimestamp === null ||
+ typeof row.firstEventTimestamp === 'undefined'
+ ? Number.NaN
+ : Number(row.firstEventTimestamp)
+ const lastTimestamp =
+ row.lastEventTimestamp === null ||
+ typeof row.lastEventTimestamp === 'undefined'
+ ? Number.NaN
+ : Number(row.lastEventTimestamp)
+ const sessionDuration = Number(row.sdur) || 0
+ const replayDuration =
+ Number.isFinite(firstTimestamp) &&
+ Number.isFinite(lastTimestamp) &&
+ lastTimestamp > firstTimestamp
+ ? Math.round((lastTimestamp - firstTimestamp) / 1000)
+ : sessionDuration
+
+ return {
+ ...row,
+ hasReplay: 1,
+ chunkCount: Number(row.chunkCount) || 0,
+ eventCount: Number(row.eventCount) || 0,
+ replayDuration,
+ replayStart:
+ Number.isFinite(firstTimestamp) && firstTimestamp > 0
+ ? dayjs.utc(firstTimestamp).format('YYYY-MM-DD HH:mm:ss')
+ : row.replayCreatedAt,
+ }
+ })
+ }
+
+ private getDataDeletionDateRange(from: string | null, to: string | null) {
+ const normalizedFrom = from
+ ? dayjs.utc(from).format('YYYY-MM-DD HH:mm:ss')
+ : null
+ const normalizedTo = to ? dayjs.utc(to).format('YYYY-MM-DD HH:mm:ss') : null
+ const conditions: string[] = []
+
+ if (normalizedFrom) {
+ conditions.push('created >= {from:String}')
+ }
+ if (normalizedTo) {
+ conditions.push('created <= {to:String}')
+ }
+
+ return {
+ from: normalizedFrom,
+ to: normalizedTo,
+ condition: conditions.length ? `AND ${conditions.join(' AND ')}` : '',
+ }
+ }
+
+ async getSessionDurationFromClickHouse(
+ psid: string,
+ pid: string,
+ ): Promise<number | null> {
+ try {
+ const query = `
+ SELECT max(duration) as duration
+ FROM (
+ SELECT dateDiff('second', min(firstSeen), max(lastSeen)) as duration
+ FROM sessions
+ WHERE psid = {psid:UInt64}
+ AND pid = {pid:FixedString(12)}
+ GROUP BY sid
+ )
+ `
+
+ const { data } = await clickhouse
+ .query({
+ query,
+ query_params: { psid, pid },
+ })
+ .then((resultSet) => resultSet.json<{ duration: number }>())
+
+ return data[0]?.duration ?? null
+ } catch (error) {
+ console.error('Failed to get session duration:', error)
+ return null
+ }
+ }
}
diff --git a/backend/apps/community/src/analytics/bot-detection.service.ts b/backend/apps/community/src/analytics/bot-detection.service.ts
index 510e0bfbd..023ea6905 100644
--- a/backend/apps/community/src/analytics/bot-detection.service.ts
+++ b/backend/apps/community/src/analytics/bot-detection.service.ts
@@ -25,6 +25,7 @@ export type BotEndpoint =
| 'heartbeat'
| 'identify'
| 'noscript'
+ | 'session_replay'
interface BotDetectionInput {
pid: string
diff --git a/backend/apps/community/src/analytics/dto/data-deletion.dto.ts b/backend/apps/community/src/analytics/dto/data-deletion.dto.ts
index 333743729..2ae16ca5f 100644
--- a/backend/apps/community/src/analytics/dto/data-deletion.dto.ts
+++ b/backend/apps/community/src/analytics/dto/data-deletion.dto.ts
@@ -17,6 +17,7 @@ export const DATA_DELETION_EVENT_TYPES = [
'error',
'performance',
'captcha',
+ 'session_replay',
] as const
export type DataDeletionEventType = (typeof DATA_DELETION_EVENT_TYPES)[number]
@@ -64,7 +65,7 @@ export class DataDeletionDto {
type: [String],
enum: DATA_DELETION_EVENT_TYPES,
description:
- "Event types to delete. Any of: 'pageview', 'custom_event', 'error', 'performance', 'captcha'.",
+ "Event types to delete. Any of: 'pageview', 'custom_event', 'error', 'performance', 'captcha', 'session_replay'.",
})
@IsOptional()
@IsArray()
diff --git a/backend/apps/community/src/analytics/dto/session-replay.dto.ts b/backend/apps/community/src/analytics/dto/session-replay.dto.ts
new file mode 100644
index 000000000..a404e26fd
--- /dev/null
+++ b/backend/apps/community/src/analytics/dto/session-replay.dto.ts
@@ -0,0 +1,118 @@
+import { ApiProperty, PickType } from '@nestjs/swagger'
+import {
+ ArrayMaxSize,
+ IsArray,
+ IsIn,
+ IsInt,
+ IsNotEmpty,
+ IsObject,
+ IsOptional,
+ IsString,
+ Matches,
+ Max,
+ MaxLength,
+ Min,
+} from 'class-validator'
+import { Type } from 'class-transformer'
+
+import { PID_REGEX } from '../../common/constants'
+import { GetDataDto } from './getData.dto'
+
+const SESSION_REPLAY_PRIVACY_MODES = ['total', 'normal', 'none'] as const
+
+export type SessionReplayPrivacyMode =
+ (typeof SESSION_REPLAY_PRIVACY_MODES)[number]
+
+export class SessionReplayStartDto {
+ @ApiProperty({ required: true, description: 'The project ID' })
+ @IsNotEmpty()
+ @Matches(PID_REGEX, { message: 'The provided Project ID (pid) is incorrect' })
+ pid: string
+
+ @ApiProperty({ required: true })
+ @IsString()
+ @IsNotEmpty()
+ @MaxLength(80)
+ @Matches(/^[a-zA-Z0-9_-]+$/)
+ replayId: string
+
+ @ApiProperty({ enum: SESSION_REPLAY_PRIVACY_MODES, default: 'total' })
+ @IsIn(SESSION_REPLAY_PRIVACY_MODES)
+ privacy: SessionReplayPrivacyMode
+
+ @IsOptional()
+ @IsString()
+ @MaxLength(2048)
+ pg?: string
+
+ @IsOptional()
+ @IsString()
+ @MaxLength(64)
+ lc?: string
+
+ @IsOptional()
+ @IsString()
+ @MaxLength(80)
+ tz?: string
+
+ @IsOptional()
+ @IsString()
+ @MaxLength(256)
+ profileId?: string
+}
+
+export class SessionReplayChunkDto extends SessionReplayStartDto {
+ @Type(() => Number)
+ @IsInt()
+ @Min(0)
+ @Max(4294967295)
+ chunkIndex: number
+
+ @IsArray()
+ @ArrayMaxSize(1000)
+ @IsObject({ each: true })
+ events: Record<string, unknown>[]
+}
+
+export class GetSessionReplayDto {
+ @ApiProperty({ required: true, description: 'The project ID' })
+ @IsNotEmpty()
+ @Matches(PID_REGEX, { message: 'The provided Project ID (pid) is incorrect' })
+ pid: string
+
+ @ApiProperty()
+ @IsNotEmpty()
+ psid: string
+
+ @ApiProperty({ required: false })
+ @IsOptional()
+ @IsString()
+ @IsNotEmpty()
+ @MaxLength(80)
+ @Matches(/^[a-zA-Z0-9_-]+$/)
+ replayId?: string
+}
+
+export class GetSessionReplaysDto extends PickType(GetDataDto, [
+ 'pid',
+ 'period',
+ 'from',
+ 'to',
+ 'filters',
+ 'timezone',
+] as const) {
+ @Type(() => Number)
+ @IsOptional()
+ @IsInt()
+ @Min(0)
+ @Max(150)
+ take?: number
+
+ @Type(() => Number)
+ @IsOptional()
+ @IsInt()
+ @Min(0)
+ skip?: number
+}
+
+export class SessionReplayExportStartDto extends GetSessionReplayDto {}
diff --git a/backend/apps/community/src/analytics/session-replay-export.processor.ts b/backend/apps/community/src/analytics/session-replay-export.processor.ts
new file mode 100644
index 000000000..b09258643
--- /dev/null
+++ b/backend/apps/community/src/analytics/session-replay-export.processor.ts
@@ -0,0 +1,32 @@
+import { Processor, WorkerHost } from '@nestjs/bullmq'
+import { Job } from 'bullmq'
+
+import {
+ SESSION_REPLAY_EXPORT_QUEUE,
+ SessionReplayExportJobData,
+ SessionReplayExportService,
+} from './session-replay-export.service'
+
+const concurrencyValue = Number(process.env.SESSION_REPLAY_EXPORT_CONCURRENCY)
+const concurrency =
+ Number.isFinite(concurrencyValue) && concurrencyValue > 0
+ ? Math.floor(concurrencyValue)
+ : 1
+
+@Processor(SESSION_REPLAY_EXPORT_QUEUE, { concurrency })
+export class SessionReplayExportProcessor extends WorkerHost {
+ constructor(
+ private readonly sessionReplayExportService: SessionReplayExportService,
+ ) {
+ super()
+ }
+
+ async process(job: Job<SessionReplayExportJobData>): Promise<void> {
+ if (job.data.type === 'cleanup') {
+ await this.sessionReplayExportService.cleanupExportJob(job.data)
+ return
+ }
+
+ await this.sessionReplayExportService.processExportJob(job.data)
+ }
+}
diff --git a/backend/apps/community/src/analytics/session-replay-export.service.ts b/backend/apps/community/src/analytics/session-replay-export.service.ts
new file mode 100644
index 000000000..6d980ab7a
--- /dev/null
+++ b/backend/apps/community/src/analytics/session-replay-export.service.ts
@@ -0,0 +1,902 @@
+import { spawn } from 'child_process'
+import { createHash, randomUUID } from 'crypto'
+import { createReadStream } from 'fs'
+import * as fs from 'fs/promises'
+import * as os from 'os'
+import * as path from 'path'
+import {
+ BadRequestException,
+ Injectable,
+ Logger,
+ NotFoundException,
+ PayloadTooLargeException,
+ ServiceUnavailableException,
+ StreamableFile,
+} from '@nestjs/common'
+import { InjectQueue } from '@nestjs/bullmq'
+import { Queue } from 'bullmq'
+import type { Response } from 'express'
+
+import { redis } from '../common/constants'
+import { hash } from '../common/utils'
+import { AnalyticsService } from './analytics.service'
+import { SessionReplayS3Service } from './session-replay-s3.service'
+
+export const SESSION_REPLAY_EXPORT_QUEUE = 'session-replay-export'
+
+type SessionReplayExportStatus =
+ | 'queued'
+ | 'processing'
+ | 'ready'
+ | 'failed'
+ | 'expired'
+
+export interface SessionReplayExportResponse {
+ exportId: string
+ status: SessionReplayExportStatus
+ progress: number
+ filename: string
+ expiresAt: string
+ error?: string
+}
+
+export type SessionReplayExportJobData =
+ | {
+ type: 'export'
+ exportId: string
+ pid: string
+ psid: string
+ replayId?: string
+ }
+ | {
+ type: 'cleanup'
+ exportId: string
+ expiresAt: string
+ }
+
+export interface SessionReplayExportState extends SessionReplayExportResponse {
+ pid: string
+ psid: string
+ replayId?: string
+ objectKey?: string
+ createdAt: string
+ updatedAt: string
+}
+
+type RrvideoEvent = Record<string, unknown> & {
+ type: number
+ timestamp: number
+ data: Record<string, unknown>
+}
+
+const DEFAULT_MAX_DURATION_MS = 30 * 60 * 1000
+const DEFAULT_MAX_EVENTS = 100000
+const DEFAULT_MAX_INPUT_BYTES = 150 * 1024 * 1024
+const DEFAULT_MAX_OUTPUT_BYTES = 500 * 1024 * 1024
+const DEFAULT_TTL_SECONDS = 24 * 60 * 60
+const DEFAULT_RENDER_TIMEOUT_MS = 60 * 60 * 1000
+const DEFAULT_VIEWPORT = { width: 1280, height: 720 }
+const TMP_DIR = path.resolve(os.tmpdir(), 'swetrix-session-replay-exports')
+const EXPORT_RENDERER_VERSION = 3
+const RRWEB_EVENT_TYPE_FULL_SNAPSHOT = 2
+const RRWEB_EVENT_TYPE_INCREMENTAL_SNAPSHOT = 3
+const RRWEB_EVENT_TYPE_META = 4
+const RRWEB_INCREMENTAL_SOURCE_VIEWPORT_RESIZE = 4
+
+const getPositiveEnvNumber = (key: string, fallback: number) => {
+ const value = Number(process.env[key])
+ return Number.isFinite(value) && value > 0 ? value : fallback
+}
+
+const getExportStateKey = (exportId: string) =>
+ `session-replay:export:${exportId}`
+
+@Injectable()
+export class SessionReplayExportService {
+ private readonly logger = new Logger(SessionReplayExportService.name)
+
+ private readonly maxDurationMs = getPositiveEnvNumber(
+ 'SESSION_REPLAY_EXPORT_MAX_DURATION_MS',
+ DEFAULT_MAX_DURATION_MS,
+ )
+
+ private readonly maxEvents = getPositiveEnvNumber(
+ 'SESSION_REPLAY_EXPORT_MAX_EVENTS',
+ DEFAULT_MAX_EVENTS,
+ )
+
+ private readonly maxInputBytes = getPositiveEnvNumber(
+ 'SESSION_REPLAY_EXPORT_MAX_INPUT_BYTES',
+ DEFAULT_MAX_INPUT_BYTES,
+ )
+
+ private readonly maxOutputBytes = getPositiveEnvNumber(
+ 'SESSION_REPLAY_EXPORT_MAX_OUTPUT_BYTES',
+ DEFAULT_MAX_OUTPUT_BYTES,
+ )
+
+ private readonly ttlSeconds = getPositiveEnvNumber(
+ 'SESSION_REPLAY_EXPORT_TTL_SECONDS',
+ DEFAULT_TTL_SECONDS,
+ )
+
+ private readonly renderTimeoutMs = getPositiveEnvNumber(
+ 'SESSION_REPLAY_EXPORT_RENDER_TIMEOUT_MS',
+ DEFAULT_RENDER_TIMEOUT_MS,
+ )
+
+ constructor(
+ private readonly analyticsService: AnalyticsService,
+ private readonly sessionReplayStorage: SessionReplayS3Service,
+ @InjectQueue(SESSION_REPLAY_EXPORT_QUEUE)
+ private readonly exportQueue: Queue<SessionReplayExportJobData>,
+ ) {}
+
+ async startExport(
+ pid: string,
+ psid: string,
+ replayId?: string,
+ ): Promise<SessionReplayExportResponse> {
+ if (!this.sessionReplayStorage.isConfigured()) {
+ throw new ServiceUnavailableException(
+ 'Session replay storage is not configured',
+ )
+ }
+
+ const replay = await this.analyticsService.getSessionReplaySummary(
+ pid,
+ psid,
+ replayId,
+ )
+
+ if (!replay?.hasReplay) {
+ throw new BadRequestException('Replay is no longer available')
+ }
+
+ this.validateReplayMetadata(replay.eventCount, replay.replayDuration)
+
+ const resolvedReplayId = replay.replayId || replayId
+ const exportReplayId = resolvedReplayId || 'session'
+ const exportId = hash(
+ `${EXPORT_RENDERER_VERSION}:${pid}:${psid}:${exportReplayId}:${replay.eventCount}:${replay.replayDuration}`,
+ )
+ const existing = await this.getState(exportId)
+
+ if (existing && !this.shouldStartNewExport(existing)) {
+ return this.toResponse(existing)
+ }
+
+ if (existing?.objectKey) {
+ await this.sessionReplayStorage
+ .deleteObject(existing.objectKey)
+ .catch((reason) =>
+ this.logger.warn(
+ `Failed to delete stale session replay export ${exportId}: ${
+ reason instanceof Error ? reason.message : String(reason)
+ }`,
+ ),
+ )
+ }
+
+ const now = new Date()
+ const state: SessionReplayExportState = {
+ exportId,
+ pid,
+ psid,
+ replayId: resolvedReplayId,
+ status: 'queued',
+ progress: 0,
+ filename: this.getFilename(psid),
+ expiresAt: new Date(now.getTime() + this.ttlSeconds * 1000).toISOString(),
+ createdAt: now.toISOString(),
+ updatedAt: now.toISOString(),
+ }
+
+ await this.saveState(state)
+
+ try {
+ await this.exportQueue.add(
+ 'export-session-replay',
+ {
+ type: 'export',
+ exportId,
+ pid,
+ psid,
+ replayId: resolvedReplayId,
+ },
+ {
+ jobId: exportId,
+ attempts: 1,
+ removeOnComplete: true,
+ removeOnFail: true,
+ },
+ )
+ } catch (reason) {
+ await this.markFailed(state, reason)
+ throw new ServiceUnavailableException('Failed to start export')
+ }
+
+ return this.toResponse(state)
+ }
+
+ async getExport(exportId: string): Promise<SessionReplayExportResponse> {
+ const state = await this.getState(exportId)
+ if (!state) {
+ throw new NotFoundException('Export not found')
+ }
+
+ if (this.isExpired(state) && state.status !== 'expired') {
+ await this.expireState(state)
+ return this.toResponse({
+ ...state,
+ status: 'expired',
+ objectKey: undefined,
+ })
+ }
+
+ return this.toResponse(state)
+ }
+
+ async downloadExport(
+ exportId: string,
+ response: Response,
+ ): Promise<StreamableFile> {
+ const state = await this.getState(exportId)
+
+ if (!state || this.isExpired(state) || state.status === 'expired') {
+ throw new NotFoundException('Export not found')
+ }
+
+ if (state.status !== 'ready' || !state.objectKey) {
+ throw new BadRequestException('Export is not ready')
+ }
+
+ const object = await this.sessionReplayStorage.getObjectStream(
+ state.objectKey,
+ )
+
+ if (!object) {
+ await this.markFailed(state, new Error('Export file is missing'))
+ throw new NotFoundException('Export file not found')
+ }
+
+ response.setHeader('Content-Type', object.contentType || 'video/mp4')
+ response.setHeader(
+ 'Content-Disposition',
+ `attachment; filename="${state.filename}"`,
+ )
+ response.setHeader('Cache-Control', 'private, no-store')
+ if (object.contentLength) {
+ response.setHeader('Content-Length', object.contentLength)
+ }
+
+ return new StreamableFile(object.body)
+ }
+
+ async assertExportAccess(
+ exportId: string,
+ ): Promise<SessionReplayExportState> {
+ const state = await this.getState(exportId)
+ if (!state) {
+ throw new NotFoundException('Export not found')
+ }
+ return state
+ }
+
+ async processExportJob(
+ data: Extract<SessionReplayExportJobData, { type: 'export' }>,
+ ) {
+ const existing = await this.getState(data.exportId)
+ const state =
+ existing ||
+ ({
+ exportId: data.exportId,
+ pid: data.pid,
+ psid: data.psid,
+ replayId: data.replayId,
+ status: 'queued',
+ progress: 0,
+ filename: this.getFilename(data.psid),
+ expiresAt: new Date(Date.now() + this.ttlSeconds * 1000).toISOString(),
+ createdAt: new Date().toISOString(),
+ updatedAt: new Date().toISOString(),
+ } satisfies SessionReplayExportState)
+
+ let workDir: string | null = null
+
+ try {
+ await this.updateState(state, { status: 'processing', progress: 5 })
+
+ const { replay, events } = await this.analyticsService.getSessionReplay(
+ data.pid,
+ data.psid,
+ data.replayId,
+ )
+
+ if (!replay?.hasReplay || !events.length) {
+ throw new Error('Replay is no longer available')
+ }
+
+ this.validateReplayMetadata(replay.eventCount, replay.replayDuration)
+ const exportEvents = this.prepareEventsForRrvideo(events)
+
+ const durationMs = this.getReplayDurationMs(
+ exportEvents,
+ replay.replayDuration,
+ )
+ this.validateReplayDuration(durationMs)
+
+ const serializedEvents = JSON.stringify(exportEvents)
+ const inputBytes = Buffer.byteLength(serializedEvents)
+
+ if (inputBytes > this.maxInputBytes) {
+ throw new Error('Replay is too large to export')
+ }
+
+ workDir = path.join(TMP_DIR, `${data.exportId}-${randomUUID()}`)
+ await fs.mkdir(workDir, { recursive: true, mode: 0o700 })
+
+ const inputPath = path.join(workDir, 'events.json')
+ const configPath = path.join(workDir, 'rrvideo.config.json')
+ const webmPath = path.join(workDir, 'replay.webm')
+ const mp4Path = path.join(workDir, 'replay.mp4')
+
+ await fs.writeFile(inputPath, serializedEvents, { mode: 0o600 })
+ await fs.writeFile(
+ configPath,
+ JSON.stringify(this.getRrvideoConfig(exportEvents)),
+ { mode: 0o600 },
+ )
+
+ await this.updateState(state, { status: 'processing', progress: 20 })
+
+ await this.runCommand(
+ this.getRrvideoBin(),
+ ['--input', inputPath, '--output', webmPath, '--config', configPath],
+ {
+ cwd: workDir,
+ rejectOutput: /Error initializing replayer|Failed to transform/i,
+ },
+ )
+
+ await this.updateState(state, { status: 'processing', progress: 70 })
+
+ await this.runCommand(
+ this.getFfmpegBin(),
+ [
+ '-y',
+ '-i',
+ webmPath,
+ '-c:v',
+ 'libx264',
+ '-pix_fmt',
+ 'yuv420p',
+ '-movflags',
+ '+faststart',
+ mp4Path,
+ ],
+ { cwd: workDir },
+ )
+
+ const outputStat = await fs.stat(mp4Path)
+ if (outputStat.size > this.maxOutputBytes) {
+ throw new Error('Replay export is too large to download')
+ }
+
+ await this.updateState(state, { status: 'processing', progress: 90 })
+
+ const objectKey = this.getObjectKey(data.pid, data.psid, data.exportId)
+ const outputHash = await this.hashFile(mp4Path)
+ await this.sessionReplayStorage.putObject(
+ objectKey,
+ createReadStream(mp4Path),
+ 'video/mp4',
+ {
+ contentLength: outputStat.size,
+ payloadHash: outputHash,
+ },
+ )
+
+ await this.updateState(state, {
+ status: 'ready',
+ progress: 100,
+ objectKey,
+ error: undefined,
+ })
+
+ try {
+ await this.exportQueue.add(
+ 'cleanup-session-replay-export',
+ {
+ type: 'cleanup',
+ exportId: data.exportId,
+ expiresAt: state.expiresAt,
+ },
+ {
+ jobId: `${data.exportId}:cleanup:${hash(state.expiresAt)}`,
+ delay: this.ttlSeconds * 1000,
+ attempts: 3,
+ removeOnComplete: true,
+ removeOnFail: true,
+ },
+ )
+ } catch (reason) {
+ this.logger.warn(
+ `Failed to schedule session replay export cleanup ${data.exportId}: ${
+ reason instanceof Error ? reason.message : String(reason)
+ }`,
+ )
+ }
+ } catch (reason) {
+ await this.markFailed(state, reason)
+ throw reason
+ } finally {
+ if (workDir) {
+ await fs.rm(workDir, { recursive: true, force: true }).catch(() => null)
+ }
+ }
+ }
+
+ async cleanupExportJob(
+ data: Extract<SessionReplayExportJobData, { type: 'cleanup' }>,
+ ) {
+ const state = await this.getState(data.exportId)
+ if (!state) return
+
+ if (state.expiresAt !== data.expiresAt) return
+
+ if (state.objectKey) {
+ try {
+ await this.sessionReplayStorage.deleteObject(state.objectKey)
+ } catch (reason) {
+ this.logger.warn(
+ `Failed to delete session replay export ${data.exportId}: ${
+ reason instanceof Error ? reason.message : String(reason)
+ }`,
+ )
+ throw reason
+ }
+ }
+
+ await this.expireState(state)
+ }
+
+ private validateReplayMetadata(eventCount: number, durationSeconds: number) {
+ if (eventCount > this.maxEvents) {
+ throw new PayloadTooLargeException('Replay has too many events to export')
+ }
+
+ this.validateReplayDuration(durationSeconds * 1000)
+ }
+
+ private validateReplayDuration(durationMs: number) {
+ if (durationMs > this.maxDurationMs) {
+ throw new PayloadTooLargeException('Replay is too long to export')
+ }
+ }
+
+ private prepareEventsForRrvideo(events: Record<string, unknown>[]) {
+ const normalised: Array<{ event: RrvideoEvent; index: number }> = []
+
+ events.forEach((event, index) => {
+ const normalisedEvent = this.normaliseReplayEvent(event)
+ if (normalisedEvent) {
+ normalised.push({ event: normalisedEvent, index })
+ }
+ })
+
+ normalised.sort(
+ (a, b) => a.event.timestamp - b.event.timestamp || a.index - b.index,
+ )
+
+ if (!normalised.length) {
+ throw new Error('Replay is no longer available')
+ }
+
+ const prepared = normalised.map(({ event }) => event)
+ if (
+ !prepared.some((event) => event.type === RRWEB_EVENT_TYPE_FULL_SNAPSHOT)
+ ) {
+ throw new Error('Replay is missing a full snapshot')
+ }
+
+ const viewport = this.getReplayViewport(prepared)
+ const href = this.getReplayHref(prepared)
+ let hasMeta = false
+ const withMeta = prepared.map((event) => {
+ if (event.type !== RRWEB_EVENT_TYPE_META) return event
+
+ hasMeta = true
+ return {
+ ...event,
+ data: {
+ ...this.getEventData(event),
+ href,
+ width: viewport.width,
+ height: viewport.height,
+ },
+ }
+ })
+
+ if (!hasMeta) {
+ withMeta.unshift({
+ type: RRWEB_EVENT_TYPE_META,
+ timestamp: withMeta[0].timestamp,
+ data: {
+ href,
+ width: viewport.width,
+ height: viewport.height,
+ },
+ })
+ }
+
+ return withMeta
+ }
+
+ private normaliseReplayEvent(
+ event: Record<string, unknown>,
+ ): RrvideoEvent | null {
+ const timestamp = Number(event.timestamp)
+ const type = this.normaliseEventType(event.type)
+
+ if (!Number.isFinite(timestamp) || type === null) {
+ return null
+ }
+
+ return {
+ ...event,
+ type,
+ timestamp,
+ data: this.getEventData(event),
+ }
+ }
+
+ private normaliseEventType(value: unknown) {
+ const numeric = Number(value)
+ if (Number.isInteger(numeric)) return numeric
+
+ if (typeof value !== 'string') return null
+
+ const eventTypes: Record<string, number> = {
+ DomContentLoaded: 0,
+ Load: 1,
+ FullSnapshot: RRWEB_EVENT_TYPE_FULL_SNAPSHOT,
+ IncrementalSnapshot: RRWEB_EVENT_TYPE_INCREMENTAL_SNAPSHOT,
+ Meta: RRWEB_EVENT_TYPE_META,
+ Custom: 5,
+ Plugin: 6,
+ Asset: 7,
+ }
+
+ return eventTypes[value] ?? null
+ }
+
+ private getEventData(event: Record<string, unknown>) {
+ return event.data && typeof event.data === 'object'
+ ? (event.data as Record<string, unknown>)
+ : {}
+ }
+
+ private getReplayDurationMs(
+ events: Record<string, unknown>[],
+ fallbackDurationSeconds: number,
+ ) {
+ let minTimestamp = Infinity
+ let maxTimestamp = -Infinity
+
+ for (const event of events) {
+ const timestamp = Number(event.timestamp)
+ if (!Number.isFinite(timestamp)) continue
+
+ minTimestamp = Math.min(minTimestamp, timestamp)
+ maxTimestamp = Math.max(maxTimestamp, timestamp)
+ }
+
+ if (!Number.isFinite(minTimestamp) || !Number.isFinite(maxTimestamp)) {
+ return fallbackDurationSeconds * 1000
+ }
+
+ return Math.max(fallbackDurationSeconds * 1000, maxTimestamp - minTimestamp)
+ }
+
+ private getRrvideoConfig(events: Record<string, unknown>[]) {
+ const viewport = this.getReplayViewport(events)
+
+ return {
+ width: viewport.width,
+ height: viewport.height,
+ speed: 1,
+ skipInactive: false,
+ mouseTail: true,
+ }
+ }
+
+ private getReplayViewport(events: Record<string, unknown>[]) {
+ let maxWidth = 0
+ let maxHeight = 0
+
+ for (const event of events) {
+ const data = this.getEventData(event)
+ const isViewportEvent =
+ Number(event.type) === RRWEB_EVENT_TYPE_META ||
+ (Number(event.type) === RRWEB_EVENT_TYPE_INCREMENTAL_SNAPSHOT &&
+ Number(data.source) === RRWEB_INCREMENTAL_SOURCE_VIEWPORT_RESIZE)
+
+ if (!isViewportEvent) continue
+
+ const viewport = this.getViewportCandidate(data)
+ if (!viewport) continue
+
+ maxWidth = Math.max(maxWidth, viewport.width)
+ maxHeight = Math.max(maxHeight, viewport.height)
+ }
+
+ if (!maxWidth || !maxHeight) {
+ return DEFAULT_VIEWPORT
+ }
+
+ return this.clampViewport({ width: maxWidth, height: maxHeight })
+ }
+
+ private getViewportCandidate(data: Record<string, unknown>) {
+ const width = Number(data.width)
+ const height = Number(data.height)
+
+ if (
+ !Number.isFinite(width) ||
+ !Number.isFinite(height) ||
+ width <= 0 ||
+ height <= 0
+ ) {
+ return null
+ }
+
+ return {
+ width: Math.round(width),
+ height: Math.round(height),
+ }
+ }
+
+ private clampViewport(viewport: { width: number; height: number }) {
+ return {
+ width: Math.min(1920, Math.max(320, viewport.width)),
+ height: Math.min(1080, Math.max(240, viewport.height)),
+ }
+ }
+
+ private getReplayHref(events: Record<string, unknown>[]) {
+ for (const event of events) {
+ if (Number(event.type) !== RRWEB_EVENT_TYPE_META) continue
+
+ const href = this.getEventData(event).href
+ if (typeof href === 'string' && href) {
+ return this.getSafeReplayHref(href)
+ }
+ }
+
+ return 'about:blank'
+ }
+
+ private getSafeReplayHref(href: string) {
+ try {
+ const url = new URL(href)
+ if (url.protocol === 'https:' || url.protocol === 'http:') {
+ return url.toString()
+ }
+ } catch {
+ return 'about:blank'
+ }
+
+ return 'about:blank'
+ }
+
+ private async hashFile(filePath: string) {
+ const digest = createHash('sha256')
+ await new Promise<void>((resolve, reject) => {
+ const stream = createReadStream(filePath)
+ stream.on('data', (chunk) => digest.update(chunk))
+ stream.on('error', reject)
+ stream.on('end', resolve)
+ })
+
+ return digest.digest('hex')
+ }
+
+ private async runCommand(
+ command: string,
+ args: string[],
+ options: { cwd?: string; rejectOutput?: RegExp } = {},
+ ) {
+ await new Promise<void>((resolve, reject) => {
+ let settled = false
+ let output = ''
+ const child = spawn(command, args, {
+ cwd: options.cwd,
+ stdio: ['ignore', 'pipe', 'pipe'],
+ })
+ const timeout = setTimeout(() => {
+ if (settled) return
+ settled = true
+ child.kill('SIGKILL')
+ reject(new Error(`${path.basename(command)} timed out`))
+ }, this.renderTimeoutMs)
+
+ const captureOutput = (chunk: Buffer) => {
+ output = `${output}${chunk.toString()}`
+ if (output.length > 8000) {
+ output = output.slice(-8000)
+ }
+ }
+
+ child.stdout.on('data', captureOutput)
+ child.stderr.on('data', captureOutput)
+
+ child.on('error', (reason) => {
+ if (settled) return
+ settled = true
+ clearTimeout(timeout)
+ reject(reason)
+ })
+
+ child.on('close', (code) => {
+ if (settled) return
+ settled = true
+ clearTimeout(timeout)
+
+ if (code === 0) {
+ if (options.rejectOutput?.test(output)) {
+ reject(
+ new Error(
+ `${path.basename(command)} reported a renderer error: ${output}`,
+ ),
+ )
+ return
+ }
+
+ resolve()
+ return
+ }
+
+ reject(
+ new Error(
+ `${path.basename(command)} failed with status ${code}: ${output}`,
+ ),
+ )
+ })
+ })
+ }
+
+ private getRrvideoBin() {
+ return (
+ process.env.RRVIDEO_BIN ||
+ path.join(
+ process.cwd(),
+ 'node_modules',
+ '.bin',
+ process.platform === 'win32' ? 'rrvideo.cmd' : 'rrvideo',
+ )
+ )
+ }
+
+ private getFfmpegBin() {
+ return process.env.FFMPEG_BIN || 'ffmpeg'
+ }
+
+ private getObjectKey(pid: string, psid: string, exportId: string) {
+ return ['session-replay-exports', pid, psid, `${exportId}.mp4`].join('/')
+ }
+
+ private getFilename(psid: string) {
+ const safePsid = psid.replace(/[^a-zA-Z0-9_-]/g, '').slice(0, 80)
+ return `swetrix-replay-${safePsid || 'session'}.mp4`
+ }
+
+ private async getState(
+ exportId: string,
+ ): Promise<SessionReplayExportState | null> {
+ const raw = await redis.get(getExportStateKey(exportId))
+ if (!raw) return null
+
+ try {
+ return JSON.parse(raw) as SessionReplayExportState
+ } catch {
+ return null
+ }
+ }
+
+ private async saveState(state: SessionReplayExportState) {
+ await redis.set(
+ getExportStateKey(state.exportId),
+ JSON.stringify(state),
+ 'EX',
+ this.ttlSeconds + 24 * 60 * 60,
+ )
+ }
+
+ private async updateState(
+ state: SessionReplayExportState,
+ update: Partial<SessionReplayExportState>,
+ ) {
+ const next = {
+ ...state,
+ ...update,
+ updatedAt: new Date().toISOString(),
+ }
+ Object.assign(state, next)
+ await this.saveState(next)
+ return next
+ }
+
+ private async markFailed(state: SessionReplayExportState, reason: unknown) {
+ this.logger.error(
+ `Session replay export ${state.exportId} failed: ${this.getDetailedError(
+ reason,
+ )}`,
+ )
+
+ await this.updateState(state, {
+ status: 'failed',
+ progress: 100,
+ error: this.getPublicError(reason),
+ objectKey: undefined,
+ })
+ }
+
+ private async expireState(state: SessionReplayExportState) {
+ await this.updateState(state, {
+ status: 'expired',
+ progress: 100,
+ objectKey: undefined,
+ error: undefined,
+ })
+ }
+
+ private isExpired(state: SessionReplayExportState) {
+ return Date.parse(state.expiresAt) <= Date.now()
+ }
+
+ private shouldStartNewExport(state: SessionReplayExportState) {
+ return (
+ this.isExpired(state) ||
+ state.status === 'expired' ||
+ state.status === 'failed'
+ )
+ }
+
+ private getPublicError(reason: unknown) {
+ const message = this.getDetailedError(reason)
+
+ if (message.includes('Replay is no longer available')) {
+ return 'Replay is no longer available'
+ }
+
+ if (
+ message.includes('too large') ||
+ message.includes('too long') ||
+ message.includes('too many events')
+ ) {
+ return 'Replay is too large to export'
+ }
+
+ return 'Could not export replay to MP4'
+ }
+
+ private getDetailedError(reason: unknown) {
+ return reason instanceof Error
+ ? reason.stack || reason.message
+ : String(reason)
+ }
+
+ private toResponse(
+ state: SessionReplayExportState,
+ ): SessionReplayExportResponse {
+ return {
+ exportId: state.exportId,
+ status: state.status,
+ progress: state.progress,
+ filename: state.filename,
+ expiresAt: state.expiresAt,
+ ...(state.error ? { error: state.error } : {}),
+ }
+ }
+}
diff --git a/backend/apps/community/src/analytics/session-replay-s3.service.ts b/backend/apps/community/src/analytics/session-replay-s3.service.ts
new file mode 100644
index 000000000..daaece44a
--- /dev/null
+++ b/backend/apps/community/src/analytics/session-replay-s3.service.ts
@@ -0,0 +1,387 @@
+import crypto from 'crypto'
+import { Readable } from 'stream'
+import { Injectable } from '@nestjs/common'
+
+interface S3Config {
+ endpoint: string
+ bucket: string
+ region: string
+ forcePathStyle: boolean
+ accessKeyId: string
+ secretAccessKey: string
+}
+
+type HeaderMap = Record<string, string>
+type PutObjectBody = Buffer | Readable
+
+const SESSION_REPLAY_STORAGE_TIMEOUT_MS = 30_000
+// Hetzner object storage intermittently returns 503s; dropped replay chunks
+// are unrecoverable, so transient failures get a couple of retries.
+const SESSION_REPLAY_STORAGE_MAX_ATTEMPTS = 3
+const SESSION_REPLAY_STORAGE_RETRY_BASE_DELAY_MS = 300
+const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503, 504])
+
+const sleep = (ms: number) =>
+ new Promise<void>((resolve) => setTimeout(resolve, ms))
+
+const sha256Hex = (value: Buffer | string) =>
+ crypto.createHash('sha256').update(value).digest('hex')
+
+const hmac = (key: Buffer | string, value: string) =>
+ crypto.createHmac('sha256', key).update(value).digest()
+
+const encodeKeyPath = (key: string) =>
+ key.split('/').map(encodeURIComponent).join('/')
+
+const encodeQueryValue = (value: string) =>
+ encodeURIComponent(value).replace(
+ /[!'()*]/g,
+ (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`,
+ )
+
+const normalizeEndpoint = (endpoint: string) => {
+ const value = endpoint.trim().replace(/\/+$/, '')
+
+ return /^https?:\/\//.test(value) ? value : `https://${value}`
+}
+
+const inferHetznerRegion = (endpoint: string) => {
+ const suffix = '.your-objectstorage.com'
+ const hostname = new URL(endpoint).hostname
+
+ if (!hostname.endsWith(suffix)) {
+ return ''
+ }
+
+ return hostname.slice(0, -suffix.length).split('.')[0] || ''
+}
+
+const decodeXmlValue = (value: string) =>
+ value
+ .replace(/&lt;/g, '<')
+ .replace(/&gt;/g, '>')
+ .replace(/&quot;/g, '"')
+ .replace(/&apos;/g, "'")
+ .replace(/&amp;/g, '&')
+
+@Injectable()
+export class SessionReplayS3Service {
+ private getConfig(): S3Config | null {
+ const endpointValue =
+ process.env.SESSION_REPLAY_S3_ENDPOINT || process.env.HETZNER_S3_ENDPOINT
+ const endpoint = endpointValue ? normalizeEndpoint(endpointValue) : ''
+ const region =
+ process.env.SESSION_REPLAY_S3_REGION ||
+ (endpoint ? inferHetznerRegion(endpoint) : '') ||
+ 'us-east-1'
+ const forcePathStyle =
+ process.env.SESSION_REPLAY_S3_FORCE_PATH_STYLE === 'true'
+ const bucket =
+ process.env.SESSION_REPLAY_S3_BUCKET || process.env.HETZNER_S3_BUCKET
+ const accessKeyId =
+ process.env.SESSION_REPLAY_S3_ACCESS_KEY_ID ||
+ process.env.HETZNER_S3_ACCESS_KEY_ID
+ const secretAccessKey =
+ process.env.SESSION_REPLAY_S3_SECRET_ACCESS_KEY ||
+ process.env.HETZNER_S3_SECRET_ACCESS_KEY
+
+ if (!endpoint || !bucket || !region || !accessKeyId || !secretAccessKey) {
+ return null
+ }
+
+ return {
+ endpoint,
+ bucket,
+ region,
+ forcePathStyle,
+ accessKeyId,
+ secretAccessKey,
+ }
+ }
+
+ isConfigured(): boolean {
+ return Boolean(this.getConfig())
+ }
+
+ async putObject(
+ key: string,
+ body: PutObjectBody,
+ contentType = 'application/json',
+ options: { contentLength?: number; payloadHash?: string } = {},
+ ): Promise<void> {
+ const headers: HeaderMap = {
+ 'content-type': contentType,
+ }
+
+ if (typeof options.contentLength === 'number') {
+ headers['content-length'] = String(options.contentLength)
+ }
+
+ const response = await this.signedFetch(
+ 'PUT',
+ key,
+ body,
+ headers,
+ options.payloadHash,
+ )
+
+ if (!response.ok) {
+ throw new Error(`S3 PUT failed with status ${response.status}`)
+ }
+ }
+
+ async getObject(key: string): Promise<Buffer | null> {
+ const response = await this.signedFetch('GET', key)
+
+ if (response.status === 404) {
+ return null
+ }
+
+ if (!response.ok) {
+ throw new Error(`S3 GET failed with status ${response.status}`)
+ }
+
+ return Buffer.from(await response.arrayBuffer())
+ }
+
+ async getObjectStream(key: string): Promise<{
+ body: Readable
+ contentLength?: string
+ contentType?: string
+ } | null> {
+ const response = await this.signedFetch('GET', key)
+
+ if (response.status === 404) {
+ return null
+ }
+
+ if (!response.ok) {
+ throw new Error(`S3 GET failed with status ${response.status}`)
+ }
+
+ if (!response.body) {
+ return null
+ }
+
+ return {
+ body: Readable.fromWeb(response.body as any),
+ contentLength: response.headers.get('content-length') || undefined,
+ contentType: response.headers.get('content-type') || undefined,
+ }
+ }
+
+ async deleteObject(key: string): Promise<void> {
+ const response = await this.signedFetch('DELETE', key)
+
+ if (!response.ok && response.status !== 404) {
+ throw new Error(`S3 DELETE failed with status ${response.status}`)
+ }
+ }
+
+ async listObjects(prefix: string): Promise<string[]> {
+ const keys: string[] = []
+ let continuationToken: string | undefined
+
+ do {
+ const response = await this.signedFetch(
+ 'GET',
+ '',
+ undefined,
+ {},
+ undefined,
+ {
+ 'list-type': '2',
+ prefix,
+ 'max-keys': '1000',
+ 'continuation-token': continuationToken,
+ },
+ )
+
+ if (!response.ok) {
+ throw new Error(`S3 LIST failed with status ${response.status}`)
+ }
+
+ const xml = await response.text()
+ const keyRegex = /<Key>([\s\S]*?)<\/Key>/g
+ let keyMatch = keyRegex.exec(xml)
+
+ while (keyMatch) {
+ keys.push(decodeXmlValue(keyMatch[1]))
+ keyMatch = keyRegex.exec(xml)
+ }
+
+ continuationToken = xml.match(
+ /<NextContinuationToken>([\s\S]*?)<\/NextContinuationToken>/,
+ )?.[1]
+
+ if (continuationToken) {
+ continuationToken = decodeXmlValue(continuationToken)
+ }
+ } while (continuationToken)
+
+ return keys
+ }
+
+ private async signedFetch(
+ method: 'PUT' | 'GET' | 'DELETE',
+ key: string,
+ body?: PutObjectBody,
+ extraHeaders: HeaderMap = {},
+ payloadHashOverride?: string,
+ queryParams: Record<string, string | undefined> = {},
+ ): Promise<Response> {
+ // Stream bodies can only be read once, so they get a single attempt.
+ const attempts =
+ body instanceof Readable ? 1 : SESSION_REPLAY_STORAGE_MAX_ATTEMPTS
+ let lastError: unknown
+
+ for (let attempt = 0; attempt < attempts; attempt++) {
+ if (attempt > 0) {
+ await sleep(
+ SESSION_REPLAY_STORAGE_RETRY_BASE_DELAY_MS * 2 ** (attempt - 1),
+ )
+ }
+
+ try {
+ const response = await this.signedFetchOnce(
+ method,
+ key,
+ body,
+ extraHeaders,
+ payloadHashOverride,
+ queryParams,
+ )
+
+ if (
+ RETRYABLE_STATUS_CODES.has(response.status) &&
+ attempt < attempts - 1
+ ) {
+ lastError = new Error(
+ `S3 ${method} failed with status ${response.status}`,
+ )
+ continue
+ }
+
+ return response
+ } catch (reason) {
+ lastError = reason
+ }
+ }
+
+ throw lastError
+ }
+
+ private async signedFetchOnce(
+ method: 'PUT' | 'GET' | 'DELETE',
+ key: string,
+ body?: PutObjectBody,
+ extraHeaders: HeaderMap = {},
+ payloadHashOverride?: string,
+ queryParams: Record<string, string | undefined> = {},
+ ): Promise<Response> {
+ const config = this.getConfig()
+ if (!config) {
+ throw new Error('S3 session replay storage is not configured')
+ }
+
+ const hasStreamBody = body instanceof Readable
+ if (hasStreamBody && !payloadHashOverride) {
+ throw new Error('Stream uploads require a payload hash')
+ }
+
+ const payloadHash =
+ payloadHashOverride ||
+ sha256Hex(body instanceof Readable ? '' : body || '')
+ const now = new Date()
+ const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, '')
+ const dateStamp = amzDate.slice(0, 8)
+ const endpoint = new URL(config.endpoint)
+ const canonicalQuery = Object.entries(queryParams)
+ .filter(([, value]) => value !== undefined)
+ .sort(([left], [right]) => left.localeCompare(right))
+ .map(
+ ([key, value]) =>
+ `${encodeQueryValue(key)}=${encodeQueryValue(value || '')}`,
+ )
+ .join('&')
+
+ if (config.forcePathStyle) {
+ endpoint.pathname = `/${encodeURIComponent(config.bucket)}/${encodeKeyPath(key)}`
+ } else {
+ endpoint.hostname = `${config.bucket}.${endpoint.hostname}`
+ endpoint.pathname = `/${encodeKeyPath(key)}`
+ }
+ endpoint.search = canonicalQuery ? `?${canonicalQuery}` : ''
+
+ const headers: HeaderMap = {
+ host: endpoint.host,
+ 'x-amz-content-sha256': payloadHash,
+ 'x-amz-date': amzDate,
+ ...extraHeaders,
+ }
+ const signedHeaderKeys = Object.keys(headers)
+ .map((header) => header.toLowerCase())
+ .sort()
+ const canonicalHeaders = signedHeaderKeys
+ .map((header) => `${header}:${headers[header].trim()}\n`)
+ .join('')
+ const signedHeaders = signedHeaderKeys.join(';')
+ const credentialScope = `${dateStamp}/${config.region}/s3/aws4_request`
+ const canonicalRequest = [
+ method,
+ endpoint.pathname,
+ canonicalQuery,
+ canonicalHeaders,
+ signedHeaders,
+ payloadHash,
+ ].join('\n')
+ const stringToSign = [
+ 'AWS4-HMAC-SHA256',
+ amzDate,
+ credentialScope,
+ sha256Hex(canonicalRequest),
+ ].join('\n')
+ const dateKey = hmac(`AWS4${config.secretAccessKey}`, dateStamp)
+ const regionKey = hmac(dateKey, config.region)
+ const serviceKey = hmac(regionKey, 's3')
+ const signingKey = hmac(serviceKey, 'aws4_request')
+ const signature = crypto
+ .createHmac('sha256', signingKey)
+ .update(stringToSign)
+ .digest('hex')
+
+ headers.authorization = [
+ `AWS4-HMAC-SHA256 Credential=${config.accessKeyId}/${credentialScope}`,
+ `SignedHeaders=${signedHeaders}`,
+ `Signature=${signature}`,
+ ].join(', ')
+ const requestBody = body
+ ? hasStreamBody
+ ? (body as any)
+ : new Uint8Array(body)
+ : undefined
+ const controller = new AbortController()
+ const timeout = setTimeout(
+ () => controller.abort(),
+ SESSION_REPLAY_STORAGE_TIMEOUT_MS,
+ )
+ const request: RequestInit & { duplex?: 'half' } = {
+ method,
+ headers,
+ signal: controller.signal,
+ }
+
+ if (requestBody) {
+ request.body = requestBody
+ if (hasStreamBody) {
+ request.duplex = 'half'
+ }
+ }
+
+ try {
+ return await fetch(endpoint, request)
+ } finally {
+ clearTimeout(timeout)
+ }
+ }
+}
diff --git a/backend/apps/community/src/common/utils.ts b/backend/apps/community/src/common/utils.ts
index 301075931..a8aeaebb6 100644
--- a/backend/apps/community/src/common/utils.ts
+++ b/backend/apps/community/src/common/utils.ts
@@ -135,6 +135,7 @@ const ALLOWED_KEYS = [
'captchaDifficulty',
'captchaDifficultyMode',
'brandKeywords',
+ 'sessionReplayRetentionDays',
]
const CLICKHOUSE_PROJECT_UPDATABLE_KEYS = [
@@ -425,6 +426,8 @@ const updateProjectClickhouse = async (
let type = 'String'
if (INT8_COLUMNS.includes(col)) {
type = 'Int8'
+ } else if (col === 'sessionReplayRetentionDays') {
+ type = 'UInt16'
} else if (UINT8_COLUMNS.includes(col)) {
type = 'UInt8'
} else if (NULLABLE_INT64_COLUMNS.includes(col)) {
diff --git a/backend/apps/community/src/main.ts b/backend/apps/community/src/main.ts
index 8dab4ada1..4b3a95d81 100644
--- a/backend/apps/community/src/main.ts
+++ b/backend/apps/community/src/main.ts
@@ -1,3 +1,5 @@
+import { NestExpressApplication } from '@nestjs/platform-express'
+import express from 'express'
import { NestFactory } from '@nestjs/core'
import { ValidationPipe, VersioningType } from '@nestjs/common'
import cookieParser from 'cookie-parser'
@@ -7,7 +9,15 @@ import { isDevelopment } from './common/constants'
import { AppModule } from './app.module'
async function bootstrap() {
- const app = await NestFactory.create(AppModule)
+ const app = await NestFactory.create<NestExpressApplication>(AppModule, {
+ bodyParser: false,
+ })
+ app.use(
+ ['/log/session-replay/chunk', '/v1/log/session-replay/chunk'],
+ express.json({ limit: '15mb' }),
+ )
+ app.useBodyParser('json', { limit: '1mb' })
+ app.useBodyParser('urlencoded', { extended: true, limit: '1mb' })
app.use(cookieParser())
app.useGlobalPipes(new ValidationPipe())
diff --git a/backend/apps/community/src/project/dto/update-project.dto.ts b/backend/apps/community/src/project/dto/update-project.dto.ts
index 74ef95ecd..8c23c7d6e 100644
--- a/backend/apps/community/src/project/dto/update-project.dto.ts
+++ b/backend/apps/community/src/project/dto/update-project.dto.ts
@@ -42,4 +42,15 @@ export class UpdateProjectDto extends IntersectionType(
@IsIn(['manual', 'auto'])
@IsOptional()
captchaDifficultyMode?: 'manual' | 'auto'
+
+ @ApiProperty({
+ required: false,
+ description: 'Session replay retention in days.',
+ enum: [30, 90, 365, 1825],
+ default: 30,
+ })
+ @IsInt()
+ @IsIn([30, 90, 365, 1825])
+ @IsOptional()
+ sessionReplayRetentionDays?: number
}
diff --git a/backend/apps/community/src/project/entity/project.entity.ts b/backend/apps/community/src/project/entity/project.entity.ts
index 68b4ef241..6b1cde5ac 100644
--- a/backend/apps/community/src/project/entity/project.entity.ts
+++ b/backend/apps/community/src/project/entity/project.entity.ts
@@ -14,6 +14,7 @@ export class Project {
// IPs (or CIDR ranges) that bot detection (Shields) never flags
ipWhitelist: string[]
countryBlacklist: string[]
+ sessionReplayRetentionDays: number
active: boolean
public: boolean
isPasswordProtected: boolean
diff --git a/backend/apps/community/src/project/project.controller.ts b/backend/apps/community/src/project/project.controller.ts
index 74bcb7a40..e6bba1d12 100644
--- a/backend/apps/community/src/project/project.controller.ts
+++ b/backend/apps/community/src/project/project.controller.ts
@@ -43,7 +43,7 @@ import dayjs from 'dayjs'
import { hash } from 'bcrypt'
import { Auth } from '../auth/decorators'
-import { isValidDate } from '../analytics/analytics.service'
+import { AnalyticsService, isValidDate } from '../analytics/analytics.service'
import {
LEGAL_PID_CHARACTERS,
PID_LENGTH,
@@ -117,6 +117,7 @@ import { LetterTemplate } from '../mailer/letter'
export class ProjectController {
constructor(
private readonly projectService: ProjectService,
+ private readonly analyticsService: AnalyticsService,
private readonly logger: AppLoggerService,
private readonly userService: UserService,
private readonly mailerService: MailerService,
@@ -1015,6 +1016,10 @@ export class ProjectController {
this.projectService.allowedToManage(project, userId)
+ await this.analyticsService.deleteData(id, '[]', null, null, [
+ 'session_replay',
+ ])
+
await deleteProjectClickhouse(id)
try {
@@ -1175,6 +1180,10 @@ export class ProjectController {
project.captchaDifficultyMode = projectDTO.captchaDifficultyMode
}
+ if (projectDTO.sessionReplayRetentionDays !== undefined) {
+ project.sessionReplayRetentionDays = projectDTO.sessionReplayRetentionDays
+ }
+
if (projectDTO.brandKeywords !== undefined) {
project.brandKeywords = projectDTO.brandKeywords
}
@@ -1231,16 +1240,21 @@ export class ProjectController {
this.projectService.allowedToView(project, userId, headers['x-password'])
- const [isDataExists, isErrorDataExists, isCaptchaDataExists] =
- await Promise.all([
- !_isEmpty(
- await this.projectService.getPIDsWhereAnalyticsDataExists([id]),
- ),
- !_isEmpty(await this.projectService.getPIDsWhereErrorsDataExists([id])),
- !_isEmpty(
- await this.projectService.getPIDsWhereCaptchaDataExists([id]),
- ),
- ])
+ const [
+ isDataExists,
+ isErrorDataExists,
+ isCaptchaDataExists,
+ isReplayDataExists,
+ ] = await Promise.all([
+ !_isEmpty(
+ await this.projectService.getPIDsWhereAnalyticsDataExists([id]),
+ ),
+ !_isEmpty(await this.projectService.getPIDsWhereErrorsDataExists([id])),
+ !_isEmpty(await this.projectService.getPIDsWhereCaptchaDataExists([id])),
+ !_isEmpty(
+ await this.projectService.getPIDsWhereSessionReplayDataExists([id]),
+ ),
+ ])
const funnels = await getFunnelsClickhouse(id)
const rawShares = await findProjectSharesByProjectClickhouse(id)
@@ -1287,6 +1301,7 @@ export class ProjectController {
isDataExists,
isErrorDataExists,
isCaptchaDataExists,
+ isReplayDataExists,
role,
isLocked: false,
isAccessConfirmed,
diff --git a/backend/apps/community/src/project/project.module.ts b/backend/apps/community/src/project/project.module.ts
index 46d3d9dc8..7db9de253 100644
--- a/backend/apps/community/src/project/project.module.ts
+++ b/backend/apps/community/src/project/project.module.ts
@@ -1,3 +1,4 @@
+import { AnalyticsModule } from '../analytics/analytics.module'
import { Module, forwardRef } from '@nestjs/common'
import { ProjectService } from './project.service'
@@ -9,7 +10,12 @@ import { UserModule } from '../user/user.module'
import { MailerModule } from '../mailer/mailer.module'
@Module({
- imports: [AppLoggerModule, forwardRef(() => UserModule), MailerModule],
+ imports: [
+ forwardRef(() => AnalyticsModule),
+ AppLoggerModule,
+ forwardRef(() => UserModule),
+ MailerModule,
+ ],
providers: [ProjectService, GSCService],
exports: [ProjectService, GSCService],
controllers: [ProjectController, GSCController],
diff --git a/backend/apps/community/src/project/project.service.ts b/backend/apps/community/src/project/project.service.ts
index 740568b4f..0bc163a30 100644
--- a/backend/apps/community/src/project/project.service.ts
+++ b/backend/apps/community/src/project/project.service.ts
@@ -671,4 +671,41 @@ export class ProjectService {
this.validateIPWhitelist(projectDTO)
this.validateCountryBlacklist(projectDTO)
}
+
+ async getPIDsWhereSessionReplayDataExists(
+ projectIds: string[],
+ ): Promise<string[]> {
+ if (_isEmpty(projectIds)) {
+ return []
+ }
+
+ const params = _reduce(
+ projectIds,
+ (acc, curr, index) => ({
+ ...acc,
+ [`pid_${index}`]: curr,
+ }),
+ {},
+ )
+
+ const pids = _join(
+ _map(params, (val, key) => `{${key}:FixedString(12)}`),
+ ',',
+ )
+
+ const query = `
+ SELECT DISTINCT pid
+ FROM session_replay_chunks
+ WHERE pid IN (${pids})
+ `
+
+ const { data } = await clickhouse
+ .query({
+ query,
+ query_params: params,
+ })
+ .then((resultSet) => resultSet.json<{ pid: string }>())
+
+ return _map(data, ({ pid }) => pid)
+ }
}
diff --git a/backend/apps/community/src/task-manager/task-manager.service.ts b/backend/apps/community/src/task-manager/task-manager.service.ts
index c87add44b..1bdb34103 100644
--- a/backend/apps/community/src/task-manager/task-manager.service.ts
+++ b/backend/apps/community/src/task-manager/task-manager.service.ts
@@ -1,14 +1,29 @@
-import { Injectable } from '@nestjs/common'
+import { AnalyticsService } from '../analytics/analytics.service'
+import { Injectable, Logger } from '@nestjs/common'
import { Cron, CronExpression } from '@nestjs/schedule'
import { SaltService } from '../analytics/salt.service'
@Injectable()
export class TaskManagerService {
- constructor(private readonly saltService: SaltService) {}
+ private readonly logger = new Logger(TaskManagerService.name)
+
+ constructor(
+ private readonly saltService: SaltService,
+ private readonly analyticsService: AnalyticsService,
+ ) {}
@Cron(CronExpression.EVERY_HOUR)
async regenerateGlobalSalts() {
await this.saltService.regenerateExpiredSalts()
}
+
+ @Cron(CronExpression.EVERY_10_MINUTES, { waitForCompletion: true })
+ async cleanupExpiredSessionReplays() {
+ try {
+ await this.analyticsService.cleanupExpiredSessionReplays()
+ } catch (reason) {
+ this.logger.error('Failed to clean up expired session replays', reason)
+ }
+ }
}
diff --git a/backend/migrations/clickhouse/initialise_selfhosted.js b/backend/migrations/clickhouse/initialise_selfhosted.js
index 253c2bd2c..0364f9dda 100644
--- a/backend/migrations/clickhouse/initialise_selfhosted.js
+++ b/backend/migrations/clickhouse/initialise_selfhosted.js
@@ -3,6 +3,25 @@ const { queriesRunner, dbName } = require('./setup')
const { initialiseDatabase } = require('./initialise_database')
const CLICKHOUSE_INIT_QUERIES = [
+ `CREATE TABLE IF NOT EXISTS ${dbName}.session_replay_chunks
+ (
+ pid FixedString(12),
+ psid UInt64,
+ replayId String CODEC(ZSTD(3)),
+ chunkIndex UInt32,
+ objectKey String CODEC(ZSTD(3)),
+ privacyMode LowCardinality(String),
+ eventCount UInt32,
+ uncompressedBytes UInt32,
+ compressedBytes UInt32,
+ firstEventTimestamp Nullable(UInt64),
+ lastEventTimestamp Nullable(UInt64),
+ created DateTime('UTC') CODEC(Delta(4), LZ4),
+ expiresAt DateTime('UTC') CODEC(Delta(4), LZ4)
+ )
+ ENGINE = ReplacingMergeTree(created)
+ PARTITION BY toYYYYMM(created)
+ ORDER BY (pid, psid, replayId, chunkIndex);`,
`CREATE TABLE IF NOT EXISTS ${dbName}.user
(
id FixedString(36),
@@ -29,6 +48,7 @@ const CLICKHOUSE_INIT_QUERIES = [
ipBlacklist Nullable(String) CODEC(ZSTD(3)),
ipWhitelist Nullable(String) CODEC(ZSTD(3)),
countryBlacklist Nullable(String) CODEC(ZSTD(3)),
+ sessionReplayRetentionDays UInt16 DEFAULT 30,
active Int8,
public Int8,
isPasswordProtected Int8,
diff --git a/backend/migrations/clickhouse/selfhosted_2026_09_12_session_replays.js b/backend/migrations/clickhouse/selfhosted_2026_09_12_session_replays.js
new file mode 100644
index 000000000..f8ab2ba2e
--- /dev/null
+++ b/backend/migrations/clickhouse/selfhosted_2026_09_12_session_replays.js
@@ -0,0 +1,27 @@
+const { queriesRunner, dbName } = require('./setup')
+
+const queries = [
+ `CREATE TABLE IF NOT EXISTS ${dbName}.session_replay_chunks
+ (
+ pid FixedString(12),
+ psid UInt64,
+ replayId String CODEC(ZSTD(3)),
+ chunkIndex UInt32,
+ objectKey String CODEC(ZSTD(3)),
+ privacyMode LowCardinality(String),
+ eventCount UInt32,
+ uncompressedBytes UInt32,
+ compressedBytes UInt32,
+ firstEventTimestamp Nullable(UInt64),
+ lastEventTimestamp Nullable(UInt64),
+ created DateTime('UTC') CODEC(Delta(4), LZ4),
+ expiresAt DateTime('UTC') CODEC(Delta(4), LZ4)
+ )
+ ENGINE = ReplacingMergeTree(created)
+ PARTITION BY toYYYYMM(created)
+ ORDER BY (pid, psid, replayId, chunkIndex);`,
+
+ `ALTER TABLE ${dbName}.project ADD COLUMN IF NOT EXISTS sessionReplayRetentionDays UInt16 DEFAULT 30;`,
+]
+
+queriesRunner(queries)
diff --git a/docs/content/docs/analytics-dashboard/session-replays.mdx b/docs/content/docs/analytics-dashboard/session-replays.mdx
index 32463dd52..f68c5a510 100644
--- a/docs/content/docs/analytics-dashboard/session-replays.mdx
+++ b/docs/content/docs/analytics-dashboard/session-replays.mdx
@@ -4,9 +4,9 @@ slug: /analytics-dashboard/session-replays
description: "Use Swetrix session replays to investigate visitor interactions, understand usability problems, and diagnose issues in context."
---
-<Callout type="info" title="Cloud Exclusive">
- Session replays are exclusively available on **Swetrix Cloud**. They are not currently available
- for self-hosted instances.
+<Callout type="info">
+ Session replays are available on Swetrix Cloud and Community Edition. For a self-hosted instance,
+ first [configure S3-compatible replay storage](/selfhosting/session-replays).
</Callout>
Session Replays let you watch recorded browser sessions alongside the analytics context Swetrix already collects. Use them to debug confusing journeys, reproduce issues, review funnel drop-offs, and understand what happened before an error or conversion.
diff --git a/docs/content/docs/selfhosting/configuring.mdx b/docs/content/docs/selfhosting/configuring.mdx
index 1aebc73cc..a6a3e3c58 100644
--- a/docs/content/docs/selfhosting/configuring.mdx
+++ b/docs/content/docs/selfhosting/configuring.mdx
@@ -36,6 +36,12 @@ The `BASE_URL` must be publicly reachable from your users' browsers. Do not set
| `IS_PRIMARY_NODE` | `true` | You should not touch this variable unless you know what you are doing. It's used to spin off multiple API instances in a cluster, where only one of them will be primary. If changed to `false`, things like cron task manager will be disabled for this instance. |
| `TWO_FACTOR_AUTHENTICATION_APP_NAME` | `Swetrix CE` | The app name shown in authenticator apps when users set up 2FA. |
+### Session replay storage
+
+Community Edition supports session replays with a private S3-compatible bucket. Configure `SESSION_REPLAY_S3_ENDPOINT`, `SESSION_REPLAY_S3_BUCKET`, `SESSION_REPLAY_S3_REGION`, `SESSION_REPLAY_S3_ACCESS_KEY_ID`, and `SESSION_REPLAY_S3_SECRET_ACCESS_KEY` on the API container. Set `SESSION_REPLAY_S3_FORCE_PATH_STYLE=true` for providers such as MinIO that use path-style URLs.
+
+See [Session replays](/selfhosting/session-replays) for provider examples, Docker environment forwarding, proxy limits, retention, and MP4 export setup.
+
### Email configuration (SMTP)
Swetrix will send transactional emails for some actions, like password reset or project invitations. You must configure SMTP credentials for this to work correctly.
diff --git a/docs/content/docs/selfhosting/how-to.mdx b/docs/content/docs/selfhosting/how-to.mdx
index d15e58efd..b9081dd85 100644
--- a/docs/content/docs/selfhosting/how-to.mdx
+++ b/docs/content/docs/selfhosting/how-to.mdx
@@ -163,3 +163,7 @@ If you'd rather not run Docker Compose on a server yourself, the community maint
[![Deploy on Railway](/img/integrations/railway-button.svg)](https://railway.com/deploy/swetrix)
The template's source lives at [osbytes/template-swetrix](https://github.com/osbytes/template-swetrix).
+
+## Session replays
+
+To record and play back sessions, configure your own private S3-compatible bucket using the [Session replay setup guide](/selfhosting/session-replays). Replay storage is optional; ordinary analytics works without it.
diff --git a/docs/content/docs/selfhosting/meta.json b/docs/content/docs/selfhosting/meta.json
index eea80cd4d..92b3c13ea 100644
--- a/docs/content/docs/selfhosting/meta.json
+++ b/docs/content/docs/selfhosting/meta.json
@@ -1,4 +1,4 @@
{
"title": "Self-hosting",
- "pages": ["how-to", "configuring", "google-search-console", "google-analytics"]
+ "pages": ["how-to", "configuring", "session-replays", "google-search-console", "google-analytics"]
}
diff --git a/docs/content/docs/selfhosting/session-replays.mdx b/docs/content/docs/selfhosting/session-replays.mdx
new file mode 100644
index 000000000..7333aee97
--- /dev/null
+++ b/docs/content/docs/selfhosting/session-replays.mdx
@@ -0,0 +1,121 @@
+---
+title: Session replays
+slug: /selfhosting/session-replays
+description: "Configure private S3-compatible storage for session recording, playback, and MP4 exports in Swetrix Community Edition."
+---
+
+Community Edition supports session recording, playback, and MP4 exports using the same recorder and player as Swetrix Cloud. Recordings are stored in your own private S3-compatible bucket; ClickHouse stores replay metadata and Redis coordinates recording and export jobs. There is no subscription or monthly replay quota in Community Edition.
+
+## Configure storage
+
+Create a private bucket and credentials with permission to read, write, and delete objects in that bucket. Swetrix creates objects, but does not create the bucket. The API must be able to reach the storage endpoint. Browsers access recordings through Swetrix, so the bucket does not need public access or browser CORS rules.
+
+Add these variables to the `.env` file in your self-hosting directory:
+
+```dotenv
+SESSION_REPLAY_S3_ENDPOINT=https://s3.eu-west-1.amazonaws.com
+SESSION_REPLAY_S3_BUCKET=swetrix-replays
+SESSION_REPLAY_S3_REGION=eu-west-1
+SESSION_REPLAY_S3_ACCESS_KEY_ID=your-access-key
+SESSION_REPLAY_S3_SECRET_ACCESS_KEY=your-secret-key
+SESSION_REPLAY_S3_FORCE_PATH_STYLE=false
+```
+
+| Variable | Description |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SESSION_REPLAY_S3_ENDPOINT` | S3 API endpoint, including `https://` or `http://`. Use the service endpoint, without a bucket name, object path, or query string. |
+| `SESSION_REPLAY_S3_BUCKET` | Name of an existing private bucket. |
+| `SESSION_REPLAY_S3_REGION` | Region used to sign S3 requests. Defaults to the location inferred from a Hetzner endpoint, or `us-east-1` for other providers. Set your bucket's region explicitly for AWS. |
+| `SESSION_REPLAY_S3_ACCESS_KEY_ID` | Access key for the bucket. Keep it on the API server. |
+| `SESSION_REPLAY_S3_SECRET_ACCESS_KEY` | Secret key for the bucket. Keep it on the API server. |
+| `SESSION_REPLAY_S3_FORCE_PATH_STYLE` | Set to `true` to use `endpoint/bucket/key`, for example with MinIO. Defaults to `false`, which uses `bucket.endpoint/key`. |
+
+For AWS, grant `s3:GetObject`, `s3:PutObject`, and `s3:DeleteObject` on the bucket's objects. This setup uses access-key credentials, rather than an IAM role or temporary session token.
+
+Common endpoint settings:
+
+| Provider | Endpoint example | Region | Path style |
+| -------------------------------- | -------------------------------------------------- | ----------------------------------------- | ---------- |
+| AWS S3 | `https://s3.eu-west-1.amazonaws.com` | `eu-west-1` (match your bucket) | `false` |
+| Hetzner Object Storage | `https://fsn1.your-objectstorage.com` | `fsn1` (or leave blank to infer it) | `false` |
+| Cloudflare R2 | `https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com` | `auto` | `true` |
+| MinIO on the same Docker network | `http://minio:9000` | `us-east-1` (unless configured otherwise) | `true` |
+
+For R2, use the [S3 API endpoint and credentials](https://developers.cloudflare.com/r2/api/s3/api/), rather than a public bucket URL. For MinIO, use the S3 API port, not the web console port. A Docker container's `localhost` points to that container, so use the storage service name or a reachable hostname.
+
+## Pass the variables to Docker
+
+The self-hosting Compose configuration forwards the replay variables to the API container, and `configure.sh` includes optional replay settings in newly generated `.env` files. For an existing installation, add the values to your `.env` manually.
+
+If your older `compose.yaml` does not include replay variables, add the following entries to its existing `swetrix-api.environment` list, preserving its other entries. A Compose `.env` file alone does not pass every variable into the container:
+
+```yaml
+- SESSION_REPLAY_S3_ENDPOINT=${SESSION_REPLAY_S3_ENDPOINT}
+- SESSION_REPLAY_S3_BUCKET=${SESSION_REPLAY_S3_BUCKET}
+- SESSION_REPLAY_S3_REGION=${SESSION_REPLAY_S3_REGION:-}
+- SESSION_REPLAY_S3_ACCESS_KEY_ID=${SESSION_REPLAY_S3_ACCESS_KEY_ID}
+- SESSION_REPLAY_S3_SECRET_ACCESS_KEY=${SESSION_REPLAY_S3_SECRET_ACCESS_KEY}
+- SESSION_REPLAY_S3_FORCE_PATH_STYLE=${SESSION_REPLAY_S3_FORCE_PATH_STYLE:-false}
+```
+
+Use API and frontend images from a Community Edition release containing session replay support. Recreate the containers after updating their image tags and configuration:
+
+```bash
+docker compose up -d --force-recreate swetrix-api swetrix
+```
+
+The API's startup initialiser creates `session_replay_chunks` and adds the `sessionReplayRetentionDays` project column if missing. This also upgrades an existing CE database; there is no MySQL migration to run. If you use a custom startup command, run `npm run clickhouse:initialise` before starting the API.
+
+To apply only the replay schema upgrade to an existing CE database, run this standalone migration from the backend directory with your ClickHouse environment variables configured:
+
+```bash
+node migrations/clickhouse/selfhosted_2026_09_11_session_replays.js
+```
+
+The migration uses `IF NOT EXISTS` for both the table and retention column, so it can be rerun after a partial upgrade or the normal startup initialiser.
+
+Without storage credentials, ordinary analytics continues to work, but attempts to start a recording return `Session replay storage is not configured`.
+
+## Allow replay uploads through your proxy
+
+The API accepts replay chunk requests up to 15 MiB on `/log/session-replay/chunk` and `/v1/log/session-replay/chunk`. Your reverse proxy must also allow that size. The self-hosting Nginx configuration includes this limit. If you have an older configuration, add this inside the existing `location /backend/` block:
+
+```nginx
+client_max_body_size 15m;
+```
+
+Reload Nginx after validating its configuration. Custom proxies must forward the replay start and chunk routes, as well as the existing analytics routes. HTTP `413` responses usually mean a proxy upload limit is too small.
+
+## Start recording
+
+Initialise your tracker with your CE API URL, then explicitly start the recorder:
+
+```javascript
+swetrix.init("YOUR_PROJECT_ID", {
+ apiURL: "https://analytics.example.com/backend",
+});
+
+await swetrix.startSessionReplay({ privacy: "total" });
+```
+
+Use a current `swetrix` tracker version that supports `startSessionReplay()`. The `apiURL` above matches the standard self-hosting proxy; change it if you use another API route. Recording is opt-in and does not start automatically when you initialise analytics.
+
+Open the **Replays** tab in your project's dashboard to watch recordings. See [Session Replays](/analytics-dashboard/session-replays) for the player and [the script reference](/swetrix-js-reference#startsessionreplay) for privacy modes and masking options.
+
+## Retention and maintenance
+
+Choose **30 days, 90 days, 1 year, or 5 years** in **Project Settings > Session replays**. The default is 30 days. Changes affect newly uploaded chunks; existing chunks retain their original expiry dates.
+
+Expired chunks stop appearing in playback immediately. The primary API node cleans up expired storage objects and their ClickHouse rows in batches every 10 minutes. Keep at least one API instance running with `IS_PRIMARY_NODE=true`. Failed object deletions remain eligible for a later cleanup attempt. A backlog can take multiple runs to clear.
+
+You can delete individual replays from the player or replay list, or select session replays in the project's data-deletion tool. Deleting a project also removes its recordings. Keep storage credentials configured while deleting replay data.
+
+Back up both ClickHouse and the bucket to preserve recordings and their metadata. If you enable bucket versioning, configure lifecycle rules for noncurrent versions; ordinary object deletion does not purge those versions. Do not expire current recording objects earlier than their configured retention period.
+
+## MP4 exports
+
+The CE API Docker image includes Chromium and FFmpeg for MP4 exports. Exports run through Redis-backed background jobs and require writable temporary disk space. Allow additional RAM, CPU, and temporary disk capacity when exporting long sessions. Custom API images need the same browser and video tooling.
+
+`SESSION_REPLAY_EXPORT_CONCURRENCY` defaults to `1`; increase it only when the API server has capacity for more simultaneous renders. `SESSION_REPLAY_EXPORT_TTL_SECONDS` defaults to `86400` (24 hours), after which generated MP4 files expire. Pass either variable into the API container if you override it.
+
+Recording retains Cloud's per-replay safeguards: at most 30 minutes, 100,000 events, 1,200 chunks, and 150 MiB of uncompressed event data. A single event is limited to 5 MiB. Storage and transfer costs depend on your provider and recording volume.
diff --git a/web/app/pages/Project/Settings/ProjectSettings.tsx b/web/app/pages/Project/Settings/ProjectSettings.tsx
index 1a5324081..aee9424e9 100644
--- a/web/app/pages/Project/Settings/ProjectSettings.tsx
+++ b/web/app/pages/Project/Settings/ProjectSettings.tsx
@@ -323,7 +323,7 @@ const ProjectSettings = () => {
description: t('project.settings.tabs.sessionReplaysDesc'),
icon: VideoCameraIcon,
iconColor: 'text-violet-500',
- visible: !isSelfhosted,
+ visible: true,
},
{
id: 'emails',
@@ -379,7 +379,7 @@ const ProjectSettings = () => {
)
const sessionReplayMaxRetentionDays = useMemo(() => {
- return user?.sessionReplayRetentionDays || 30
+ return isSelfhosted ? 1825 : user?.sessionReplayRetentionDays || 30
}, [user?.sessionReplayRetentionDays])
const activeTab = useMemo<SettingsTab>(() => {
diff --git a/web/app/pages/Project/Settings/components/DeleteDataModal.tsx b/web/app/pages/Project/Settings/components/DeleteDataModal.tsx
index 25b53bc06..14300083a 100644
--- a/web/app/pages/Project/Settings/components/DeleteDataModal.tsx
+++ b/web/app/pages/Project/Settings/components/DeleteDataModal.tsx
@@ -15,7 +15,6 @@ import { toast } from 'sonner'
import type { DataDeletionPreview } from '~/api/api.server'
import { useDataDeletionPreviewProxy } from '~/hooks/useAnalyticsProxy'
-import { isSelfhosted } from '~/lib/constants'
import type { ProjectSettingsActionData } from '~/routes/projects.settings.$id'
import DatePicker from '~/ui/Datepicker'
import HoldToConfirmButton from '~/ui/HoldToConfirmButton'
@@ -45,8 +44,6 @@ interface EventType {
Icon: React.ElementType
}
-// Order mirrors how prominent each type is for a typical cleanup. Session
-// replays are cloud-only β€” self-hosted has no replay storage.
const EVENT_TYPES: EventType[] = [
{
key: 'pageview',
@@ -73,15 +70,11 @@ const EVENT_TYPES: EventType[] = [
labelKey: 'project.settings.deleteData.types.captcha',
Icon: ShieldCheckIcon,
},
- ...(isSelfhosted
- ? []
- : [
- {
- key: 'session_replay',
- labelKey: 'project.settings.deleteData.types.session_replay',
- Icon: MonitorPlayIcon,
- },
- ]),
+ {
+ key: 'session_replay',
+ labelKey: 'project.settings.deleteData.types.session_replay',
+ Icon: MonitorPlayIcon,
+ },
]
const DEFAULT_TYPES = ['pageview', 'custom_event']