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.

26.8 KB
Raw Blame
import { useActions, useValues } from 'kea'
import { Fragment } from 'react'

import { IconChevronDown, IconInfo } from '@posthog/icons'
import { LemonBanner, LemonSegmentedButton, LemonSkeleton } from '@posthog/lemon-ui'
import {
    DropdownMenu,
    DropdownMenuCheckboxItem,
    DropdownMenuContent,
    DropdownMenuGroup,
    DropdownMenuItem,
    DropdownMenuLabel,
    DropdownMenuSeparator,
    DropdownMenuTrigger,
} from '@posthog/quill'

import { dayjs } from 'lib/dayjs'
import { useFeatureFlag } from 'lib/hooks/useFeatureFlag'
import { LemonButton } from 'lib/lemon-ui/LemonButton'
import { Tooltip } from 'lib/lemon-ui/Tooltip'
import { pluralize } from 'lib/utils/strings'
import { SessionRecordingsPlaylist } from 'scenes/session-recordings/playlist/SessionRecordingsPlaylist'
import { sessionRecordingsPlaylistLogic } from 'scenes/session-recordings/playlist/sessionRecordingsPlaylistLogic'

import { Experiment } from '~/types'

import { NOT_A_FUNNEL_REASON } from '../utils'
import { ExperimentBehaviorComparison, ExperimentBehaviorComparisonToggle } from './ExperimentBehaviorComparison'
import { EXPERIMENT_RECORDING_MODE_OPTIONS, METRIC_UNSELECTABLE_COPY } from './experimentRecordingModes'
import { type ExperimentReplayMetricFilterMode, isFunnelMode } from './experimentRecordingsDeepLink'
import { ExperimentRecordingsListEmptyState } from './ExperimentRecordingsListEmptyState'
import {
    ExperimentRecordingsListUnavailableReason,
    ExperimentReplayMetricOption,
    ExperimentSessionBucket,
    experimentReplayTabLogic,
} from './experimentReplayTabLogic'
import { ExperimentScannerEntryPoint } from './ExperimentScannerEntryPoint'
import { VariantTag } from './VariantTag'

// LemonSegmentedButton values must be strings; the logic stores null for "All". '$' is not an
// allowed character in variant keys, so the '$' prefix guarantees no collision with a real
// variant — a variant literally named "all" just renders as its own option after the built-in "All".
const ALL_VARIANTS = '$all'

// The 'all_exposed' caption carries the part that isn't guessable: exposure is resolved per
// person, matching who the analysis counts, so sessions appear even when the exposure event fired
// server-side or in an earlier session.
const ALL_EXPOSED_CAPTION =
    "Showing sessions of exposed participants from their first exposure onward. The exposure event itself doesn't have to be in the session."

// The copy varies with what the in-session evidence is. 'stamped' means the flag property stands
// in for the exposure event, so the flag was active in the session rather than the exposure event
// being captured there, and the copy must not claim more than the query delivers (wording mirrors
// the behavior-comparison shelf). 'unknown' covers the availability check still pending or failed,
// where the copy claims only what both kinds share. The scopeLockedReason strings park the control
// while a bucket or watch card supplies the session set, which carries in-session evidence by
// construction, so the control could neither widen nor narrow it.
type InSessionEvidenceKind = 'event' | 'stamped' | 'unknown'
const IN_SESSION_COPY: Record<InSessionEvidenceKind, { tooltip: string; caption: string; scopeLockedReason: string }> =
    {
        event: {
            tooltip: 'Only sessions where an exposure event for this experiment was captured in the session.',
            caption: 'Showing sessions of exposed participants where the exposure was captured in the session.',
            scopeLockedReason:
                'This metric filter already narrows to sessions where the exposure was captured in the session.',
        },
        stamped: {
            tooltip:
                'Sessions where the feature flag was active. No exposure event can be matched to a recording for this experiment, so the flag being active stands in.',
            caption:
                'Showing sessions of exposed participants where the feature flag was active, since no exposure event can be matched to a recording here.',
            scopeLockedReason: 'This metric filter already narrows to sessions where the feature flag was active.',
        },
        unknown: {
            tooltip: 'Only sessions carrying in-session exposure evidence for this experiment.',
            caption: 'Showing sessions of exposed participants carrying in-session exposure evidence.',
            scopeLockedReason: 'This metric filter already narrows to sessions carrying in-session exposure evidence.',
        },
    }

