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.

27.4 KB
Raw Blame
import { useActions, useValues } from 'kea'
import { router } from 'kea-router'
import { useEffect, useRef } from 'react'

import { IconCollapse, IconExpand, IconExternal, IconInfo, IconMinus, IconWarning } from '@posthog/icons'

import { dayjs } from 'lib/dayjs'
import { LemonButton } from 'lib/lemon-ui/LemonButton'
import { LemonCollapse } from 'lib/lemon-ui/LemonCollapse'
import { LemonSkeleton } from 'lib/lemon-ui/LemonSkeleton'
import { LemonTag, LemonTagType } from 'lib/lemon-ui/LemonTag'
import { Link } from 'lib/lemon-ui/Link'
import { Tooltip } from 'lib/lemon-ui/Tooltip'
import { colonDelimitedDuration, humanFriendlyDuration } from 'lib/utils/durations'
import { addProductIntentForCrossSell } from 'lib/utils/product-intents'
import { urls } from 'scenes/urls'

import { ProductIntentContext, ProductKey } from '~/queries/schema/schema-general'

import {
    type ExperimentSessionContextItemApi,
    type ExperimentSessionMetricHitApi,
    type ExperimentSessionMetricSourceHitApi,
    SourceRoleEnumApi,
} from 'products/experiments/frontend/generated/api.schemas'

import {
    isControlVariant,
    sessionRecordingExperimentContextLogic,
} from '../player-meta/sessionRecordingExperimentContextLogic'
import { sessionRecordingPlayerLogic } from '../sessionRecordingPlayerLogic'

function variantTooltip(item: ExperimentSessionContextItemApi): string {
    return item.multiple_variants
        ? `This session saw multiple variants (${item.variants_seen.join(', ')}) of ${item.experiment_name}. The experiment analysis counts exposure per person, which can differ from a single session.`
        : `This session saw variant "${item.variant}" of ${item.experiment_name}. The experiment analysis counts exposure per person, which can differ from a single session.`
}

function VariantTag({ item }: { item: ExperimentSessionContextItemApi }): JSX.Element | null {
    // Metric-only sessions (a future backend addition) carry no variant — render no tag rather
    // than an empty one.
    if (!item.variant && item.variants_seen.length === 0) {
        return null
    }
    const type: LemonTagType = item.multiple_variants ? 'warning' : isControlVariant(item) ? 'muted' : 'highlight'
    return (
        <Tooltip title={variantTooltip(item)}>
            <LemonTag type={type} icon={item.multiple_variants ? <IconWarning /> : undefined} className="shrink-0">
                {item.multiple_variants ? `${item.variants_seen.length} variants` : item.variant}
            </LemonTag>
        </Tooltip>
    )
}

// A busy metric can carry up to the API's 50-event cap; rendering them all inline floods the narrow
// sidebar. Show a sample of seek points and note the rest as a static count (no inline expansion —
// the full picture lives on the recordings tab's metric filter and the experiment's own analysis).
const MAX_INLINE_METRIC_EVENTS = 15

function MetricEventChips({
    seekPoints,
    onSeek,
}: {
    seekPoints: { ms: number; offsetSeconds: number }[]
    onSeek: (timestampMs: number) => void
}): JSX.Element {
    const shown = seekPoints.slice(0, MAX_INLINE_METRIC_EVENTS)
    const hiddenCount = seekPoints.length - shown.length
    return (
        <div className="flex flex-row flex-wrap gap-1 pl-3">
            {shown.map(({ ms, offsetSeconds }) => (
                <Link
                    key={ms}
                    className="font-mono tabular-nums"
                    title="Jump to this event"
                    onClick={() => onSeek(ms)}
                    data-attr="replay-experiment-context-jump-to-metric-event"
                >
                    {colonDelimitedDuration(offsetSeconds, 2)}
                </Link>
            ))}
            {hiddenCount > 0 ? <span className="text-muted">+{hiddenCount} more</span> : null}
        </div>
    )
}

