: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 { 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>
)
}