// What the tab says in place of a list the backend would refuse. Each entry carries its own
// `data-attr` so autocapture can count how often each state is reached, and so a story can wait
// for the one it renders.
const LIST_UNAVAILABLE_COPY: Record<ExperimentRecordingsListUnavailableReason, { dataAttr: string; copy: string }> = {
    not_launched: {
        dataAttr: 'experiment-recordings-unavailable-not-launched',
        copy: 'Launch the experiment to see recordings of participants.',
    },
    group_aggregated: {
        dataAttr: 'experiment-recordings-unavailable-group-aggregated',
        copy: "Recordings aren't available for this experiment. It counts groups rather than individual people, so recordings can't be matched to a variant.",
    },
    no_variants: {
        dataAttr: 'experiment-recordings-unavailable-no-variants',
        copy: "Recordings aren't available because this experiment's feature flag has no variants. Add variants to the flag to see recordings of participants.",
    },
}

// A session fires a metric's events, never the metric — the caption spells that out where it
// has the room the trigger doesn't.
const MODE_SUMMARIES: Record<ExperimentReplayMetricFilterMode, string> = {
    fired_all: 'fired events from every selected metric',
    fired_any: 'fired events from at least one selected metric',
    no_metric_activity: 'fired no events from the selected metrics',
    funnel_dropoff: "were exposed but didn't finish the funnel",
    funnel_completed: 'were exposed and finished the funnel',
}

/**
 * What the trigger says, so the current mode is readable without opening the menu.
 *
 * The count is always of *metrics* — that's what the checkboxes select. A metric can count
 * several events (a ratio counts two, a funnel one per step), so counting events here would
 * disagree with the number of boxes ticked. The mode verb carries the events half: what a
 * session fires is a metric's events, never the metric itself.
 */
function metricFilterTriggerLabel(
    mode: ExperimentReplayMetricFilterMode,
    selectedUuids: string[],
    options: ExperimentReplayMetricOption[]
): string {
    if (isFunnelMode(mode)) {
        const label = mode === 'funnel_completed' ? 'Finished funnel' : "Didn't finish funnel"
        const selected = options.find((option) => option.uuid === selectedUuids[0])
        return selected ? `${label}: ${selected.name}` : label
    }
    if (selectedUuids.length === 0) {
        // Never fall back to the neutral label for a non-default mode: the mode is on, and the
        // caption below is what explains why it isn't narrowing anything yet.
        return mode === 'fired_all' ? 'Metric events' : mode === 'fired_any' ? 'Fired any' : 'Fired none'
    }
    const metrics = pluralize(selectedUuids.length, 'metric')
    if (selectedUuids.length === 1) {
        // "all of" and "any of" one metric are the same question, and both quantifiers read as
        // noise next to a count of one.
        return mode === 'no_metric_activity' ? `Didn't fire ${metrics}` : `Fired ${metrics}`
    }
    if (mode === 'fired_any') {
        return `Fired any of ${metrics}`
    }
    if (mode === 'no_metric_activity') {
        return `Fired none of ${metrics}`
    }
    return `Fired all ${metrics}`
}

/** Why a picked mode isn't narrowing the list — it needs a selection it doesn't have yet. */
function unappliedModeReason(mode: ExperimentReplayMetricFilterMode): string {
    return isFunnelMode(mode)
        ? 'Pick a funnel metric whose last step can be matched to recordings. Showing every exposed recording until then.'
        : 'Pick at least one metric. Showing every exposed recording until then.'
}

