Skip to content

: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.

8.9 KB
Raw Blame
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
}