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.7 KB
Raw Blame
import { useValues } from 'kea'

import { PropertyKeyInfo } from 'lib/components/PropertyKeyInfo'
import { LemonBanner, LemonBannerProps } from 'lib/lemon-ui/LemonBanner'
import { LemonButton } from 'lib/lemon-ui/LemonButton'
import { LemonCollapse } from 'lib/lemon-ui/LemonCollapse'
import { Spinner } from 'lib/lemon-ui/Spinner'

import { DiagnosisVerdict, ReplayCaptureDiagnosis, diagnoseReplayCapture } from '../utils/replayCaptureDiagnostics'
import { replayCaptureDiagnosticsPanelLogic } from './replayCaptureDiagnosticsPanelLogic'

type ReplayCaptureDiagnosticsPanelProps =
    | { eventProperties: Record<string, any>; sessionId?: undefined }
    | { sessionId: string; eventProperties?: undefined }

const TRIGGER_STATUS_EXPLANATIONS: Record<string, string> = {
    trigger_disabled: 'No trigger of this type is configured.',
    trigger_pending: 'A trigger is configured but has not yet matched on this session.',
    trigger_matched: 'The trigger fired, so recording was allowed to start.',
}

const RECORDING_STATUS_EXPLANATIONS: Record<string, string> = {
    active: 'The SDK is recording and producing snapshots.',
    buffering:
        'The SDK initialized but is waiting (for a trigger, duration, or remote config) before producing snapshots.',
    disabled: 'Recording is turned off, either in project settings or in the SDK config at runtime.',
    sampled: 'This session was included by the configured replay sample rate, so recording started.',
    paused: 'Recording is temporarily paused for this session.',
    lazy_loading: 'The SDK is still loading the recorder script before it can produce snapshots.',
    pending_config:
        'The SDK was waiting for recording settings from PostHog. Only posthog-js 1.356.1 to 1.358.0 report this.',
    awaiting_config: 'The SDK is waiting for recording settings from PostHog before it can start.',
    missing_config: 'The SDK could not load recording settings and stopped trying. Reload the page to start recording.',
    rrweb_error: 'The recorder failed to start, so no snapshots were produced. Check the browser console for errors.',
}

const START_REASON_EXPLANATIONS: Record<string, string> = {
    recording_initialized: 'Recording started as soon as the SDK initialized.',
    sampling_override: 'Recording started because the session was included by the sampling rules.',
    sampled_out: 'Recording was prevented because the session was excluded by sampling.',
    linked_flag_match: 'Recording started because a linked feature flag matched.',
}

const explainValue = (key: string, value: unknown): string | null => {
    switch (key) {
        case '$recording_status':
            return typeof value === 'string' ? (RECORDING_STATUS_EXPLANATIONS[value] ?? null) : null
        case '$session_recording_start_reason':
            return typeof value === 'string' ? (START_REASON_EXPLANATIONS[value] ?? null) : null
        case '$sdk_debug_replay_url_trigger_status':
        case '$sdk_debug_replay_event_trigger_status':
        case '$sdk_debug_replay_linked_flag_trigger_status':
            return typeof value === 'string' ? (TRIGGER_STATUS_EXPLANATIONS[value] ?? null) : null
        case '$sdk_debug_recording_script_not_loaded':
            return 'The SDK reported the recorder script was not loaded on the page, often caused by ad blockers.'
        case '$sdk_debug_rrweb_start_attempted':
            if (value === true) {
                return 'The SDK attempted to start the recorder.'
            }
            return value === false ? 'The SDK never attempted to start the recorder for this session.' : null
        case '$sdk_debug_rrweb_attached':
            if (value === true) {
                return 'The recorder is attached and capturing.'
            }
            return value === false ? 'The recorder is not attached, so no snapshots are being captured.' : null
        case '$sdk_debug_replay_trigger_groups_count':
            return 'The number of V2 trigger groups configured for this project.'
        case '$replay_override_sampling':
        case '$replay_override_linked_flag':
        case '$replay_override_url_trigger':
        case '$replay_override_event_trigger':
            return value === true ? 'Recording was force-started, ignoring this gating config.' : null
        default:
            return null
    }
}