/**
 * States what the server-computed set does and doesn't cover. Every clause is load-bearing: the
 * list is capped, the scan window ends at the last exposure and reaches back only so far from
 * there, and "in this session" is the honest unit — the experiment analysis counts per person over
 * the whole run window.
 */
function bucketCaption(bucket: ExperimentSessionBucket, experimentStartDate: string | null): string {
    const { session_ids, truncated, considered_metrics, excluded_metrics, filter_test_accounts, date_from, date_to } =
        bucket.response
    // The backend clamps the window start to the experiment's start, so a scan that reached the
    // whole run comes back with the two equal and leaves this null.
    const scannedFrom =
        date_from && experimentStartDate && dayjs(date_from).isAfter(dayjs(experimentStartDate))
            ? dayjs(date_from).format('MMM D, YYYY')
            : null
    if (session_ids.length === 0) {
        return scannedFrom
            ? `No recordings matched this filter between ${scannedFrom} and ${dayjs(date_to).format('MMM D, YYYY')}. Earlier sessions weren't checked.`
            : 'No recordings matched this filter.'
    }
    const sessions = truncated
        ? `Showing the ${session_ids.length} most recent recordings that`
        : `Showing ${pluralize(session_ids.length, 'recording')} that`
    const what =
        bucket.request.bucket === 'no_metric_activity'
            ? `fired no events from ${pluralize(considered_metrics.length, 'metric')} in this session`
            : bucket.request.bucket === 'fired_any' && considered_metrics.length === 1
              ? // One metric needs no quantifier, and naming it beats "at least one selected metric".
                `fired events from ${considered_metrics[0].metric_name} in this session`
              : `${MODE_SUMMARIES[bucket.request.bucket as ExperimentReplayMetricFilterMode]}, in this session`
    const caveats = [
        filter_test_accounts ? 'test accounts excluded' : null,
        excluded_metrics.length > 0
            ? `${pluralize(excluded_metrics.length, 'metric')} left out: ${excluded_metrics
                  .map((metric) => metric.metric_name)
                  .join(', ')}`
            : null,
    ].filter(Boolean)
    const scanNote = scannedFrom ? ` Sessions before ${scannedFrom} weren't checked.` : ''
    return `${sessions} ${what}.${caveats.length > 0 ? ` ${caveats.join('. ')}.` : ''}${scanNote}`
}

/** A metric row: its name, plus the events a session actually has to have fired to match it. */
function MetricOptionLabel({ option }: { option: ExperimentReplayMetricOption }): JSX.Element {
    return (
        <span className="flex min-w-0 items-baseline gap-2">
            <span className="truncate">{option.name}</span>
            {option.eventNames.length > 0 && (
                <span className="shrink-0 text-xs text-muted">{option.eventNames.join(', ')}</span>
            )}
        </span>
    )
}

