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.

11.4 KB
Raw Blame
import { LRUCache } from 'lru-cache'
import { DateTime } from 'luxon'
import { Counter, Histogram } from 'prom-client'

import { logger } from '~/common/utils/logger'

import { CyclotronJobInvocationHogFunction, CyclotronJobInvocationResult } from '../types'
import { createAddLogFunction, sanitizeLogMessage } from '../utils'
import { createInvocationResult } from '../utils/invocation-utils'
import {
    HogvmNodeModule,
    MARSHAL_ERROR_PREFIX,
    RUST_MAX_STEPS,
    RustExecResult,
    isUnsupportedByRustVm,
    loadHogvmNodeModule,
    programKey,
} from './rust-vm'
import { RustVmBatchScheduler } from './rust-vm-batch-scheduler'

/**
 * Executes transformation invocations on the Rust HogVM (via the `@posthog/hogvm-node` napi
 * addon) as the primary executor, producing the same `CyclotronJobInvocationResult` shape the
 * Node executor does. Invocations the Rust VM can't run — the addon isn't built, or the program
 * calls a host function the binding doesn't implement — return null so the caller falls back to
 * the Node VM.
 *
 * Two execution paths: `execute` runs one invocation synchronously on the JS thread
 * (`executeRegisteredSync`); `executeBatched` enqueues into a {@link RustVmBatchScheduler} that
 * coalesces same-program invocations into one `executeRegisteredBatch` FFI crossing per tick,
 * executed off the JS event loop. Both execute a program the addon registered once per distinct
 * bytecode, so the per-event cost is the globals crossing, not re-marshalling and re-decoding.
 */

export const rustVmExecution = new Counter({
    name: 'hogvm_rust_execution_total',
    help: 'Outcomes of transformation executions where the Rust HogVM is the primary executor',
    labelNames: ['outcome'],
})

export const rustVmExecutionDuration = new Histogram({
    name: 'hogvm_rust_execution_duration_ms',
    help: 'Per-invocation hog execution duration on the Rust HogVM as the primary executor',
    buckets: [0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 25, 50, 100],
})

export const rustVmProgramRegistrations = new Counter({
    name: 'hogvm_rust_program_registrations_total',
    help: 'Programs registered with the Rust HogVM after a miss in the handle cache',
})

/** Bounds the Rust-side registry: one entry per distinct program, shared by every function with that bytecode. */
export const MAX_REGISTERED_PROGRAMS = 500

type RegistryBindings = Required<
    Pick<HogvmNodeModule, 'registerProgram' | 'releaseProgram' | 'executeRegisteredSync' | 'executeRegisteredBatch'>
>

export class RustVmExecutor {
    private scheduler: RustVmBatchScheduler

    /**
     * Handles by bytecode content: every team has its own hog function row, so one template arrives
     * as thousands of functions with identical bytecode and registers once. `dispose` is the single
     * owner of releasing handles, so no caller releases directly and no handle is released twice.
     */
    private handles: LRUCache<string, number>

    constructor(private options: { mmdbPath: string }) {
        this.scheduler = new RustVmBatchScheduler(async (bytecode, events) => {
            const module_ = this.getModule()
            if (!module_) {
                // Unreachable in practice: executeBatched checks the module before enqueueing.
                throw new Error('Rust HogVM native module unavailable')
            }
            const registry = this.registryOf(module_)
            if (!registry) {
                return module_.executeBatch(bytecode, events, { parallel: true, maxSteps: RUST_MAX_STEPS })
            }
            // Resolve the handle in the same synchronous span as the FFI call: `handleFor`
            // re-registers an evicted program, and nothing can release the handle before the call.
            const handle = this.handleFor(registry, bytecode)
            return registry.executeRegisteredBatch(handle, events, { parallel: true, maxSteps: RUST_MAX_STEPS })
        })
        this.handles = new LRUCache({
            max: MAX_REGISTERED_PROGRAMS,
            dispose: (handle) => this.getModule()?.releaseProgram?.(handle),
        })
    }

    private getModule(): HogvmNodeModule | null {
        return loadHogvmNodeModule({ mmdbPath: this.options.mmdbPath })
    }

    /**
     * All four registry bindings, or null when the addon predates them: it is built and shipped
     * separately from this code, and the caller then executes unregistered instead of throwing.
     */
    private registryOf(module_: HogvmNodeModule): RegistryBindings | null {
        const { registerProgram, releaseProgram, executeRegisteredSync, executeRegisteredBatch } = module_
        if (!registerProgram || !releaseProgram || !executeRegisteredSync || !executeRegisteredBatch) {
            return null
        }
        return { registerProgram, releaseProgram, executeRegisteredSync, executeRegisteredBatch }
    }

    private handleFor(registry: RegistryBindings, bytecode: unknown[]): number {
        const key = programKey(bytecode)
        const cached = this.handles.get(key)
        if (cached !== undefined) {
            return cached
        }

        rustVmProgramRegistrations.inc()
        const handle = registry.registerProgram(bytecode)
        this.handles.set(key, handle)
        return handle
    }