// What each source is to its metric. A metric's own name says nothing about which side of it fired,
// and for most metric types that distinction is the difference between "they converted" and "they
// took the first step" — so it's spelled out rather than left to the reader.
function sourceLabel(source: ExperimentSessionMetricSourceHitApi): string | null {
    switch (source.source_role) {
        case SourceRoleEnumApi.Step:
            return source.source_total > 1
                ? `Step ${source.source_index + 1} of ${source.source_total}`
                : // A one-step funnel is just its event; the step number would be noise.
                  null
        case SourceRoleEnumApi.Numerator:
            return 'Numerator'
        case SourceRoleEnumApi.Denominator:
            return 'Denominator'
        case SourceRoleEnumApi.RetentionStart:
            return 'Start event'
        case SourceRoleEnumApi.RetentionCompletion:
            return 'Return event'
        default:
            return null
    }
}

const SESSION_SCOPE_CAVEAT =
    "What this session saw, and the metric events that fired in it. These are events a metric counts, not its result: whether they count for this person depends on their exposure and the metric's window, which the experiment analysis decides across all their sessions."

function MetricSourceRow({
    source,
    recordingStartMs,
    isWithinRecording,
    onSeek,
}: {
    source: ExperimentSessionMetricSourceHitApi
    recordingStartMs: number | null
    isWithinRecording: (timestampMs: number | null) => timestampMs is number
    onSeek: (timestampMs: number) => void
}): JSX.Element {
    // Only in-bounds occurrences are seekable — the backend's ±1h slack can place some outside the
    // playable recording. Each becomes a chip labelled with its offset from the recording start.
    const seekPoints = source.timestamps
        .map((timestamp) => dayjs(timestamp).valueOf())
        .filter((ms): ms is number => isWithinRecording(ms))
        .map((ms) => ({ ms, offsetSeconds: recordingStartMs != null ? Math.floor((ms - recordingStartMs) / 1000) : 0 }))
    const label = sourceLabel(source)

    return (
        <div className="flex flex-col gap-y-0.5 min-w-0">
            {label ? (
                <span className="pl-3 truncate text-muted">
                    {label} · {source.source_name}
                </span>
            ) : null}
            {seekPoints.length === 0 ? (
                <span className="pl-3 text-muted">Fired outside the recording</span>
            ) : (
                <MetricEventChips seekPoints={seekPoints} onSeek={onSeek} />
            )}
        </div>
    )
}

function MetricHitRow({
    hit,
    recordingStartMs,
    isWithinRecording,
    onSeek,
}: {
    hit: ExperimentSessionMetricHitApi
    recordingStartMs: number | null
    isWithinRecording: (timestampMs: number | null) => timestampMs is number
    onSeek: (timestampMs: number) => void
}): JSX.Element {
    // Metrics past the scan's aggregate ceiling carry no breakdown; their own totals are then the
    // only thing to show, unqualified — which is exactly what the 'source' role renders.
    const sources: ExperimentSessionMetricSourceHitApi[] =
        hit.sources.length > 0
            ? hit.sources
            : [
                  {
                      source_role: SourceRoleEnumApi.Source,
                      source_name: hit.metric_name,
                      source_index: 0,
                      source_total: 1,
                      event_count: hit.event_count,
                      first_timestamp: hit.first_timestamp,
                      timestamps: hit.timestamps,
                  },
              ]

    return (
        // Indented to start under the exposure-time column, so the block reads as belonging to the
        // experiment row above it rather than as another top-level row.
        <div className="flex flex-col gap-y-0.5 min-w-0 pl-8 text-xs">
            <span className="truncate">{hit.metric_name}</span>
            {sources.map((source) => (
                <MetricSourceRow
                    key={`${source.source_role}-${source.source_index}`}
                    source={source}
                    recordingStartMs={recordingStartMs}
                    isWithinRecording={isWithinRecording}
                    onSeek={onSeek}
                />
            ))}
        </div>
    )
}

