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.

16.0 KB
Raw Blame
import { MakeLogicType, actions, afterMount, connect, kea, listeners, path, props, selectors } from 'kea'
import { loaders } from 'kea-loaders'

import api from 'lib/api'
import { getSeriesColor } from 'lib/colors'
import { lemonToast } from 'lib/lemon-ui/LemonToast'
import { eventUsageLogic } from 'lib/utils/eventUsageLogic'
import { pluralize } from 'lib/utils/strings'
import { teamLogic } from 'scenes/teamLogic'

import {
    ExperimentMetric,
    ExperimentMetricTimeseries,
    ExperimentQueryResponse,
    ExperimentVariantResultBayesian,
    ExperimentVariantResultFrequentist,
} from '~/queries/schema/schema-general'
import { Experiment, ExperimentIdType } from '~/types'

import type { ExperimentMetricUnion } from '../../queries/schema/schema-general'
import { getVariantInterval } from './MetricsView/shared/utils'
import { getExperimentVariants } from './utils'

export interface ProcessedTimeseriesDataPoint {
    date: string
    value: number | null
    upper_bound: number | null
    lower_bound: number | null
    hasRealData: boolean
    number_of_samples?: number
    denominator_sum?: number
    significant?: boolean
}

export interface ProcessedChartData {
    labels: string[]
    processedData: ProcessedTimeseriesDataPoint[]
    /** When the timeseries was last computed (ISO string), shared across all data points. */
    computedAt: string | null
    /** Color of the variant's line, from the experiment's stable variant order. */
    variantColor: string
}

