: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 { Counter, Gauge } from 'prom-client'
import { HogTransformationResult, HogTransformer } from '~/common/hog-transformations/hog-transformer.interface'
import { IngestionOutputs } from '~/common/outputs/ingestion-outputs'
import { instrumentFn } from '~/common/tracing/tracing-utils'
import { PostgresRouter } from '~/common/utils/db/postgres'
import { GeoIPService, GeoIp } from '~/common/utils/geoip'
import { logger } from '~/common/utils/logger'
import { PubSub } from '~/common/utils/pubsub'
import type { TeamManager } from '~/common/utils/team-manager'
import { PluginEvent, Properties } from '~/plugin-scaffold'
import {
CyclotronJobInvocationResult,
HogFunctionInvocationGlobals,
HogFunctionInvocationGlobalsWithInputs,
HogFunctionType,
} from '../../cdp/types'
import { isLegacyPluginHogFunction } from '../../cdp/utils'
import type { CommonConfig } from '../../common/config'
import { HogExecutorService } from '../services/hog-executor.service'
import { HogInputsService } from '../services/hog-inputs.service'
import { LegacyPluginExecutorService } from '../services/legacy-plugin-executor.service'
import { HogFunctionManagerService } from '../services/managers/hog-function-manager.service'
import { IntegrationManagerService } from '../services/managers/integration-manager.service'
import {
HogFunctionMonitoringService,
MonitoringOutput,
TransformationsMonitoringConfig,
createTransformationsMonitoringService,
} from '../services/monitoring/hog-function-monitoring.service'
import { EncryptedFields } from '../utils/encryption-utils'
import { HogConfigurationError } from '../utils/hog-error-classification'
import { convertToHogFunctionFilterGlobal, filterFunctionInstrumented } from '../utils/hog-function-filtering'
import { createInputsFailureResult, createInvocation } from '../utils/invocation-utils'
import { geoipNoopResult } from './geoip-noop'
import { RustVmExecutor } from './rust-vm-executor'
import { getTransformationFunctions } from './transformation-functions'
export interface HogTransformerConfig {
siteUrl: string
hogRustVmExecutionEnabled: boolean
hogRustVmBatchExecutionEnabled: boolean
mmdbFileLocation: string
}
export const hogTransformationDroppedEvents = new Counter({
name: 'hog_transformation_dropped_events',
help: 'Indicates how many events are dropped by hog transformations',
})
export const hogTransformationInvocations = new Counter({
name: 'hog_transformation_invocations_total',
help: 'Number of times transformEvent was called directly',
})
export const hogTransformationAttempts = new Counter({
name: 'hog_transformation_attempts_total',
help: 'Number of transformation attempts before any processing',
labelNames: ['type'],
})
export const hogTransformationCompleted = new Counter({
name: 'hog_transformation_completed_total',
help: 'Number of successfully completed transformations',
labelNames: ['type'],
})
export const hogTransformationPendingInvocationResults = new Gauge({
name: 'hog_transformation_pending_invocation_results',
help: 'Number of invocation results accumulated and waiting to be processed. High values indicate memory accumulation.',
})
export const hogTransformationUnexpectedErrors = new Counter({
name: 'hog_transformation_unexpected_errors_total',
help: 'Number of unexpected errors during transformation execution. Any occurrence should trigger an alert as the transformation is skipped.',
})
export const hogTransformationProtectedPropertyWrites = new Counter({
name: 'hog_transformation_protected_property_writes_total',
help: 'Transformations that added, changed or removed a capture-owned $ai_gateway* property. The write is reverted; any occurrence is a billing-exemption forgery attempt worth an alert.',
})
// Capture stamps these after verifying the AI gateway's signature and the usage report exempts
// verified events from the AI meter, so transformations must not be able to write them.
const PROTECTED_PROPERTY_PREFIX = '$ai_gateway'
function pickProtectedProperties(properties: Properties | undefined): Properties {
const picked: Properties = {}
if (!properties) {
return picked
}
for (const key in properties) {
if (key.startsWith(PROTECTED_PROPERTY_PREFIX)) {
picked[key] = properties[key]
}
}
return picked
}
function restoreProtectedProperties(properties: Properties, protectedProperties: Properties): boolean {
const written = pickProtectedProperties(properties)
for (const key in written) {
delete properties[key]
}
Object.assign(properties, protectedProperties)
const protectedKeys = Object.keys(protectedProperties)
if (Object.keys(written).length !== protectedKeys.length) {
return true
}
return protectedKeys.some((key) => written[key] !== protectedProperties[key])
}
export interface TransformationResult extends HogTransformationResult {
event: PluginEvent | null
invocationResults: CyclotronJobInvocationResult[]
}
export class HogTransformerService implements HogTransformer {
private invocationResults: CyclotronJobInvocationResult[] = []
private cachedGeoIp?: GeoIp
private cachedTransformationFunctions?: ReturnType<typeof getTransformationFunctions>
private rustVmExecutor: RustVmExecutor | null
constructor(
private hogFunctionManager: HogFunctionManagerService,
private hogExecutor: HogExecutorService,
private hogFunctionMonitoringService: HogFunctionMonitoringService,
private pluginExecutor: LegacyPluginExecutorService,
private geoipService: GeoIPService,
private config: HogTransformerConfig
) {
this.rustVmExecutor = config.hogRustVmExecutionEnabled
? new RustVmExecutor({ mmdbPath: config.mmdbFileLocation })
: null
}
public async start(): Promise<void> {}
public async stop(): Promise<void> {
await this.processInvocationResults()
await this.hogFunctionMonitoringService.stop()
}
public async processInvocationResults(): Promise<void> {
const results = [...this.invocationResults]
this.invocationResults = []
hogTransformationPendingInvocationResults.set(0)
this.hogFunctionMonitoringService.queueInvocationResults(results)
await this.hogFunctionMonitoringService.flush()
}
public async prefetchHogFunctionsForTeams(teamIds: number[]): Promise<void> {
// Warm the by-team and by-id loaders directly, skipping the per-team assembly and sort
// that getHogFunctionsForTeams would do and the event path redoes anyway.
const idsByTeam = await this.hogFunctionManager.getHogFunctionIdsForTeams(teamIds, ['transformation'], {
flush: true,
})
await this.hogFunctionManager.getHogFunctions(Object.values(idsByTeam).flat(), { flush: true })
}
private async getTransformationFunctions() {
if (!this.cachedTransformationFunctions) {
this.cachedGeoIp = await this.geoipService.get()
this.cachedTransformationFunctions = getTransformationFunctions(this.cachedGeoIp)
}
return this.cachedTransformationFunctions
}
private createInvocationGlobals(event: PluginEvent): HogFunctionInvocationGlobals {
return {
project: {
id: event.team_id,
name: '',
url: this.config.siteUrl,
},
event: {
uuid: event.uuid,
event: event.event,
distinct_id: event.distinct_id,
properties: event.properties || {},
elements_chain: event.properties?.$elements_chain || '',
timestamp: event.timestamp || '',
url: event.properties?.$current_url || '',
},
}
}
private async transformEventAndProduceMessagesImpl(event: PluginEvent): Promise<TransformationResult> {
hogTransformationAttempts.inc({ type: 'with_messages' })
const teamHogFunctions = await this.hogFunctionManager.getHogFunctionsForTeam(event.team_id, ['transformation'])
const transformationResult = await this.transformEvent(event, teamHogFunctions)
for (const result of transformationResult.invocationResults) {
this.invocationResults.push(result)
}
hogTransformationPendingInvocationResults.set(this.invocationResults.length)
hogTransformationCompleted.inc({ type: 'with_messages' })
return {
...transformationResult,
}
}
public transformEventAndProduceMessages(event: PluginEvent): Promise<TransformationResult> {
return instrumentFn({ key: `hogTransformer.transformEventAndProduceMessages`, span: false }, () =>
this.transformEventAndProduceMessagesImpl(event)
)
}
private async transformEventImpl(
event: PluginEvent,
teamHogFunctions: HogFunctionType[]
): Promise<TransformationResult> {
hogTransformationInvocations.inc()
// Early return if no transformations to run
if (teamHogFunctions.length === 0) {
return {
event,
invocationResults: [],
}
}
const results: CyclotronJobInvocationResult[] = []
const protectedProperties = pickProtectedProperties(event.properties)
// Create globals once and update the event properties after each transformation
const globals = this.createInvocationGlobals(event)
for (const hogFunction of teamHogFunctions) {
// Create filterGlobals for each iteration - it references globals.event.properties
// which gets updated after each successful transformation
const filterGlobals = convertToHogFunctionFilterGlobal(globals)
// Check if function has filters - if not, always apply
if (hogFunction.filters?.bytecode) {
const filterResults = await filterFunctionInstrumented({
caller: 'transformation',
fn: hogFunction,
filters: hogFunction.filters,
filterGlobals,
})
// If filter didn't pass skip the actual transformation and add logs and errors from the filterResult
this.hogFunctionMonitoringService.queueAppMetrics(filterResults.metrics, 'hog_function')
this.hogFunctionMonitoringService.queueLogs(filterResults.logs, 'hog_function')
if (!filterResults.match) {
continue
}
}
let result: CyclotronJobInvocationResult
try {
result = await this.executeHogFunction(hogFunction, globals)
} catch (err) {
hogTransformationUnexpectedErrors.inc()
logger.error('⚠️', 'Unexpected error executing transformation', {
function_id: hogFunction.id,
team_id: event.team_id,
error: String(err),
})
this.hogFunctionMonitoringService.queueAppMetric(
{
team_id: event.team_id,
app_source_id: hogFunction.id,
metric_kind: 'failure',
metric_name: 'failed',
count: 1,
},
'hog_function'
)
continue
}
results.push(result)
if (result.error) {
continue
}
if (!result.execResult) {
hogTransformationDroppedEvents.inc()
this.hogFunctionMonitoringService.queueAppMetric(
{
team_id: event.team_id,
app_source_id: hogFunction.id,
metric_kind: 'other',
metric_name: 'dropped',
count: 1,
},
'hog_function'
)
return {
event: null,
invocationResults: results,
droppedBy: { id: hogFunction.id, name: hogFunction.name },
}
}
const transformedEvent: unknown = result.execResult
if (
!transformedEvent ||
typeof transformedEvent !== 'object' ||
!('properties' in transformedEvent) ||
!transformedEvent.properties ||
typeof transformedEvent.properties !== 'object'
) {
logger.error('⚠️', 'Invalid transformation result - missing or invalid properties', {
function_id: hogFunction.id,
})
continue
}
event.properties = transformedEvent.properties as Record<string, any>
event.ip = event.properties.$ip ?? null
if ('event' in transformedEvent) {
if (typeof transformedEvent.event !== 'string') {
logger.error('⚠️', 'Invalid transformation result - event name must be a string', {
function_id: hogFunction.id,
event: transformedEvent.event,
})
continue
}
event.event = transformedEvent.event
}
if ('distinct_id' in transformedEvent) {
if (typeof transformedEvent.distinct_id !== 'string') {
logger.error('⚠️', 'Invalid transformation result - distinct_id must be a string', {
function_id: hogFunction.id,
distinct_id: transformedEvent.distinct_id,
})
continue
}
event.distinct_id = transformedEvent.distinct_id
}
// Update globals so the next transformation sees the changes
globals.event.properties = event.properties
globals.event.event = event.event
globals.event.distinct_id = event.distinct_id
}
if (event.properties && restoreProtectedProperties(event.properties, protectedProperties)) {
hogTransformationProtectedPropertyWrites.inc()
}
return {
event,
invocationResults: results,
}
}
public transformEvent(event: PluginEvent, teamHogFunctions: HogFunctionType[]): Promise<TransformationResult> {
// These properties are retired, so drop any a client sends rather than letting them through
if (event.properties) {
for (const key of ['$transformations_failed', '$transformations_skipped', '$transformations_succeeded']) {
if (key in event.properties) {
delete event.properties[key]
}
}
}
return instrumentFn(`hogTransformer.transformEvent`, () => this.transformEventImpl(event, teamHogFunctions))
}
private async executeHogFunction(
hogFunction: HogFunctionType,
globals: HogFunctionInvocationGlobals
): Promise<CyclotronJobInvocationResult> {
const transformationFunctions = await this.getTransformationFunctions()
let globalsWithInputs: HogFunctionInvocationGlobalsWithInputs
try {
globalsWithInputs = await this.hogExecutor.buildInputsWithGlobals(hogFunction, globals)
} catch (error) {
// Returned rather than thrown, so the error reaches the transformation's own logs.
if (!(error instanceof HogConfigurationError)) {
throw error
}
return createInputsFailureResult(hogFunction, globals, error)
}
const invocation = createInvocation(globalsWithInputs, hogFunction)
const geoipNoop = geoipNoopResult(invocation)
if (geoipNoop) {
return geoipNoop
}
if (isLegacyPluginHogFunction(hogFunction)) {
return await this.pluginExecutor.execute(invocation)
}
if (this.rustVmExecutor) {
const sensitiveValues = this.hogExecutor.getSensitiveValues(hogFunction, globalsWithInputs.inputs)
const rustResult = this.config.hogRustVmBatchExecutionEnabled
? await this.rustVmExecutor.executeBatched(invocation, sensitiveValues)
: this.rustVmExecutor.execute(invocation, sensitiveValues)
// Null means the Rust VM can't run this program (addon not built, unsupported host
// function): fall through to the Node VM.
if (rustResult) {
return rustResult
}
}
return await this.hogExecutor.execute(invocation, { functions: transformationFunctions })
}
}
/** Config read by createHogTransformerService when running inside ingestion. */
export type HogTransformerServiceConfig = Pick<
CommonConfig,
| 'SITE_URL'
| 'CDP_HOG_RUST_VM_EXECUTION_ENABLED'
| 'CDP_HOG_RUST_VM_BATCH_EXECUTION_ENABLED'
| 'MMDB_FILE_LOCATION'
| 'TRANSFORMATIONS_HOG_TIMEOUT_MS'
> &
TransformationsMonitoringConfig
export interface HogTransformerServiceDeps {
geoipService: GeoIPService
postgres: PostgresRouter
pubSub: PubSub
encryptedFields: EncryptedFields
integrationManager: IntegrationManagerService
monitoringOutputs: IngestionOutputs<MonitoringOutput>
teamManager: Pick<TeamManager, 'getTeam'>
}
/**
* Keep this factory's config and dependencies intentionally minimal. Transformations run only the synchronous Hog
* execution core and must not inherit Redis, fetch, email, push, or other CDP delivery infrastructure just to satisfy
* a shared service constructor. Anything that needs those belongs in HogExecutorAsyncService, not in HogExecutorService.
*/
export function createHogTransformerService(
config: HogTransformerServiceConfig,
deps: HogTransformerServiceDeps
): HogTransformerService {
const hogFunctionManager = new HogFunctionManagerService(deps.postgres, deps.pubSub, deps.encryptedFields)
const hogInputsService = new HogInputsService(deps.integrationManager, undefined, deps.encryptedFields)
const hogExecutor = new HogExecutorService(
{ executionTimeoutMs: config.TRANSFORMATIONS_HOG_TIMEOUT_MS },
hogInputsService
)
const pluginExecutor = new LegacyPluginExecutorService(deps.postgres, deps.geoipService)
const hogFunctionMonitoringService = createTransformationsMonitoringService(
deps.monitoringOutputs,
config,
deps.teamManager
)
return new HogTransformerService(
hogFunctionManager,
hogExecutor,
hogFunctionMonitoringService,
pluginExecutor,
deps.geoipService,
{
siteUrl: config.SITE_URL,
hogRustVmExecutionEnabled: config.CDP_HOG_RUST_VM_EXECUTION_ENABLED,
hogRustVmBatchExecutionEnabled: config.CDP_HOG_RUST_VM_BATCH_EXECUTION_ENABLED,
mmdbFileLocation: config.MMDB_FILE_LOCATION,
}
)
}