function OpenExperimentButton({ item }: { item: ExperimentSessionContextItemApi }): JSX.Element {
    return (
        <LemonButton
            size="xsmall"
            type="tertiary"
            icon={<IconExternal />}
            to={urls.experiment(item.experiment_id)}
            targetBlank
            hideExternalLinkIcon
            className="shrink-0"
            tooltip="Open experiment in a new tab"
            data-attr="replay-experiment-context-experiment-link"
            onClick={() => {
                void addProductIntentForCrossSell({
                    from: ProductKey.SESSION_REPLAY,
                    to: ProductKey.EXPERIMENTS,
                    intent_context: ProductIntentContext.SESSION_REPLAY_EXPERIMENT_LINK_CLICKED,
                    metadata: { experiment_id: item.experiment_id },
                })
            }}
        />
    )
}

// The person's counted first exposure may lie in an earlier session (the experiment analysis counts
// exposure per person across the whole run window), so an in-session metric event can precede this one.
const EXPOSURE_CAVEAT =
    'They may have been enrolled in an earlier session, so metric events can fire before this moment.'

type ExposurePlacement = 'before' | 'inside' | 'after'

interface ExposureSeek {
    // Signed offset against the nearest captured frame: negative before the first frame, positive
    // after the last one, and the offset from the start for an in-window exposure.
    offsetMs: number
    placement: ExposurePlacement
    // The frame we can show: the exposure moment when it is in window, else the closest captured
    // frame (the first for a before-start exposure, the last for an after-end one).
    seekTargetMs: number
}

// The recorder can boot after the exposure event fired, or stop before it, so the exposure can fall
// outside the captured frames. Place it against the window and pick the closest frame to jump to.
export function computeExposureSeek(
    exposedAtMs: number,
    recordingStartMs: number,
    recordingEndMs: number | null
): ExposureSeek {
    if (exposedAtMs < recordingStartMs) {
        return { offsetMs: exposedAtMs - recordingStartMs, placement: 'before', seekTargetMs: recordingStartMs }
    }
    if (recordingEndMs != null && exposedAtMs > recordingEndMs) {
        return { offsetMs: exposedAtMs - recordingEndMs, placement: 'after', seekTargetMs: recordingEndMs }
    }
    return { offsetMs: exposedAtMs - recordingStartMs, placement: 'inside', seekTargetMs: exposedAtMs }
}

interface ExposureTimeProps {
    offsetMs: number
    placement: ExposurePlacement
    onSeek: () => void
}

// The label carries the signed offset so an out-of-window exposure reads as real, not as 00:00. A
// before-start or after-end jump lands on the closest captured frame rather than the exposure
// moment, so the tooltip names the gap and says what the jump does.
function ExposureTime({ offsetMs, placement, onSeek }: ExposureTimeProps): JSX.Element {
    // An in-window offset is a playback position, so it floors to match the player clock. An
    // out-of-window gap rounds up instead: flooring one under a second would print 00:00, the same
    // "no exposure here" reading this column exists to correct.
    const seconds = placement === 'inside' ? Math.floor(offsetMs / 1000) : Math.ceil(Math.abs(offsetMs) / 1000)
    const magnitude = colonDelimitedDuration(seconds, null)
    const label = placement === 'before' ? `-${magnitude}` : placement === 'after' ? `+${magnitude}` : magnitude
    // The same rounded value as the label, so the spelled-out gap and the compact offset agree.
    const gap = humanFriendlyDuration(seconds)
    const tooltip =
        placement === 'before'
            ? `The exposure fired ${gap} before the replay begins. Jumps to the first frame.`
            : placement === 'after'
              ? `The exposure fired ${gap} after the replay ends. Jumps to the last frame.`
              : `Jump to the first exposure in this session. ${EXPOSURE_CAVEAT}`
    return (
        <Tooltip title={tooltip}>
            <Link
                className="text-xs tabular-nums shrink-0 min-w-10 text-right"
                onClick={onSeek}
                data-attr="replay-experiment-context-jump-to-first-exposure"
            >
                {label}
            </Link>
        </Tooltip>
    )
}

// The experiment analysis counts exposure events, and this session has none: that is the one claim
// that holds wherever the viewer came from. The copy must not reference the recordings tab's list,
// because when the exposure event is server-side that tab's in-session scope falls back to listing
// flag-active sessions, and enrolled-only sessions are then exactly what its list shows.
const NOT_EXPOSED_CAVEAT =
    "The flag was active in this session, but no exposure event was captured here, so this session isn't where the experiment analysis counted this person's exposure."