export interface ExperimentTimeseriesLogicProps {
    experiment: Experiment
    metric: ExperimentMetric | undefined
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface experimentTimeseriesLogicValues {
    currentProjectId: number | string // teamLogic
    chartData: (variantKey: string) => ProcessedChartData | null
    hasTimeseriesData: boolean
    isRecalculating: boolean
    processedVariantData: (variantKey: string) => ProcessedTimeseriesDataPoint[]
    progressMessage: string | null
    timeseries: ExperimentMetricTimeseries | null
    timeseriesLoading: boolean
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface experimentTimeseriesLogicActions {
    reportExperimentTimeseriesRecalculated: (
        experimentId: ExperimentIdType,
        metric: ExperimentMetricUnion
    ) => {
        experimentId: ExperimentIdType
        metric: ExperimentMetricUnion
    } // eventUsageLogic
    loadTimeseries: ({ metric }: { metric: ExperimentMetric }) => {
        metric: ExperimentMetric
    }
    loadTimeseriesFailure: (
        error: string,
        errorObject?: any
    ) => {
        error: string
        errorObject?: any
    }
    loadTimeseriesSuccess: (
        timeseries: ExperimentMetricTimeseries | null,
        payload?: {
            metric: ExperimentMetric
        }
    ) => {
        timeseries: ExperimentMetricTimeseries | null
        payload?: {
            metric: ExperimentMetric
        }
    }
    recalculateTimeseries: ({ metric }: { metric: ExperimentMetric }) => {
        metric: ExperimentMetricUnion
    }
    recalculateTimeseriesFailure: (
        error: string,
        errorObject?: any
    ) => {
        error: string
        errorObject?: any
    }
    recalculateTimeseriesSuccess: (
        timeseries: null,
        payload?: {
            metric: ExperimentMetricUnion
        }
    ) => {
        timeseries: null
        payload?: {
            metric: ExperimentMetricUnion
        }
    }
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface experimentTimeseriesLogicMeta {
    __keaTypeGenInternalSelectorTypes: {
        isRecalculating: (timeseries: ExperimentMetricTimeseries | null) => boolean
        processedVariantData: (
            timeseries: ExperimentMetricTimeseries | null
        ) => (variantKey: string) => ProcessedTimeseriesDataPoint[]
        progressMessage: (timeseries: ExperimentMetricTimeseries | null) => string | null
        hasTimeseriesData: (timeseries: ExperimentMetricTimeseries | null) => boolean
        chartData: (
            processedVariantData: (variantKey: string) => ProcessedTimeseriesDataPoint[],
            timeseries: ExperimentMetricTimeseries | null,
            experiment: Experiment
        ) => (variantKey: string) => ProcessedChartData | null
    }
}

export type experimentTimeseriesLogicType = MakeLogicType<
    experimentTimeseriesLogicValues,
    experimentTimeseriesLogicActions,
    ExperimentTimeseriesLogicProps,
    experimentTimeseriesLogicMeta
>

export const experimentTimeseriesLogic = kea<experimentTimeseriesLogicType>([
    props({} as ExperimentTimeseriesLogicProps),
    path((key) => ['scenes', 'experiments', 'experimentTimeseriesLogic', key]),
    connect(() => ({
        actions: [eventUsageLogic, ['reportExperimentTimeseriesRecalculated']],
        values: [teamLogic, ['currentProjectId']],
    })),

    actions(() => ({
        recalculateTimeseries: ({ metric }: { metric: ExperimentMetric }) => ({ metric }),
    })),

    loaders(({ actions, props, values }) => ({
        timeseries: [
            null as ExperimentMetricTimeseries | null,
            {
                loadTimeseries: async ({ metric }: { metric: ExperimentMetric }) => {
                    if (!metric.uuid) {
                        throw new Error('Metric UUID is required')
                    }
                    if (!metric.fingerprint) {
                        throw new Error('Metric fingerprint is required')
                    }

                    // nosemgrep: prefer-codegen-api -- Legacy raw API call with a hand-written URL and an unchecked response type. experimentsTimeseriesResultsRetrieve() from 'products/experiments/frontend/generated/api' serves this route, but its generated types do not describe this call yet, so fix the endpoint's OpenAPI schema first.
                    const response = await api.get(
                        `api/projects/${values.currentProjectId}/experiments/${props.experiment.id}/timeseries_results/?metric_uuid=${metric.uuid}&fingerprint=${metric.fingerprint}`
                    )
                    return response
                },
                recalculateTimeseries: async ({ metric }: { metric: ExperimentMetric }) => {
                    if (!metric.fingerprint) {
                        throw new Error('Metric fingerprint is required')
                    }

                    try {
                        // nosemgrep: prefer-codegen-api -- Legacy raw API call with a hand-written URL and an unchecked response type. experimentsRecalculateTimeseriesCreate() from 'products/experiments/frontend/generated/api' serves this route, but its generated types do not describe this call yet, so fix the endpoint's OpenAPI schema first.
                        const response = await api.createResponse(
                            `api/projects/${values.currentProjectId}/experiments/${props.experiment.id}/recalculate_timeseries/`,
                            {
                                metric: metric,
                                fingerprint: metric.fingerprint,
                            }
                        )

                        if (response.ok) {
                            if (response.status === 201) {
                                lemonToast.success('Recalculation started successfully')
                                actions.reportExperimentTimeseriesRecalculated(
                                    props.experiment.id as ExperimentIdType,
                                    metric
                                )
                            } else if (response.status === 200) {
                                lemonToast.info('Recalculation already in progress')
                            }
                        }
                    } catch (error) {
                        lemonToast.error('Failed to start recalculation')
                        throw error
                    }

                    return null
                },
            },
        ],
    })),

    selectors({
        isRecalculating: [
            (s) => [s.timeseries],
            (timeseries: ExperimentMetricTimeseries | null): boolean => {
                return (
                    timeseries?.recalculation_status === 'pending' || timeseries?.recalculation_status === 'in_progress'
                )
            },
        ],
        // Extract and process timeseries data for a specific variant
        processedVariantData: [
            (s) => [s.timeseries],
            (
                timeseries: ExperimentMetricTimeseries | null
            ): ((variantKey: string) => ProcessedTimeseriesDataPoint[]) => {
                return (variantKey: string) => {
                    // Show completed and partial timeseries
                    if (!timeseries?.timeseries || !['completed', 'partial'].includes(timeseries.status)) {
                        return []
                    }

                    const allTimeseriesEntries = Object.entries(timeseries.timeseries).map(([date, data]) => ({
                        date,
                        data: data as ExperimentQueryResponse,
                    }))

                    const sortedTimeseriesData = allTimeseriesEntries.sort((a, b) => a.date.localeCompare(b.date))

                    // Extract data for the specific variant with carry-forward for missing data
                    let lastKnownData: ProcessedTimeseriesDataPoint | null = null

                    return sortedTimeseriesData.map((entry) => {
                        const d = entry.data

                        // Check if this entry has actual data (not null)
                        if (d && d.variant_results && d.baseline) {
                            const variant = d.variant_results.find(
                                (v: ExperimentVariantResultFrequentist | ExperimentVariantResultBayesian) =>
                                    v.key === variantKey
                            )
                            const baseline = d.baseline

                            if (variant && baseline) {
                                const interval = getVariantInterval(variant)
                                const [lower, upper] = interval || [0, 0]
                                const delta = (lower + upper) / 2

                                const dataPoint = {
                                    date: entry.date,
                                    value: delta,
                                    upper_bound: upper,
                                    lower_bound: lower,
                                    hasRealData: true,
                                    number_of_samples: variant.number_of_samples || 0,
                                    denominator_sum: variant.denominator_sum || 0,
                                    significant: variant.significant ?? false,
                                }

                                lastKnownData = dataPoint
                                return dataPoint
                            }
                        }

                        // No data for this day - carry forward last known value if available
                        if (lastKnownData) {
                            return {
                                ...lastKnownData,
                                date: entry.date,
                                hasRealData: false, // Mark as interpolated
                            }
                        }

                        // No previous data to carry forward
                        return {
                            date: entry.date,
                            value: 0,
                            upper_bound: 0,
                            lower_bound: 0,
                            hasRealData: false,
                            number_of_samples: 0,
                            denominator_sum: 0,
                            significant: false,
                        }
                    })
                }
            },
        ],

        // Progress message - shows calculation progress or completion
        progressMessage: [
            (s) => [s.timeseries],
            (timeseries: ExperimentMetricTimeseries | null): string | null => {
                if (!timeseries || !timeseries.timeseries) {
                    return null
                }

                const timeseriesData = timeseries.timeseries || {}
                const computedDays = Object.values(timeseriesData).filter((value) => value !== null).length
                const totalDays = Object.keys(timeseriesData).length

                if (totalDays === 0) {
                    return null
                }

                // If all days are computed, show "Calculated N days"
                if (computedDays === totalDays) {
                    return `Calculated ${pluralize(totalDays, 'day')}`
                }

                // Otherwise show progress "Computed N of M days"
                return `Computed ${computedDays} of ${totalDays} days`
            },
        ],
        hasTimeseriesData: [
            (s) => [s.timeseries],
            (timeseries: ExperimentMetricTimeseries | null): boolean => {
                return !!(
                    timeseries &&
                    (timeseries.status === 'completed' || timeseries.status === 'partial') &&
                    timeseries.timeseries &&
                    Object.values(timeseries.timeseries).some((data) => data !== null)
                )
            },
        ],

        chartData: [
            (s, props) => [s.processedVariantData, s.timeseries, props.experiment],
            (
                processedVariantData: (variantKey: string) => ProcessedTimeseriesDataPoint[],
                timeseries: ExperimentMetricTimeseries | null,
                experiment: Experiment
            ): ((variantKey: string) => ProcessedChartData | null) => {
                return (variantKey: string) => {
                    const processedData = processedVariantData(variantKey)
                    if (processedData.length === 0) {
                        return null
                    }

                    // Find the first day with a meaningful interval value (not zero)
                    const firstMeaningfulIndex = processedData.findIndex(
                        (d) =>
                            d.hasRealData &&
                            d.value !== null &&
                            d.value !== 0 &&
                            d.upper_bound !== null &&
                            d.lower_bound !== null &&
                            d.upper_bound !== 0 &&
                            d.lower_bound !== 0
                    )

                    // If meaningful data starts after day 1, trim to start from that day
                    const trimmedData =
                        firstMeaningfulIndex > 0 ? processedData.slice(firstMeaningfulIndex) : processedData

                    const labels = trimmedData.map((d: ProcessedTimeseriesDataPoint) => d.date)

                    // Get variant index from the experiment's stable variant order (flag-sourced)
                    let variantIndex = 0
                    const idx = getExperimentVariants(experiment).findIndex((v) => v.key === variantKey)
                    if (idx !== -1) {
                        variantIndex = idx
                    }

                    const variantColor = getSeriesColor(variantIndex)

                    return {
                        labels,
                        processedData: trimmedData,
                        computedAt: timeseries?.computed_at ?? null,
                        variantColor,
                    }
                }
            },
        ],
    }),

    listeners(({ actions }) => ({
        recalculateTimeseriesSuccess: ({ payload }) => {
            const metric = payload?.metric
            if (metric) {
                actions.loadTimeseries({ metric })
            }
        },
    })),

    afterMount(({ props, actions }) => {
        if (props.metric && props.metric.uuid && props.metric.fingerprint) {
            actions.loadTimeseries({ metric: props.metric })
        }
    }),
])