: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
// NOTE: PostIngestionEvent is our context event - it should never be sent directly to an output, but rather transformed into a lightweight schema
import { DateTime } from 'luxon'
import { Counter } from 'prom-client'
import { UUIDT } from '~/common/utils/utils'
import type { HogInputsService } from '../services/hog-inputs.service'
import {
CyclotronJobInvocation,
CyclotronJobInvocationHogFunction,
CyclotronJobInvocationResult,
HogFunctionFilterGlobals,
HogFunctionInvocationGlobals,
HogFunctionInvocationGlobalsWithInputs,
InvocationBuildFailure,
LogEntry,
MinimalAppMetric,
} from '../types'
import { HogFunctionType } from '../types'
import { getConfiguredSensitiveValues, logEntry, sanitizeLogMessage } from '../utils'
import { currentRuntimeContractHash } from './filter-runtime'
import { bytecodeContractOf, classifyHogError } from './hog-error-classification'
import { convertToHogFunctionFilterGlobal, filterFunctionInstrumented } from './hog-function-filtering'
/** The inputs step of the dead-letter pipeline. Read next to cdp_hog_function_filter_error. */
const hogFunctionInputsErrors = new Counter({
name: 'cdp_hog_function_inputs_error',
help: 'Building the inputs for an invocation threw, so no invocation was created',
labelNames: ['type', 'class'],
})
export function createInvocation(
globals: HogFunctionInvocationGlobalsWithInputs,
hogFunction: HogFunctionType
): CyclotronJobInvocationHogFunction {
return {
id: new UUIDT().toString(),
state: {
globals,
timings: [],
attempts: 0,
},
teamId: hogFunction.team_id,
functionId: hogFunction.id,
hogFunction,
queue: 'hog',
queuePriority: 0,
}
}
/**
* Matches a batch of hog functions against one event's globals and builds an invocation per match,
* resolving each one's inputs. Filter metrics/logs come back alongside for the caller to queue, as
* do the functions that matched but produced no invocation, which the caller dead-letters.
*/
export async function buildHogFunctionInvocations(
hogInputsService: HogInputsService,
hogFunctions: HogFunctionType[],
triggerGlobals: HogFunctionInvocationGlobals
): Promise<{
invocations: CyclotronJobInvocationHogFunction[]
metrics: MinimalAppMetric[]
logs: LogEntry[]
buildFailures: InvocationBuildFailure[]
}> {
const metrics: MinimalAppMetric[] = []
const logs: LogEntry[] = []
const invocations: CyclotronJobInvocationHogFunction[] = []
const buildFailures: InvocationBuildFailure[] = []
// TRICKY: The frontend generates filters matching the Clickhouse event type so we are converting back
const filterGlobals = convertToHogFunctionFilterGlobal(triggerGlobals)
const _filterHogFunction = async (
hogFunction: HogFunctionType,
filters: HogFunctionType['filters'],
filterGlobals: HogFunctionFilterGlobals
): Promise<boolean> => {
const filterResults = await filterFunctionInstrumented({
caller: 'build_hog_function_invocations',
fn: hogFunction,
filters,
filterGlobals,
})
// Add any generated metrics and logs to our collections
metrics.push(...filterResults.metrics)
logs.push(...filterResults.logs)
// Checked against undefined, not for truthiness: a thrown error whose message is empty is
// still a failure, and treating it as success drops the event with no record of it.
if (filterResults.error !== undefined) {
buildFailures.push({
sourceId: hogFunction.id,
sourceKind: 'hog_function',
step: 'filter',
error: String(filterResults.error),
errorClass: filterResults.errorClass,
})
}
return filterResults.match
}
const _buildInvocation = async (
hogFunction: HogFunctionType,
additionalInputs?: HogFunctionType['inputs']
): Promise<CyclotronJobInvocationHogFunction | null> => {
try {
const globalsWithSource = {
...triggerGlobals,
source: {
id: hogFunction.id,
name: hogFunction.name ?? `Hog function: ${hogFunction.id}`,
url: `${triggerGlobals.project.url}/functions/${hogFunction.id}/configuration/`,
},
}
const globalsWithInputs = await hogInputsService.buildInputsWithGlobals(
hogFunction,
globalsWithSource,
additionalInputs
)
return createInvocation(globalsWithInputs, hogFunction)
} catch (error) {
// A dependency outage, such as Postgres refusing an integration lookup, is not this
// function's fault. Rethrowing fails the batch, so the offsets stay put and it retries.
if (error?.isRetriable === true) {
throw error
}
const errorClass = classifyHogError(error, {
bytecodeContract: bytecodeContractOf(error),
runtimeContract: currentRuntimeContractHash(),
})
buildFailures.push({
sourceId: hogFunction.id,
sourceKind: 'hog_function',
step: 'inputs',
// The VM quotes the argument it choked on, and an argument can be a secret input.
// This message leaves the process as a header on the parked record.
error: sanitizeLogMessage([error.message], getConfiguredSensitiveValues(hogFunction)),
errorClass,
})
logs.push({
team_id: hogFunction.team_id,
log_source: 'hog_function',
log_source_id: hogFunction.id,
instance_id: new UUIDT().toString(), // random UUID, like it would be for an invocation
// logEntry truncates: the message carries the VM's text, which can quote a value.
// The VM can quote an argument, and an argument can be a secret input.
...logEntry(
'error',
sanitizeLogMessage(
[`Error building inputs for event ${triggerGlobals.event.uuid}: ${error.message}`],
getConfiguredSensitiveValues(hogFunction)
)
),
})
hogFunctionInputsErrors.inc({ type: hogFunction.type, class: errorClass })
metrics.push({
team_id: hogFunction.team_id,
app_source_id: hogFunction.id,
metric_kind: 'failure',
metric_name: 'inputs_failed',
count: 1,
})
return null
}
}
await Promise.all(
hogFunctions.map(async (hogFunction) => {
// We always check the top level filters
if (!(await _filterHogFunction(hogFunction, hogFunction.filters, filterGlobals))) {
return
}
// Check for non-mapping functions first
if (!hogFunction.mappings) {
const invocation = await _buildInvocation(hogFunction)
if (!invocation) {
return
}
invocations.push(invocation)
return
}
await Promise.all(
hogFunction.mappings.map(async (mapping) => {
if (!(await _filterHogFunction(hogFunction, mapping.filters, filterGlobals))) {
return
}
const invocation = await _buildInvocation(hogFunction, mapping.inputs ?? {})
if (!invocation) {
return
}
invocations.push(invocation)
})
)
})
)
return {
invocations,
metrics,
logs,
buildFailures,
}
}
/**
* Clones an invocation, removing all queue related values
*/
export function cloneInvocation<T extends CyclotronJobInvocation>(
invocation: T,
params: Pick<
Partial<CyclotronJobInvocation>,
'queue' | 'queuePriority' | 'queueMetadata' | 'queueScheduledAt' | 'queueParameters'
> = {}
): T {
return {
...invocation,
// The target queue is typically the same as the source but can be overridden
queue: params.queue ?? invocation.queue,
// The source is kept from the invocation always as it is important for the job queue router
queueSource: invocation.queueSource,
// Metadata is only used from the invocation if the queue is staying the same
queueMetadata:
params.queueMetadata ?? (invocation.queue === params.queue ? invocation.queueMetadata : undefined),
// Below params are always reset unless provided as overrides
queueScheduledAt: params.queueScheduledAt ?? undefined,
queuePriority: params.queuePriority ?? 0,
queueParameters: params.queueParameters ?? undefined,
}
}
export function createInputsFailureResult(
hogFunction: HogFunctionType,
globals: HogFunctionInvocationGlobals,
error: Error,
invocationId?: string
): CyclotronJobInvocationResult<CyclotronJobInvocationHogFunction> {
const invocation = createInvocation({ ...globals, inputs: {} }, hogFunction)
if (invocationId) {
invocation.id = invocationId
}
return createInvocationResult<CyclotronJobInvocationHogFunction>(
invocation,
{},
{
error: error.message,
logs: [{ level: 'error', timestamp: DateTime.now(), message: `Error building inputs: ${error.message}` }],
}
)
}
/**
* Safely creates an invocation result from an invocation, cloning it and resetting the relevant queue parameters
*/
export function createInvocationResult<T extends CyclotronJobInvocation>(
invocation: CyclotronJobInvocation,
invocationParams: Pick<
Partial<CyclotronJobInvocation>,
'queue' | 'queuePriority' | 'queueMetadata' | 'queueScheduledAt' | 'queueParameters'
> = {},
resultParams: Pick<
Partial<CyclotronJobInvocationResult>,
| 'finished'
| 'capturedPostHogEvents'
| 'warehouseWebhookPayloads'
| 'messageAssets'
| 'conversionWatchers'
| 'logs'
| 'metrics'
| 'error'
| 'execResult'
| 'emailSendResult'
> = {}
): CyclotronJobInvocationResult<T> {
return {
// Clone the invocation for the result cleaned
finished: true,
capturedPostHogEvents: [],
warehouseWebhookPayloads: [],
messageAssets: [],
conversionWatchers: [],
logs: [],
metrics: [],
...resultParams,
invocation: cloneInvocation(invocation, invocationParams) as T,
}
}