// The caveat hangs off an info icon, like the section header's: it's far too long to sit inline in a
// sidebar this narrow.
function NotExposedInSessionLabel({ children, className }: { children: string; className?: string }): JSX.Element {
    return (
        <Tooltip title={NOT_EXPOSED_CAVEAT}>
            {/* The icon trails the text inline so it stays with the last word when the label wraps. */}
            <span className={className} data-attr="replay-experiment-context-not-exposed">
                {children}
                <IconInfo className="inline-block ml-1 size-3 text-secondary" />
            </span>
        </Tooltip>
    )
}

function ExperimentContextRow({
    item,
    exposure,
    leading,
}: {
    item: ExperimentSessionContextItemApi
    // The exposure timestamp column: its signed offset and the jump to the closest captured frame.
    // Absent for a row with no exposure (enrolled-only), or before the recording window resolves.
    exposure?: ExposureTimeProps | null
    // Leading slot rendered before the timestamp — the metric-events expand toggle, or a same-width
    // spacer so the timestamp and name columns line up across rows.
    leading?: JSX.Element | null
}): JSX.Element {
    // The name is a plain label in its own flex-1 truncate box (keeping the variant tag and
    // open-experiment icon right-aligned). Seeking lives on the timestamp; opening the experiment on
    // the icon — so the name identifies the row rather than pretending to be a control.
    return (
        <div className="flex flex-row items-center gap-x-2 min-w-0">
            {leading}
            {exposure ? <ExposureTime {...exposure} /> : null}
            <div className="flex-1 min-w-0 truncate">{item.experiment_name}</div>
            <VariantTag item={item} />
            <OpenExperimentButton item={item} />
        </div>
    )
}

// The experiments scene keeps /experiments/<numeric id> in the path even while the player is embedded
// in its recordings tab, so the experiment the viewer came from is recoverable from the route. Returns
// null off that scene (the generic replay page), where there's no experiment to pin.
function experimentIdFromPath(pathname: string): number | null {
    const match = pathname.match(/\/experiments\/(\d+)/)
    return match ? Number(match[1]) : null
}