function ExplainedSignalList({ signals }: { signals: Record<string, unknown> }): JSX.Element {
    const entries = Object.entries(signals)
    if (entries.length === 0) {
        return <div className="text-xs text-muted">No diagnostic signals on this event.</div>
    }
    return (
        <div className="text-xs deprecated-space-y-2">
            {entries.map(([key, value]) => {
                const explanation = explainValue(key, value)
                const display = typeof value === 'object' ? JSON.stringify(value) : String(value)
                return (
                    <div key={key} className="flex flex-col">
                        <div className="flex gap-2 items-baseline justify-between">
                            <span className="font-semibold">
                                <PropertyKeyInfo value={key} />
                            </span>
                            <pre className="text-primary-alt break-all mb-0">{display}</pre>
                        </div>
                        {explanation && <span className="text-muted italic pl-2">{explanation}</span>}
                    </div>
                )
            })}
        </div>
    )
}

const BANNER_TYPE_BY_VERDICT: Record<DiagnosisVerdict, LemonBannerProps['type']> = {
    captured: 'success',
    ad_blocked: 'warning',
    disabled: 'warning',
    trigger_pending: 'info',
    sampled_out: 'info',
    buffering_empty: 'info',
    recorder_error: 'warning',
    unknown: 'info',
}

function DiagnosisContent({ diagnosis }: { diagnosis: ReplayCaptureDiagnosis }): JSX.Element {
    return (
        <LemonBanner type={BANNER_TYPE_BY_VERDICT[diagnosis.verdict]} className="text-left">
            <div className="deprecated-space-y-2">
                <div className="font-semibold">{diagnosis.headline}</div>
                <ul className="list-disc pl-4 deprecated-space-y-1 text-xs">
                    {diagnosis.reasons.map((reason, idx) => (
                        <li key={idx}>{reason}</li>
                    ))}
                </ul>
                {diagnosis.suggestedActions.length > 0 && (
                    <div className="flex gap-2 flex-wrap">
                        {diagnosis.suggestedActions.map((action, idx) => (
                            <LemonButton
                                data-attr="replay-diagnostics-action"
                                key={idx}
                                type="secondary"
                                size="small"
                                to={action.to}
                                targetBlank={action.to?.startsWith('http')}
                            >
                                {action.label}
                            </LemonButton>
                        ))}
                    </div>
                )}
                {Object.keys(diagnosis.rawSignals).length > 0 && (
                    <LemonCollapse
                        size="small"
                        panels={[
                            {
                                key: 'raw-signals',
                                header: 'Raw diagnostic signals',
                                content: (
                                    <div className="max-h-[40vh] overflow-y-auto">
                                        <ExplainedSignalList signals={diagnosis.rawSignals} />
                                    </div>
                                ),
                            },
                        ]}
                    />
                )}
            </div>
        </LemonBanner>
    )
}

export function ReplayCaptureDiagnosticsPanel(props: ReplayCaptureDiagnosticsPanelProps): JSX.Element | null {
    if (props.eventProperties) {
        return <DiagnosisContent diagnosis={diagnoseReplayCapture(props.eventProperties)} />
    }

    return <SessionIdDiagnosticsPanel sessionId={props.sessionId} />
}

function SessionIdDiagnosticsPanel({ sessionId }: { sessionId: string }): JSX.Element | null {
    const { sessionEventProperties, sessionEventPropertiesLoading } = useValues(
        replayCaptureDiagnosticsPanelLogic({ sessionId })
    )

    if (sessionEventPropertiesLoading) {
        return (
            <div className="flex justify-center items-center p-4">
                <Spinner />
                <span className="ml-2 text-xs text-muted">Loading capture diagnostics…</span>
            </div>
        )
    }

    if (!sessionEventProperties) {
        return null
    }

    return <DiagnosisContent diagnosis={diagnoseReplayCapture(sessionEventProperties)} />
}