: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 { UsageIngestionClient, UsageRecordInput } from '~/common/usage-ingestion/client'
import { UsageRecordBatch } from '~/common/usage-ingestion/usage-record-batch'
import { IngestedEventInfo } from '~/ingestion/common/steps/event-processing/emit-event-step'
import { resolveAnalyticsUsageKey } from '~/ingestion/common/usage-records/billable-events'
import { isOkResult } from '~/ingestion/framework/results'
import { Properties } from '~/plugin-scaffold'
import { Person } from '~/types'
import { createRecordEventUsageAfterIngestStep, createRecordEventUsageStep } from './usage-records-steps'
const forceUpgradedPerson = (): Person => ({
team_id: 42,
properties: {},
uuid: 'person-uuid',
created_at: DateTime.fromISO('2026-06-01T00:00:00.000Z'),
force_upgrade: true,
})
describe('usage-records-steps', () => {
const FLUSH_TIMESTAMP_MS = 1_700_000_000_000
let ingestedUsage: UsageRecordInput[]
let eventUsageBatch: UsageRecordBatch
beforeEach(() => {
jest.useFakeTimers()
jest.setSystemTime(FLUSH_TIMESTAMP_MS)
ingestedUsage = []
const usageClient = {
ingest: jest.fn((records: UsageRecordInput[]) => {
ingestedUsage.push(...records)
return Promise.resolve()
}),
} as unknown as UsageIngestionClient
eventUsageBatch = new UsageRecordBatch(usageClient, { unit: 'events', isTeamEnabled: () => true })
})
afterEach(() => {
jest.useRealTimers()
})
async function queueEventUsage(
ingested: Promise<IngestedEventInfo | null>[],
event: Partial<{
event: string
eventUuid: string
distinctId: string
timestamp: string
properties: Properties
}> = {},
personProcessing: { processPerson?: boolean; person?: Person } = {},
headers: { now?: Date } = {}
): Promise<void> {
const prepare = createRecordEventUsageStep(resolveAnalyticsUsageKey)
const prepared = await prepare({
preparedEvent: {
teamId: 42,
event: '$pageview',
eventUuid: 'event-uuid',
distinctId: 'user-7',
timestamp: '2026-06-15T23:55:00.000Z',
properties: {},
...event,
},
headers,
eventUsageBatch,
...personProcessing,
})
expect(isOkResult(prepared)).toBe(true)
if (!isOkResult(prepared)) {
throw new Error('expected usage preparation to succeed')
}
const recordAfterIngest = createRecordEventUsageAfterIngestStep()
await recordAfterIngest({ ...prepared.value, ingested })
}
it.each([
[
'Kafka rejects the write',
(): Promise<IngestedEventInfo | null> => Promise.reject(new Error('Kafka unavailable')),
],
['Kafka declines the event', (): Promise<IngestedEventInfo | null> => Promise.resolve(null)],
])('does not report usage when %s', async (_name, acknowledgement) => {
await queueEventUsage([acknowledgement()])
await eventUsageBatch.flush()
expect(ingestedUsage).toEqual([])
})
it.each([
['ordinary values', {}],
[
'the longest event name and distinct ID a client can send',
{ event: 'e'.repeat(200), distinctId: 'd'.repeat(400) },
],
])('keeps the record ID inside the service identifier limit with %s', async (_name, event) => {
await queueEventUsage([Promise.resolve({ topic: 'events', partition: 0 })], event)
await eventUsageBatch.flush()
expect(ingestedUsage[0].recordId).toMatch(/^2026-06-15:[0-9a-f]{32}$/)
})
it.each([
['distinct ID', { distinctId: 'user-8' }],
['event name', { event: '$autocapture' }],
['UUID', { eventUuid: 'other-uuid' }],
])('bills two events that differ only in %s separately', async (_name, event) => {
const acknowledged = (): Promise<IngestedEventInfo> => Promise.resolve({ topic: 'events', partition: 0 })
await queueEventUsage([acknowledged()])
await queueEventUsage([acknowledged()], event)
await eventUsageBatch.flush()
expect(new Set(ingestedUsage.map((record) => record.recordId)).size).toBe(2)
})
it.each([
['share a submission ID', { $survey_id: 'survey-1', $survey_submission_id: 'submission-1' }, 1],
['have no submission ID', { $survey_id: 'survey-1' }, 2],
])('bills partial and completed survey sent events once when they %s', async (_name, properties, expected) => {
const acknowledged = (): Promise<IngestedEventInfo> => Promise.resolve({ topic: 'events', partition: 0 })
const step = (eventUuid: string, completed: boolean): Promise<void> =>
queueEventUsage([acknowledged()], {
event: 'survey sent',
eventUuid,
properties: { ...properties, $survey_completed: completed },
})
await step('partial-uuid', false)
await step('completed-uuid', true)
await eventUsageBatch.flush()
expect(ingestedUsage.every((record) => record.usageKey === 'survey_responses')).toBe(true)
expect(new Set(ingestedUsage.map((record) => record.recordId)).size).toBe(expected)
})
it('bills two events apart when only the position of a newline differs', async () => {
const acknowledged = (): Promise<IngestedEventInfo> => Promise.resolve({ topic: 'events', partition: 0 })
await queueEventUsage([acknowledged()], { event: 'a\nb', distinctId: 'c' })
await queueEventUsage([acknowledged()], { event: 'a', distinctId: 'b\nc' })
await eventUsageBatch.flush()
expect(new Set(ingestedUsage.map((record) => record.recordId)).size).toBe(2)
})
it('reports the event usage payload only after Kafka acknowledges the write', async () => {
let acknowledgeKafka!: (info: IngestedEventInfo) => void
const kafkaAcknowledgement = new Promise<IngestedEventInfo>((resolve) => {
acknowledgeKafka = resolve
})
await queueEventUsage([kafkaAcknowledgement])
const flush = eventUsageBatch.flush()
await expect(Promise.resolve()).resolves.toBeUndefined()
expect(ingestedUsage).toEqual([])
acknowledgeKafka({ topic: 'events', partition: 0 })
await flush
expect(ingestedUsage).toEqual([
{
recordId: expect.stringMatching(/^2026-06-15:[0-9a-f]{32}$/),
teamId: 42,
usageKey: 'events',
unit: 'events',
quantity: 1,
timestampMs: FLUSH_TIMESTAMP_MS,
},
])
})
it.each([
['same day', '2026-07-01T00:01:00.000Z'],
['closed month', '2026-05-15T12:00:00.000Z'],
['future source date', '2026-08-01T00:00:00.000Z'],
])('bills receipt time and preserves the source date for %s', async (_name, timestamp) => {
const capturedAtMs = Date.parse('2026-07-01T23:59:00.000Z')
jest.setSystemTime(capturedAtMs)
await queueEventUsage(
[Promise.resolve({ topic: 'events', partition: 0 })],
{ timestamp },
{ processPerson: true },
{ now: new Date(capturedAtMs) }
)
jest.advanceTimersByTime(6 * 60 * 60 * 1000)
await eventUsageBatch.flush()
expect(ingestedUsage.map((record) => record.usageKey)).toEqual(['events', 'enhanced_person_events'])
for (const record of ingestedUsage) {
expect(record.timestampMs).toBe(capturedAtMs)
expect(record.recordId).toMatch(new RegExp(`^${timestamp.slice(0, 10)}:[0-9a-f]{32}$`))
}
})
// The meters have to match `person_mode` in the nightly report's two billable-event queries,
// which count `full` and `force_upgrade` as enhanced and `propertyless` as not. A force upgrade
// only happens when the client asked for propertyless, so it is the case that breaks if the
// step goes back to reading `processPerson` alone.
it.each([
['full', { processPerson: true }, ['events', 'enhanced_person_events']],
['propertyless', { processPerson: false }, ['events']],
[
'force_upgrade',
{ processPerson: false, person: forceUpgradedPerson() },
['events', 'enhanced_person_events'],
],
])('bills %s person processing under %j', async (_mode, personProcessing, expectedUsageKeys) => {
await queueEventUsage([Promise.resolve({ topic: 'events', partition: 0 })], {}, personProcessing)
await eventUsageBatch.flush()
expect(ingestedUsage.map((record) => record.usageKey)).toEqual(expectedUsageKeys)
// One event, so both meters share the identity and are told apart only by the usage key.
expect(new Set(ingestedUsage.map((record) => record.recordId)).size).toBe(1)
})
})