: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 { DateTime } from 'luxon'
import { normalizeProcessPerson } from '~/common/utils/event'
import {
buildFlagCalledPersonlessMatcher,
isFlagCalledPersonlessCandidate,
} from '~/ingestion/common/persons/flag-called-personless'
import { uuidFromDistinctId } from '~/ingestion/common/persons/person-uuid'
import { PersonsStoreForBatch } from '~/ingestion/common/persons/persons-store-for-batch'
import {
DEFAULT_FLAG_CALLED_PERSONLESS_DEFAULT_TEAMS,
DEFAULT_FLAG_CALLED_PERSONLESS_EXCLUDED_TEAMS,
} from '~/ingestion/config'
import { PipelineResult, ok } from '~/ingestion/framework/results'
import { ProcessingStep } from '~/ingestion/framework/steps'
import { PluginEvent } from '~/plugin-scaffold'
import { Person, Team } from '~/types'
export type ProcessPersonlessInput = {
normalizedEvent: PluginEvent
team: Team
timestamp: DateTime
processPerson: boolean
processPersonExplicitlyTrue: boolean
forceDisablePersonProcessing: boolean
personsStoreForBatch: PersonsStoreForBatch
}
export type ProcessPersonlessOutput = {
personlessPerson?: Person
}
/**
* Pipeline step that handles personless event processing checks.
*
* Runs when processPerson=false, and also for $feature_flag_called events that did not
* explicitly set $process_person_profile=true — so server-side flag evaluation does not
* create orphan person profiles (see #60581). Flag-called events that find an existing
* person, or that carry group keys, stay personful; the rest are defaulted to personless.
*
* For personless events, this step:
* 1. Fetches existing person from cache (populated by prefetchPersonsStep)
* 2. Calculates force_upgrade flag
* 3. Returns person (real or fake) with potential force_upgrade flag
*/
export function createProcessPersonlessStep<TInput extends ProcessPersonlessInput>(
flagCalledPersonlessDefaultTeams: string = DEFAULT_FLAG_CALLED_PERSONLESS_DEFAULT_TEAMS,
flagCalledPersonlessExcludedTeams: string = DEFAULT_FLAG_CALLED_PERSONLESS_EXCLUDED_TEAMS
): ProcessingStep<TInput, TInput & ProcessPersonlessOutput> {
const flagCalledDefaultEnabledForTeam = buildFlagCalledPersonlessMatcher(
flagCalledPersonlessDefaultTeams,
flagCalledPersonlessExcludedTeams
)
return async function processPersonlessStep(
input: TInput
): Promise<PipelineResult<TInput & ProcessPersonlessOutput>> {
if (input.processPerson) {
const mayDefaultFlagCalledToPersonless = isFlagCalledPersonlessCandidate(
input.normalizedEvent,
input.team.id,
input.processPersonExplicitlyTrue,
flagCalledDefaultEnabledForTeam
)
if (!mayDefaultFlagCalledToPersonless) {
return ok(input)
}
return await applyFeatureFlagCalledPersonlessDefault(input, input.personsStoreForBatch)
}
const { normalizedEvent, team, timestamp, forceDisablePersonProcessing, personsStoreForBatch } = input
const distinctId = normalizedEvent.distinct_id
if (forceDisablePersonProcessing) {
return ok({ ...input, personlessPerson: createFakePerson(team.id, distinctId) })
}
// Check if a real person exists for this distinct_id (from prefetch cache). An event
// racing a merge may miss the person and stay propertyless; the merge's always-written
// override re-points it.
const existingPerson = await personsStoreForBatch.fetchForChecking(team.id, distinctId)
if (existingPerson) {
const person = existingPerson as Person
// Ensure person properties don't propagate elsewhere, such as onto the event itself.
person.properties = {}
// If the team has opted out then we never force the upgrade.
const teamHasNotOptedOut = !team.person_processing_opt_out
if (teamHasNotOptedOut && timestamp > person.created_at.plus({ minutes: 1 })) {
// See documentation on the Person.force_upgrade field.
//
// Note that we account for timestamp vs person creation time (with a little
// padding for good measure) to account for ingestion lag. It's possible for
// events to be processed after person creation even if they were sent prior
// to person creation, and the user did nothing wrong in that case.
person.force_upgrade = true
}
return ok({ ...input, personlessPerson: person })
}
return ok({ ...input, personlessPerson: createFakePerson(team.id, distinctId) })
}
}
/**
* Defaults a $feature_flag_called event to personless unless a person already exists for
* its distinct ID, so server-side flag evaluation does not create orphan person profiles.
*/
async function applyFeatureFlagCalledPersonlessDefault<TInput extends ProcessPersonlessInput>(
input: TInput,
personsStore: PersonsStoreForBatch
): Promise<PipelineResult<TInput & ProcessPersonlessOutput>> {
const { normalizedEvent, team } = input
const distinctId = normalizedEvent.distinct_id
const existingPerson = await personsStore.fetchForChecking(team.id, distinctId)
if (existingPerson) {
// A person already exists for this distinct ID, so keep the event personful.
return ok(input)
}
return ok({
...input,
// The event was normalized as personful upstream, so re-normalize it to strip
// $set/$set_once and stamp $process_person_profile=false.
normalizedEvent: normalizeProcessPerson(normalizedEvent, false),
processPerson: false,
personlessPerson: createFakePerson(team.id, distinctId),
})
}
/**
* Creates a deterministic fake person for personless events.
*
* The UUID is deterministic based on team_id and distinct_id, allowing:
* - Future events with same distinct_id to get same UUID
* - Later merging/upgrading without data loss
*
* The created_at timestamp (1970-01-01 00:00:05 UTC) serves as a debugging marker
* that this is a synthetic person, not a real one.
*/
function createFakePerson(teamId: number, distinctId: string): Person {
// We need a value from the `person_created_column` in ClickHouse. This should be
// hidden from users for events without a real person, anyway. It's slightly offset
// from the 0 date (by 5 seconds) in order to assist in debugging by being
// harmlessly distinct from Unix UTC "0".
const createdAt = DateTime.utc(1970, 1, 1, 0, 0, 5)
return {
team_id: teamId,
properties: {},
uuid: uuidFromDistinctId(teamId, distinctId),
created_at: createdAt,
}
}