    /**
     * Count and log a fallback so every node-vm handoff is attributable to a function. Returns
     * null for the caller to pass through.
     */
    private fallback(
        outcome: 'fallback_unsupported' | 'fallback_exception',
        invocation: CyclotronJobInvocationHogFunction,
        sensitiveValues: string[],
        error: unknown
    ): null {
        rustVmExecution.inc({ outcome })
        logger.warn('🦀', 'Rust HogVM invocation fell back to the node vm', {
            outcome,
            functionId: invocation.functionId,
            teamId: invocation.teamId,
            // Same redaction as hog print logs: marshalling errors and panic messages can embed
            // values from the invocation globals, which include secret inputs.
            error: error !== undefined ? sanitizeLogMessage([String(error)], sensitiveValues) : undefined,
        })
        return null
    }

    /**
     * Execute one transformation invocation on the Rust VM. Returns null when the Node VM must
     * run it instead.
     *
     * Runs through `executeRegisteredSync` on the JS thread — the same threading model as the Node VM's
     * exec, minus the work. Executions are sub-millisecond and bounded by the step budget, so a
     * libuv thread-hop per invocation would cost more than the execution it offloads.
     */
    public execute(
        invocation: CyclotronJobInvocationHogFunction,
        sensitiveValues: string[]
    ): CyclotronJobInvocationResult<CyclotronJobInvocationHogFunction> | null {
        const module_ = this.getModule()
        if (!module_) {
            // No per-invocation log: a missing addon affects every invocation and the loader
            // already warned once with the load error.
            rustVmExecution.inc({ outcome: 'fallback_unavailable' })
            return null
        }

        let rust
        try {
            const registry = this.registryOf(module_)
            rust = registry
                ? registry.executeRegisteredSync(
                      this.handleFor(registry, invocation.hogFunction.bytecode),
                      invocation.state.globals,
                      { maxSteps: RUST_MAX_STEPS }
                  )
                : module_.executeSync(invocation.hogFunction.bytecode, invocation.state.globals, {
                      maxSteps: RUST_MAX_STEPS,
                  })
        } catch (error) {
            // A throw here is the boundary or the native side, not the program's own error path —
            // marshalling failures (e.g. globals containing NaN or Infinity, which serde_json
            // can't represent), rust panics, addon bugs. Deliberately broad: the node vm can run
            // all of these, so correctness wins and the invocation falls back — while the warn log
            // and the fallback_exception outcome carry the error so native faults stay visible
            // rather than being silently healed.
            return this.fallback('fallback_exception', invocation, sensitiveValues, error)
        }

        return this.toInvocationResult(rust, invocation, sensitiveValues)
    }

    /**
     * Execute one transformation invocation via the batching scheduler: same-program invocations
     * in flight during the same tick share one `executeRegisteredBatch` call, off the JS event loop.
     * Returns null when the Node VM must run it instead — same fallback contract as `execute`,
     * with a batch event that failed JS→JSON conversion (`marshal_error:`) treated like the sync
     * path's boundary throw: that event alone falls back, having never executed.
     */
    public async executeBatched(
        invocation: CyclotronJobInvocationHogFunction,
        sensitiveValues: string[]
    ): Promise<CyclotronJobInvocationResult<CyclotronJobInvocationHogFunction> | null> {
        const module_ = this.getModule()
        if (!module_) {
            rustVmExecution.inc({ outcome: 'fallback_unavailable' })
            return null
        }

        let rust: RustExecResult
        try {
            rust = await this.scheduler.execute(invocation.hogFunction.bytecode, invocation.state.globals)
        } catch (error) {
            // A rejected batch never delivered results, so nothing executed — safe to fall back.
            return this.fallback('fallback_exception', invocation, sensitiveValues, error)
        }

        if (rust.error?.startsWith(MARSHAL_ERROR_PREFIX)) {
            return this.fallback('fallback_exception', invocation, sensitiveValues, rust.error)
        }

        return this.toInvocationResult(rust, invocation, sensitiveValues)
    }

    private toInvocationResult(
        rust: RustExecResult,
        invocation: CyclotronJobInvocationHogFunction,
        sensitiveValues: string[]
    ): CyclotronJobInvocationResult<CyclotronJobInvocationHogFunction> | null {
        if (rust.error && isUnsupportedByRustVm(rust.error)) {
            return this.fallback('fallback_unsupported', invocation, sensitiveValues, rust.error)
        }

        const durationMs = rust.durationUs / 1000
        rustVmExecutionDuration.observe(durationMs)

        const result = createInvocationResult<CyclotronJobInvocationHogFunction>(invocation)
        const addLog = createAddLogFunction(result.logs)
        result.invocation.state.timings.push({ kind: 'hog', duration_ms: durationMs })

        const eventId = invocation.state.globals.event?.uuid || 'Unknown event'

        for (const message of rust.logs ?? []) {
            result.logs.push({
                level: 'info',
                timestamp: DateTime.now(),
                message: sanitizeLogMessage([message], sensitiveValues),
            })
        }
        if (rust.logsTruncated) {
            addLog('warn', `Function exceeded maximum log entries. No more logs will be collected. Event: ${eventId}`)
        }

        if (rust.error) {
            rustVmExecution.inc({ outcome: 'error' })
            addLog('error', `Error executing function on event ${eventId}: ${rust.error}`)
            result.error = rust.error
            return result
        }

        rustVmExecution.inc({ outcome: 'executed' })
        if (rust.result) {
            result.execResult = rust.result
        }
        addLog('debug', `Function completed in ${Number(durationMs.toFixed(2))}ms.`)
        return result
    }
}