export function ExperimentReplayTab({ experiment }: { experiment: Experiment }): JSX.Element {
    const logic = experimentReplayTabLogic({ experiment })
    const {
        effectiveVariantKey,
        effectiveExposureScope,
        exposureInSessionUnavailableReason,
        inSessionExposure,
        playlistHeldForChecks,
        variantKeys,
        recordingsFilters,
        effectiveMetricUuids,
        metricOptions,
        metricFilterMode,
        droppedMetricReason,
        filtersCustomized,
        sessionBucket,
        sessionBucketLoading,
        sessionBucketError,
        sessionBucketRequest,
        listUnavailableReason,
        listLoadError,
    } = useValues(logic)
    const {
        setSelectedVariantKey,
        setExposureScope,
        setMetricSelected,
        setMetricFilterMode,
        loadSessionBucket,
        playlistFiltersChanged,
        recordingsLoaded,
        recordingsLoadFailed,
        retryListLoad,
        recordingOpened,
    } = useActions(logic)
    const experimentScannerEnabled = useFeatureFlag('VISION_EXPERIMENT_SCANNER')
    // Which in-session copy applies, from the evidence kind the availability check resolved.
    const inSessionCopy =
        IN_SESSION_COPY[inSessionExposure ? (inSessionExposure.uses_stamped_fallback ? 'stamped' : 'event') : 'unknown']

    // One object feeds both the playlist below and the findMounted lookup, because the logic's
    // kea key is derived from these props: hand-duplicating them at the two sites would let the
    // keys drift apart, and a drifted key turns every highlight click into a silent no-op.
    const playlistLogicProps = { logicKey: `experiment-${experiment.id}`, updateSearchParams: false }
    // `findMounted` rather than building the logic: the playlist below owns it and passes props
    // this call doesn't have, so building it from here first would leave it mounted with a
    // half-built set of them. Before the playlist has rendered there is nothing to select anyway.
    const watchRecording = (sessionId: string): boolean => {
        const playlist = sessionRecordingsPlaylistLogic.findMounted(playlistLogicProps)
        if (!playlist) {
            return false
        }
        playlist.actions.setSelectedRecordingId(sessionId)
        return true
    }
    // The button that calls this only renders under a failed list, so the playlist below it is
    // mounted. Guarded anyway, because nothing in the type keeps it that way.
    const retryList = (): void => {
        retryListLoad()
        sessionRecordingsPlaylistLogic.findMounted(playlistLogicProps)?.actions.loadSessionRecordings()
    }

    // The variant switcher, the scope control and the metric filter all describe a list, so they
    // are meaningless without one. Placed after every hook, as the draft case always was.
    if (listUnavailableReason !== null) {
        const { dataAttr, copy } = LIST_UNAVAILABLE_COPY[listUnavailableReason]
        return (
            <div data-attr={dataAttr}>
                <LemonBanner type="info">{copy}</LemonBanner>
            </div>
        )
    }

    // Selectable metrics render as checkboxes. The rest move to labelled sections that explain
    // once, via a section tooltip, why they can't be matched — instead of repeating the same
    // reason on every row. One section per distinct reason, since metrics can be unmatchable for
    // different reasons (server-side events, a retention window, data-warehouse-only sources, or
    // simply not being a funnel while the drop-off mode is on).
    const linkableMetricOptions = metricOptions.filter(
        (option) => !option.unlinkable && (!isFunnelMode(metricFilterMode) || option.dropoffReason === null)
    )
    const unselectableOptionsByReason = new Map<string, ExperimentReplayMetricOption[]>()
    for (const option of metricOptions) {
        const reason = option.unlinkable
            ? option.unlinkableReason
            : isFunnelMode(metricFilterMode)
              ? option.dropoffReason
              : null
        if (reason) {
            unselectableOptionsByReason.set(reason, [...(unselectableOptionsByReason.get(reason) ?? []), option])
        }
    }

    // Both client-side modes narrow the list themselves, and the trigger label already says which
    // metric they narrowed it by, so the caption has nothing left to add once one is picked.
    const clientSideFilterApplied =
        !sessionBucketRequest &&
        (metricFilterMode === 'fired_all' || metricFilterMode === 'funnel_completed') &&
        effectiveMetricUuids.length > 0

    return (
        <div data-attr="experiment-recordings-tab">
            {experimentScannerEnabled && (
                <ExperimentScannerEntryPoint experiment={experiment} variantKey={effectiveVariantKey} />
            )}
            <div className="mb-2 flex flex-wrap gap-2">
                <LemonSegmentedButton
                    size="small"
                    value={effectiveVariantKey ?? ALL_VARIANTS}
                    onChange={(value) => setSelectedVariantKey(value === ALL_VARIANTS ? null : value)}
                    options={[
                        { value: ALL_VARIANTS, label: 'All' },
                        ...variantKeys.map((key) => ({ value: key, label: <VariantTag variantKey={key} /> })),
                    ]}
                />
                <LemonSegmentedButton
                    size="small"
                    value={effectiveExposureScope}
                    onChange={(value) => setExposureScope(value)}
                    disabledReason={sessionBucketRequest !== null ? inSessionCopy.scopeLockedReason : undefined}
                    options={[
                        {
                            value: 'in_session' as const,
                            label: 'Exposed in session',
                            tooltip: inSessionCopy.tooltip,
                            disabledReason: exposureInSessionUnavailableReason ?? undefined,
                            'data-attr': 'experiment-recordings-exposure-scope-in-session',
                        },
                        {
                            value: 'all_exposed' as const,
                            label: 'All sessions',
                            tooltip:
                                'Every session of exposed participants from their first exposure onward, including sessions without the exposure event.',
                            'data-attr': 'experiment-recordings-exposure-scope-all',
                        },
                    ]}
                />
                {metricOptions.length > 0 && (
                    <DropdownMenu>
                        <DropdownMenuTrigger
                            render={
                                <LemonButton
                                    size="small"
                                    type="secondary"
                                    sideIcon={<IconChevronDown />}
                                    tooltip="Narrow the list by what fired in each session. Whether a session fired a metric's events can differ from what the experiment analysis counts."
                                    data-attr="experiment-recordings-metric-filter"
                                />
                            }
                        >
                            {metricFilterTriggerLabel(metricFilterMode, effectiveMetricUuids, metricOptions)}
                        </DropdownMenuTrigger>
                        <DropdownMenuContent align="start" className="min-w-fit max-w-100">
                            <div className="p-1">
                                <LemonSegmentedButton
                                    size="xsmall"
                                    fullWidth
                                    value={metricFilterMode}
                                    onChange={(value) => setMetricFilterMode(value)}
                                    options={EXPERIMENT_RECORDING_MODE_OPTIONS}
                                />
                            </div>
                            <DropdownMenuSeparator />
                            {linkableMetricOptions.map((option) => (
                                <DropdownMenuCheckboxItem
                                    key={option.uuid}
                                    checked={effectiveMetricUuids.includes(option.uuid)}
                                    onCheckedChange={(checked: boolean) => setMetricSelected(option.uuid, checked)}
                                    closeOnClick={false}
                                    data-attr="experiment-recordings-metric-option"
                                >
                                    <MetricOptionLabel option={option} />
                                </DropdownMenuCheckboxItem>
                            ))}
                            {[...unselectableOptionsByReason.entries()].map(([reason, options], index) => (
                                // Fragment, not a wrapper element: the separator, label, and items
                                // must stay direct children of the menu for keyboard nav and ARIA.
                                <Fragment key={reason}>
                                    {(linkableMetricOptions.length > 0 || index > 0) && <DropdownMenuSeparator />}
                                    {/* Quill's DropdownMenuLabel renders a Base UI GroupLabel, which must
                                        live inside a DropdownMenuGroup or it throws at render. */}
                                    <DropdownMenuGroup>
                                        <DropdownMenuLabel inset className="flex items-center gap-1">
                                            {reason === NOT_A_FUNNEL_REASON
                                                ? 'Needs a funnel metric'
                                                : "Can't match to recordings"}
                                            <Tooltip title={reason}>
                                                <IconInfo className="size-3 shrink-0" />
                                            </Tooltip>
                                        </DropdownMenuLabel>
                                        {options.map((option) => (
                                            // Informational only — not selectable. The section label above
                                            // carries the explanation shared by this section's metrics.
                                            <DropdownMenuItem
                                                key={option.uuid}
                                                inset
                                                disabled
                                                data-attr="experiment-recordings-metric-option"
                                            >
                                                <MetricOptionLabel option={option} />
                                            </DropdownMenuItem>
                                        ))}
                                    </DropdownMenuGroup>
                                </Fragment>
                            ))}
                        </DropdownMenuContent>
                    </DropdownMenu>
                )}
                <ExperimentBehaviorComparisonToggle experiment={experiment} />
            </div>
            {/* The default mode also uses the endpoint for a single multi-source metric, so the
                caption follows the request, not the mode. The dropped-metric caption claims a whole
                population, so a filter the viewer added in the playlist bar makes it wrong and takes
                it away. The telemetry nulls the reason on the same condition. */}
            <div className="mb-2 flex flex-wrap items-center gap-2 text-xs text-secondary">
                {/* First, because a list that failed makes every other caption moot: none of them
                    describes a population the viewer can see. The retry is offered whatever the
                    status, unlike the shelf above, which shows a 400 as a plain answer: the tab
                    now states the refusals it can foresee instead of sending the list, so the
                    ones that reach here pass once the exposures finish computing. */}
                {listLoadError !== null ? (
                    <>
                        <span data-attr="experiment-recordings-list-error-caption">
                            Couldn't load recordings: {listLoadError.detail}
                        </span>
                        <LemonButton
                            size="xsmall"
                            type="secondary"
                            onClick={retryList}
                            data-attr="experiment-recordings-list-retry"
                        >
                            Try again
                        </LemonButton>
                    </>
                ) : clientSideFilterApplied ? null : droppedMetricReason && !filtersCustomized ? (
                    <span data-attr="experiment-recordings-dropped-metric-caption">
                        {METRIC_UNSELECTABLE_COPY[droppedMetricReason].onTab}
                    </span>
                ) : !sessionBucketRequest && metricFilterMode === 'fired_all' ? (
                    <span data-attr="experiment-recordings-population-caption">
                        {effectiveExposureScope === 'in_session' ? inSessionCopy.caption : ALL_EXPOSED_CAPTION}
                    </span>
                ) : !sessionBucketRequest ? (
                    <span>{unappliedModeReason(metricFilterMode)}</span>
                ) : sessionBucketError !== null ? (
                    <>
                        <span>Couldn't work out which sessions match this filter: {sessionBucketError}</span>
                        <LemonButton size="xsmall" type="secondary" onClick={() => loadSessionBucket()}>
                            Try again
                        </LemonButton>
                    </>
                ) : sessionBucketLoading || !sessionBucket ? (
                    <span>Finding matching sessions…</span>
                ) : (
                    <span data-attr="experiment-recordings-bucket-caption">
                        {bucketCaption(sessionBucket, experiment.start_date ?? null)}
                    </span>
                )}
            </div>
            <ExperimentBehaviorComparison experiment={experiment} onWatchRecording={watchRecording} />
            <div className="SessionRecordingPlaylistHeightWrapper">
                {playlistHeldForChecks ? (
                    // A persisted in-session choice waits for the availability and linkability
                    // checks: mounted now, the playlist would fire the heavy all-sessions listing
                    // only to replace it when the scope confirms and the filters flip.
                    <LemonSkeleton className="h-full" active />
                ) : (
                    <SessionRecordingsPlaylist
                        {...playlistLogicProps}
                        analyticsSource="experiment-recordings-tab"
                        filters={recordingsFilters}
                        // The tab's own controls own these filters, so the filter bar resets to them
                        // rather than to replay's defaults, which would list people outside the
                        // experiment under the variant's label.
                        resetToCallerFilters
                        onFiltersChange={(filters) => playlistFiltersChanged(filters)}
                        onRecordingsLoaded={(recordings, isFirstPage) => recordingsLoaded(recordings, isFirstPage)}
                        onRecordingsLoadFailed={(error, isFirstPage) => recordingsLoadFailed(error, isFirstPage)}
                        onRecordingSelected={(recordingId) => recordingOpened(recordingId)}
                        listEmptyState={<ExperimentRecordingsListEmptyState experiment={experiment} />}
                    />
                )}
            </div>
        </div>
    )
}