export function PlayerSidebarExperimentsSection(): JSX.Element | null {
    const { logicProps, sessionPlayerData } = useValues(sessionRecordingPlayerLogic)
    const { seekToTime } = useActions(sessionRecordingPlayerLogic)
    const experimentContextLogic = sessionRecordingExperimentContextLogic({
        sessionRecordingId: logicProps.sessionRecordingId,
    })
    const { seenItems, enrolledItems, hasExperimentContext, expandedExperimentIds, experimentContextLoading } =
        useValues(experimentContextLogic)
    const { setExperimentExpanded } = useActions(experimentContextLogic)
    const { location } = useValues(router)

    // The experiment the viewer arrived from: their recordings tab keeps the URL on /experiments/<id>
    // while the player is embedded, so we can pin it and default-expand its metrics. Null on the
    // generic replay page, where there's no experiment context.
    const currentExperimentId = experimentIdFromPath(location.pathname)
    const currentItem =
        currentExperimentId != null
            ? ([...seenItems, ...enrolledItems].find((item) => item.experiment_id === currentExperimentId) ?? null)
            : null

    // Default-expand the current experiment's metrics on load so they're visible right away — but only
    // once per experiment. Auto-expanding again on a later metric-count change (e.g. a context refetch)
    // would silently reopen a row the viewer deliberately collapsed, so a ref tracks who's been done.
    const currentExpandableId = currentItem?.experiment_id
    const currentMetricCount = currentItem?.metrics_in_session.length ?? 0
    const autoExpandedIds = useRef<Set<number>>(new Set())
    useEffect(() => {
        if (
            currentExpandableId != null &&
            currentMetricCount > 0 &&
            !autoExpandedIds.current.has(currentExpandableId)
        ) {
            autoExpandedIds.current.add(currentExpandableId)
            setExperimentExpanded(currentExpandableId, true)
        }
    }, [currentExpandableId, currentMetricCount, setExperimentExpanded])

    if (experimentContextLoading && !hasExperimentContext) {
        if (currentExperimentId == null) {
            return null
        }
        return (
            <div
                className="rounded border bg-surface-primary px-2 py-1 flex flex-col gap-y-1"
                data-attr="replay-experiment-context-overview-loading"
            >
                <h4 className="font-semibold text-xs mb-0">Experiments</h4>
                <LemonSkeleton className="h-4 w-2/3" />
                <LemonSkeleton className="h-4 w-1/2" />
            </div>
        )
    }

    if (!hasExperimentContext) {
        return null
    }

    const recordingStartMs = sessionPlayerData?.start?.valueOf() ?? null
    // seekToTime rather than seekToTimestamp, because only seekToTime consumes a pending
    // auto-skip. A click made before that skip fires would otherwise be overridden by it.
    const seekToTimestamp = (timestampMs: number): void => {
        if (recordingStartMs != null) {
            seekToTime(timestampMs - recordingStartMs)
        }
    }
    const recordingEndMs =
        recordingStartMs != null && sessionPlayerData?.durationMs != null
            ? recordingStartMs + sessionPlayerData.durationMs
            : null
    // The backend can return timestamps from its ±1h slack around the recording; seeking to an
    // out-of-bounds time silently clamps to a boundary, so only offer jumps for moments that fall
    // inside the playable recording.
    const isWithinRecording = (timestampMs: number | null): timestampMs is number =>
        timestampMs != null &&
        recordingStartMs != null &&
        recordingEndMs != null &&
        timestampMs >= recordingStartMs &&
        timestampMs <= recordingEndMs

    // Reserve a leading gutter on every seen row (so timestamps and names align) only when at least
    // one experiment has an expand toggle; with nothing expandable, keep the list flush-left.
    const anySeenExpandable = seenItems.some((seenItem) => seenItem.metrics_in_session.length > 0)

    // One seen experiment rendered in full: its timestamp seek control, the expand toggle (or the
    // no-metrics marker), and — when expanded — its metric hits. Extracted so the pinned "current"
    // experiment reuses the exact same treatment as the list rows below it.
    const renderSeenRow = (item: ExperimentSessionContextItemApi): JSX.Element => {
        const exposedAtMs = item.first_exposure_timestamp ? dayjs(item.first_exposure_timestamp).valueOf() : null
        // The exposure needs the resolved recording start to place it and to jump. Without it there
        // is no offset to show and nowhere to seek, so the row renders without a timestamp column.
        const seek =
            exposedAtMs != null && recordingStartMs != null
                ? computeExposureSeek(exposedAtMs, recordingStartMs, recordingEndMs)
                : null
        const hasMetrics = item.metrics_in_session.length > 0
        const isExpanded = expandedExperimentIds.includes(item.experiment_id)
        return (
            <div key={item.experiment_id} className="flex flex-col gap-y-0.5 min-w-0">
                <ExperimentContextRow
                    item={item}
                    exposure={
                        seek
                            ? {
                                  offsetMs: seek.offsetMs,
                                  placement: seek.placement,
                                  onSeek: () => seekToTimestamp(seek.seekTargetMs),
                              }
                            : null
                    }
                    leading={
                        // -me-1.5 pulls the timestamp back toward the toggle so the icon and time read
                        // as one column (and line up better with the expanded metrics), without
                        // tightening the timestamp-to-name gap.
                        anySeenExpandable ? (
                            <div className="shrink-0 flex w-[1.625rem] items-center justify-center -me-1.5">
                                {hasMetrics ? (
                                    <LemonButton
                                        size="xsmall"
                                        icon={isExpanded ? <IconCollapse /> : <IconExpand />}
                                        onClick={() => setExperimentExpanded(item.experiment_id, !isExpanded)}
                                        tooltip={
                                            isExpanded
                                                ? 'Hide metric events'
                                                : `Show metric events (${item.metrics_in_session.length})`
                                        }
                                        data-attr="replay-experiment-context-expand-metrics"
                                    />
                                ) : (
                                    // Same component and size as the expand button so the marker has an
                                    // identical box, border, and tooltip hover target. disabledReason keeps
                                    // it hoverable (LemonButton disables via aria-disabled, not the native
                                    // attribute) while signalling there's nothing to expand.
                                    <LemonButton
                                        size="xsmall"
                                        icon={<IconMinus />}
                                        disabledReason="No experiment metric fired in this session"
                                        data-attr="replay-experiment-context-no-metrics"
                                    />
                                )}
                            </div>
                        ) : undefined
                    }
                />
                {isExpanded && hasMetrics ? (
                    <div className="flex flex-col gap-y-0.5">
                        {item.metrics_in_session.map((hit) => (
                            <MetricHitRow
                                key={hit.metric_uuid}
                                hit={hit}
                                recordingStartMs={recordingStartMs}
                                isWithinRecording={isWithinRecording}
                                onSeek={seekToTimestamp}
                            />
                        ))}
                    </div>
                ) : null}
            </div>
        )
    }

    const otherSeenItems = currentItem
        ? seenItems.filter((item) => item.experiment_id !== currentItem.experiment_id)
        : seenItems
    const otherEnrolledItems = currentItem
        ? enrolledItems.filter((item) => item.experiment_id !== currentItem.experiment_id)
        : enrolledItems
    // Pin the current experiment only when there are other experiments to stand out from — a lone
    // "Viewing" row is just clutter. Otherwise it stays inline in the normal lists below.
    const pinnedItem = currentItem && (otherSeenItems.length > 0 || otherEnrolledItems.length > 0) ? currentItem : null
    const listSeenItems = pinnedItem ? otherSeenItems : seenItems
    const listEnrolledItems = pinnedItem ? otherEnrolledItems : enrolledItems

    return (
        <div
            className="rounded border bg-surface-primary px-2 py-1 flex flex-col gap-y-1"
            data-attr="replay-experiment-context-overview"
        >
            <h4 className="font-semibold text-xs mb-0 flex items-center gap-1">
                Experiments
                {/* One icon for the whole section: the caveat applies to every row and every metric
                    under it, so repeating it per metric name would fire a tooltip on almost any
                    hover in here. */}
                <Tooltip title={SESSION_SCOPE_CAVEAT}>
                    <IconInfo className="size-3 shrink-0 text-secondary" />
                </Tooltip>
            </h4>

            {pinnedItem ? (
                <div className="flex flex-col gap-y-0.5" data-attr="replay-experiment-context-current">
                    <span className="text-[0.625rem] font-semibold uppercase tracking-wider text-secondary">
                        Viewing
                    </span>
                    {pinnedItem.first_exposure_timestamp != null ? (
                        renderSeenRow(pinnedItem)
                    ) : (
                        <>
                            <ExperimentContextRow item={pinnedItem} />
                            {/* Pinning lifts the row out of the enrolled group below, and with it out of
                                that group's label, so the row has to carry the distinction itself. */}
                            <NotExposedInSessionLabel className="w-fit text-xs text-muted">
                                Not exposed in this session
                            </NotExposedInSessionLabel>
                        </>
                    )}
                </div>
            ) : null}

            {pinnedItem && listSeenItems.length > 0 ? (
                <span className="text-[0.625rem] font-semibold uppercase tracking-wider text-muted">
                    Other experiments in this session
                </span>
            ) : null}

            {listSeenItems.map((item) => renderSeenRow(item))}

            {listEnrolledItems.length > 0 ? (
                <LemonCollapse
                    embedded
                    size="small"
                    panels={[
                        {
                            key: 'enrolled',
                            header: (
                                <NotExposedInSessionLabel>
                                    {`Also enrolled, not exposed in this session (${listEnrolledItems.length})`}
                                </NotExposedInSessionLabel>
                            ),
                            content: (
                                <div className="flex flex-col gap-y-1">
                                    {listEnrolledItems.map((item) => (
                                        <ExperimentContextRow key={item.experiment_id} item={item} />
                                    ))}
                                </div>
                            ),
                        },
                    ]}
                />
            ) : null}
        </div>
    )
}