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.

6.5 KB
Raw Blame

Session replay rasterizer

Temporal worker that converts session replays into MP4 videos using puppeteer-capture's HeadlessExperimental.beginFrame for deterministic virtual-time frame capture. Runs on a dedicated rasterization-task-queue.

Architecture

Temporal workflow (Python)
  └─ dispatches activity to rasterization-task-queue
       └─ Node.js worker picks it up
            ├─ rasterizeRecording (puppeteer-capture: deterministic frame capture)
            ├─ computeVideoTimestamps (map session time → video time)
            ├─ uploadToS3
            └─ return metadata

The worker maintains a warm Chromium browser pool — a single browser instance is reused across exports and recycled after N uses.

Screenshots default to JPEG (q=80) via a CDP session monkey-patch, giving ~30% faster frame capture than the hardcoded PNG in puppeteer-capture.

Directory structure

recording-rasterizer/
├── index.ts              ← thin entry point, delegates to temporal/worker.ts
├── rasterize-file.ts     ← offline render of a JSONL file (bin/rasterize-recording-file)
├── config.ts             ← environment variable configuration
├── errors.ts             ← RasterizationError class
├── logger.ts             ← pino logger factory
├── metrics.ts            ← Prometheus metrics
├── types.ts              ← input/output contracts
├── utils.ts              ← timing utilities
├── storage.ts            ← S3 upload and download
├── postprocess.ts        ← map inactivity periods to video timestamps
│
├── temporal/             ← Temporal integration
│   ├── worker.ts         ← worker bootstrap (browser pool, Temporal connection, metrics server)
│   └── activities.ts     ← activity handler (record → upload → cleanup)
│
├── capture/                  ← Puppeteer capture pipeline
│   ├── browser-pool.ts       ← warm Chromium lifecycle manager
│   ├── recorder.ts           ← orchestrates page setup → player load → capture
│   ├── capture-page.ts       ← viewport, CDP guards, callback error guards
│   ├── player.ts             ← PlayerController: message bridge, playback lifecycle
│   ├── capture.ts            ← frame capture loop with abort/timeout handling
│   ├── request-interceptor.ts ← request interception + stylesheet proxying
│   ├── block-proxy.ts        ← recording block fetcher (recording-api)
│   ├── file-block-source.ts  ← serves one JSONL file or allowlisted S3 object (source_s3_uri)
│   └── config.ts             ← input validation + capture config builder
│
└── __tests__/            ← all tests

Running locally

The rasterizer runs in Docker since beginFrame requires Linux chrome-headless-shell:

bin/temporal-recording-rasterizer-worker

This builds TypeScript locally, builds the Docker image (with hash-based caching), and starts the container with volume mounts for fast iteration.

Configuration

Key environment variables (see config.ts for full list):

Variable Default Description
SCREENSHOT_FORMAT jpeg Screenshot format for frame capture (jpeg or png)
SCREENSHOT_JPEG_QUALITY 80 JPEG quality (1-100), only used when format is jpeg
MAX_CONCURRENT_ACTIVITIES 4 Max parallel activities; fewer while memory or CPU is above target
TUNER_TARGET_MEMORY_USAGE 0.7 Above this fraction of pod memory, take only the first activity
TUNER_TARGET_CPU_USAGE 0.9 Above this fraction of pod CPU, take only the first activity
TUNER_RAMP_THROTTLE_MS 10000 Minimum wait between new activity slots above the first
BROWSER_RECYCLE_AFTER 100 Recycle Chromium after N page uses
MAX_IDLE_BROWSERS 2 Warm Chromiums kept alive; extras close on release
CAPTURE_BROWSER_LOGS 0 Forward browser console/error logs to worker logger
ENABLE_PLAYER_CSP 1 Script-locking CSP on the player page (0 disables)

Egress from the browser and the S3 client is routed through the proxy in HTTPS_PROXY/HTTP_PROXY. In production a missing proxy URL is a startup error; RASTERIZER_USE_PROXY=false explicitly disables containment.

Activity inputs

The rasterize-recording activity accepts RasterizeRecordingInput (see types.ts):

Field Required Default Description
session_id yes — Session to rasterize
team_id yes — Team ID
s3_bucket yes — S3 bucket for output
s3_key_prefix yes — S3 key prefix
playback_speed no 4 Playback speed multiplier
recording_fps no 24 Output video framerate
start_offset_s no — Start playback N seconds from session start
end_offset_s no — Stop playback N seconds from session start
trim no — Max output duration in seconds
max_virtual_time no — Max virtual time in seconds before stopping
output_format no mp4 Output video format (mp4, webm or gif)
recording_api_token no — Team-scoped read JWT relayed to recording-api
viewport_width no 1280 Capture viewport width
viewport_height no 720 Capture viewport height
show_metadata_footer no false Include metadata footer in output
skip_inactivity no true Skip inactive periods during playback
mouse_tail no true Show mouse trail in replay