:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { EventType, IncrementalSource, eventWithTime } from 'posthog-js/rrweb-types'
import { RecordingSegment, RecordingSnapshot } from './types'
// nodejs/src/ingestion/pipelines/sessionreplay/segmentation.ts has a cut-down version of this
// for computing activeMilliseconds during ingestion. It intentionally differs:
// no window tracking, no gap filling, different isActiveEvent rules.
const activeSources = [
IncrementalSource.MouseMove,
IncrementalSource.MouseInteraction,
IncrementalSource.Scroll,
IncrementalSource.ViewportResize,
IncrementalSource.Input,
IncrementalSource.TouchMove,
IncrementalSource.MediaInteraction,
IncrementalSource.Drag,
]
const ACTIVITY_THRESHOLD_MS = 5000
const isActiveEvent = (event: eventWithTime): boolean => {
return (
event.type === EventType.FullSnapshot ||
event.type === EventType.Meta ||
(event.type === EventType.IncrementalSnapshot && activeSources.includes(event.data?.source))
)
}
export const mapSnapshotsToWindowId = (snapshots: RecordingSnapshot[]): Record<number, eventWithTime[]> => {
const snapshotsByWindowId: Record<number, eventWithTime[]> = {}
snapshots.forEach((snapshot) => {
if (!snapshotsByWindowId[snapshot.windowId]) {
snapshotsByWindowId[snapshot.windowId] = []
}
snapshotsByWindowId[snapshot.windowId].push(snapshot)
})
return snapshotsByWindowId
}
export const createSegments = (
snapshots: RecordingSnapshot[],
start: number | null,
end: number | null,
trackedWindow: number | null | undefined,
snapshotsByWindowId: Record<number, eventWithTime[]>,
// whether every source covering [startTs, endTs] has loaded; null = unknown, keep the default kind
isRangeLoaded: (startTimestamp: number, endTimestamp: number) => boolean | null = () => null
): RecordingSegment[] => {
let segments: RecordingSegment[] = []
let activeSegment!: Partial<RecordingSegment>
let lastActiveEventTimestamp = 0
snapshots.forEach((snapshot, index) => {
const eventIsActive = isActiveEvent(snapshot)
const previousSnapshot = snapshots[index - 1]
const isPreviousSnapshotLastForWindow =
snapshotsByWindowId[previousSnapshot?.windowId]?.slice(-1)[0] === previousSnapshot
// When do we create a new segment?
// 1. If we don't have one yet
let isNewSegment = !activeSegment
// 2. If it is currently inactive but a new "active" event comes in
if (eventIsActive && !activeSegment?.isActive) {
isNewSegment = true
}
// 3. If it is currently active but no new active event has been seen for the activity threshold
if (activeSegment?.isActive && lastActiveEventTimestamp + ACTIVITY_THRESHOLD_MS < snapshot.timestamp) {
isNewSegment = true
}
// 4. If windowId changes we create a new segment
if (activeSegment?.windowId !== snapshot.windowId && eventIsActive) {
isNewSegment = true
}
// 5. If there are no more snapshots for this windowId
if (isPreviousSnapshotLastForWindow) {
isNewSegment = true
}
// NOTE: We have to make sure that we set this _after_ we use it
lastActiveEventTimestamp = eventIsActive ? snapshot.timestamp : lastActiveEventTimestamp
if (isNewSegment) {
if (activeSegment) {
segments.push(activeSegment as RecordingSegment)
}
activeSegment = {
kind: 'window',
startTimestamp: snapshot.timestamp,
windowId: snapshot.windowId,
isActive: eventIsActive,
}
}
activeSegment.endTimestamp = snapshot.timestamp
})
if (activeSegment) {
segments.push(activeSegment as RecordingSegment)
}
// We've built the segments, but this might not account for "gaps" in them
// To account for this we build up a new segment list filling in gaps with
// either the tracked window if the viewing window is fixed
// or whatever window is available (preferably the previous one)
// Or a "null" window if there is nothing (like if they navigated away to a different site)
const findWindowIdForTimestamp = (timestamp: number, preferredWindowId?: number): number | undefined => {
// Check all the snapshotsByWindowId to see if the timestamp is within its range
// prefer the preferredWindowId if it is within its range
let windowIds = Object.keys(snapshotsByWindowId).map(Number)
if (preferredWindowId !== undefined) {
windowIds = [preferredWindowId, ...windowIds.filter((id) => id !== preferredWindowId)]
}
for (const windowId of windowIds) {
const snapshots = snapshotsByWindowId[windowId]
if (snapshots[0].timestamp <= timestamp && snapshots[snapshots.length - 1].timestamp >= timestamp) {
return windowId
}
}
}
segments = segments.reduce((acc, segment, index) => {
const previousSegment = segments[index - 1]
const list = [...acc]
if (previousSegment && segment.startTimestamp !== previousSegment.endTimestamp) {
// If the segments do not immediately follow each other, then we add a "gap" segment
const startTimestamp = previousSegment.endTimestamp
const endTimestamp = segment.startTimestamp
// Offset the window ID check so we look for a subsequent segment
const preferredWindowId = trackedWindow ?? previousSegment.windowId
const windowId = findWindowIdForTimestamp(startTimestamp + 1, preferredWindowId)
// A "gap" whose sources haven't loaded yet is pending data, not real inactivity — classify it as buffer so the player waits instead of skipping.
const gapSegment: Partial<RecordingSegment> = {
kind: isRangeLoaded(startTimestamp, endTimestamp) === false ? 'buffer' : 'gap',
startTimestamp,
endTimestamp,
windowId,
isActive: false,
}
list.push(gapSegment as RecordingSegment)
}
list.push(segment)
return list
}, [] as RecordingSegment[])
if (start && end) {
// As we don't necessarily have all the segments at once, we add a final segment to fill the gap between the last segment and the end of the recording
const latestTimestamp = segments[segments.length - 1]?.endTimestamp
const endTimestamp = end
if (!latestTimestamp || latestTimestamp < endTimestamp) {
const startTimestamp = latestTimestamp ? latestTimestamp + 1 : start
// The trailing region is pending data by default, but once its sources are all loaded it is just trailing inactivity.
segments.push({
kind: isRangeLoaded(startTimestamp, endTimestamp) === true ? 'gap' : 'buffer',
startTimestamp,
endTimestamp: endTimestamp,
isActive: false,
} as RecordingSegment)
}
// if the first segment starts after the start of the session, add a gap segment at the beginning
const firstTimestamp = segments[0]?.startTimestamp
if (firstTimestamp && firstTimestamp > start) {
segments.unshift({
kind: isRangeLoaded(start, firstTimestamp) === false ? 'buffer' : 'gap',
startTimestamp: start,
endTimestamp: firstTimestamp,
isActive: false,
} as RecordingSegment)
}
}
segments = segments.map((segment) => {
// These can all be done in a loop at the end...
segment.durationMs = segment.endTimestamp - segment.startTimestamp
return segment
})
return segments
}
/**
* Merge runs of consecutive inactive segments into single segments.
* Active segments pass through unchanged. This produces output similar
* to the PostHog frontend's merged regions — fewer, coarser periods
* that are easier to skip over and less noisy for consumers.
*/
export const mergeInactiveSegments = (segments: RecordingSegment[]): RecordingSegment[] => {
const merged: RecordingSegment[] = []
let i = 0
while (i < segments.length) {
if (segments[i].isActive) {
merged.push(segments[i])
i++
continue
}
// Start of an inactive run — scan forward to the last consecutive inactive segment
const first = segments[i]
let last = first
while (i + 1 < segments.length && !segments[i + 1].isActive) {
i++
last = segments[i]
}
merged.push({
kind: first.kind,
startTimestamp: first.startTimestamp,
endTimestamp: last.endTimestamp,
durationMs: last.endTimestamp - first.startTimestamp,
windowId: first.windowId,
isActive: false,
})
i++
}
return merged
}