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.

4.7 KB
Raw Blame
import { Message } from 'node-rdkafka'
import { parse as parseUuid, v5 as uuidv5 } from 'uuid'

import { UsageRecordBatch } from '~/common/usage-ingestion/usage-record-batch'
import { parseTeamsList } from '~/common/utils/env-utils'
import { createEvent } from '~/ingestion/common/steps/event-processing/create-event'
import { EventUsageRecord } from '~/ingestion/common/steps/usage-records-steps'
import { ok } from '~/ingestion/framework/results'
import { ProcessingStep } from '~/ingestion/framework/steps'
import { EventHeaders, Person, PreIngestionEvent, Team } from '~/types'

import { EventToEmit } from './emit-event-step'

const FEATURE_FLAG_CALLED_EVENT = '$feature_flag_called'
const EXPERIMENT_EXPOSURE_EVENT = '$experiment_exposure'

// UUIDv5 namespace (a randomly generated UUIDv4) for deriving a duplicated exposure
// event's uuid from its source event's uuid.
const EXPERIMENT_EXPOSURE_UUIDV5_NAMESPACE = parseUuid('1b7c9119-5953-4668-97b7-ab0ef8a6bb48')

// SDKs mark calls to flags on v2 rules with this property and send $experiment_exposure
// themselves, so duplicating those calls would count each exposure twice. SDKs send the
// number; the string is matched too because a duplicate costs more than a skipped one.
function isConfigVersion2FeatureFlagCalledEvent(event: PreIngestionEvent): boolean {
    const configVersion = event.properties['$feature_flag_config_version']
    return configVersion === 2 || configVersion === '2'
}

// Flag definitions aren't available in ingestion, so multivariate is inferred from the
// response shape; a variant literally keyed "true" or "false" is indistinguishable from
// a boolean flag response and knowingly skipped.
function isMultivariateFeatureFlagCalledEvent(event: PreIngestionEvent): boolean {
    const response = event.properties['$feature_flag_response']

    return (
        event.event === FEATURE_FLAG_CALLED_EVENT &&
        !isConfigVersion2FeatureFlagCalledEvent(event) &&
        typeof response === 'string' &&
        response !== '' &&
        response !== 'true' &&
        response !== 'false'
    )
}

export interface CreateEventStepInput {
    team: Team
    person?: Person
    preparedEvent: PreIngestionEvent
    processPerson: boolean
    historicalMigration: boolean
    headers: EventHeaders
    message: Message
    eventUsageRecords?: EventUsageRecord[]
    eventUsageBatch?: UsageRecordBatch
}

export interface CreateEventStepResult<O extends string> {
    team: Team
    eventsToEmit: EventToEmit<O>[]
    teamId: number
    headers: EventHeaders
    message: Message
    eventUsageRecords?: EventUsageRecord[]
    eventUsageBatch?: UsageRecordBatch
}

export function createCreateEventStep<O extends string, T extends CreateEventStepInput>(
    output: O,
    experimentExposureDuplicationTeams: string = ''
): ProcessingStep<T, CreateEventStepResult<O>> {
    const exposureDuplicationTeams = parseTeamsList(experimentExposureDuplicationTeams)

    return function createEventStep(input) {
        const {
            team,
            person,
            preparedEvent,
            processPerson,
            historicalMigration,
            headers,
            message,
            eventUsageRecords,
            eventUsageBatch,
        } = input

        const capturedAt = headers.now ?? null
        const rawEvent = createEvent(preparedEvent, person, processPerson, historicalMigration, capturedAt)
        const eventsToEmit: EventToEmit<O>[] = [{ event: rawEvent, output }]

        // Duplicated exposures build up $experiment_exposure data for allowlisted teams during
        // the migration away from $feature_flag_called-based experiment exposures. The duplicate
        // gets its own uuid because event uuids are assumed unique by lookups and API endpoints,
        // derived deterministically from the source event's uuid so that a Kafka redelivery
        // reproduces the same row, which the events table's ReplacingMergeTree can collapse.
        if (
            (exposureDuplicationTeams === '*' || exposureDuplicationTeams.includes(preparedEvent.teamId)) &&
            isMultivariateFeatureFlagCalledEvent(preparedEvent)
        ) {
            eventsToEmit.push({
                event: {
                    ...rawEvent,
                    event: EXPERIMENT_EXPOSURE_EVENT,
                    uuid: uuidv5(rawEvent.uuid, EXPERIMENT_EXPOSURE_UUIDV5_NAMESPACE),
                },
                output,
            })
        }

        const result: CreateEventStepResult<O> = {
            team,
            eventsToEmit,
            teamId: preparedEvent.teamId,
            headers,
            message,
            eventUsageRecords,
            eventUsageBatch,
        }

        return Promise.resolve(ok(result, []))
    }
}