feat(cli): forward perf breakdown + tmpPeakBytes to PostHog telemetry

[jrusso1020]

What

Forwards the new per-phase extraction breakdown and tmpPeakBytes fields from RenderPerfSummary (added in #444 and #446) to PostHog via the CLI's existing render_complete telemetry event.

Why

The CLI already ships render_complete events to PostHog (packages/cli/src/telemetry/client.ts), but events.ts:trackRenderComplete only carried a subset of RenderPerfSummary — top-level timings, composition dims, and memory snapshots. After #444 added per-phase extraction breakdown (videoExtractBreakdown) and #446 added cache hit/miss counters, the data lives on job.perfSummary at render-complete but never reaches PostHog dashboards.

Without this, any PostHog insight built around "how often are we hitting the cache?", "what's the median HDR preflight cost?", or "where in the extract phase do compositions spend time?" has to be answered by Datadog log scraping instead.

How

• packages/cli/src/telemetry/events.ts — extend trackRenderComplete props with 17 new optional fields: tmpPeakBytes, the six named stage timings, and the ten videoExtractBreakdown fields. All sent as flat properties (extract_cache_hits, stage_capture_ms, etc.) — PostHog insights query flat keys more ergonomically than nested objects.
• packages/cli/src/commands/render.ts — wire job.perfSummary.videoExtractBreakdown / stages / tmpPeakBytes into the trackRenderMetrics → trackRenderComplete hand-off.
• Naming: extract_phase3_ms deliberately disambiguates from stage_video_extract_ms — the former is just the parallel ffmpeg extract inside Phase 3; the latter is the full stage (resolve + probe + preflight + extract).
• All new fields are optional. The Docker-subprocess branch of render.ts that doesn't have a local perfSummary still compiles and ships events without them.

Test plan

• bun run --cwd packages/cli test — 161/161 pass
• bunx tsc -p packages/cli/tsconfig.json --noEmit — no errors
• bunx oxlint + bunx oxfmt — clean
• Once merged, verify PostHog receives the new properties on a real render event (run hyperframes render against a fixture and watch PostHog ingestion — telemetry auto-disables in CI, so this requires a local dev render with HYPERFRAMES_NO_TELEMETRY unset).

Stack

Depends on #444 (adds the videoExtractBreakdown + tmpPeakBytes fields to RenderPerfSummary) and transitively on #445 → #446.

Future work (not in this PR)

• The HeyGen internal producer server (hyperframes-internal/packages/producer/src/server.ts) logs perfSummary to Datadog via log.info but has no PostHog integration. Production renders are the bulk of the traffic — separate PR to either ship perfSummary to PostHog from the internal server, or materialize Datadog log-based metrics for per-phase timings.

[jrusso1020]

• feat(cli): forward perf breakdown + tmpPeakBytes to PostHog telemetry #454 👈 (View in Graphite)
• perf(engine): content-addressed extraction cache for video frames #446
• perf(engine): segment-scope SDR→HDR preflight #445
• perf(engine): extraction-phase instrumentation #444
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[miguel-heygen]

Review: feat(cli): forward perf breakdown + tmpPeakBytes to PostHog telemetry

Clean, mechanical wiring PR. 2 files, +56/-0, all additive. No issues.

What it does

Forwards 17 new optional fields from RenderPerfSummary to PostHog's render_complete event: tmpPeakBytes, 6 stage timings, and 10 videoExtractBreakdown fields (including cache hit/miss counters from #446).

What I checked

• Naming consistency — snake_case PostHog keys match the existing pattern. extract_phase3_ms vs stage_video_extract_ms disambiguation is correct and documented in the PR body.
• All fields optional — Docker-subprocess branch without a local perfSummary still compiles and ships events without them. Confirmed by the nullish chaining on perf?.stages, perf?.videoExtractBreakdown, perf?.tmpPeakBytes.
• No naming conflicts — the ...getMemorySnapshot() spread at the end uses peak_memory_mb / memory_free_mb, no overlap with the new stage_* / extract_* keys.
• Flat property layout — correct for PostHog. Nested objects would require JSON stringification and make insights queries harder.
• No cardinality concerns — all values are numeric (timings in ms, byte counts, integer counters). PostHog handles this fine.

One note (not blocking)

trackEvent will receive undefined for all 17 new properties when perf is null (the Docker-subprocess path). Most PostHog SDKs strip undefined values before sending, so this is fine — but if the SDK sends them as explicit nulls, it could clutter the event schema. Worth a quick check on the first real ingestion event (already in the test plan).

Verdict: Approve

No issues. Ship it.

[jrusso1020]

Rebased the stack onto current main + onto the updated #446. No code changes — <https://github.com/heygen-com/hyperframes/pull/454#pullrequestreview-4165039347|your review> was clean approval, and the downstream fixes on #444/#445/#446 don't touch any of the 17 new trackRenderComplete fields, so the wiring stays identical. bun run --cwd packages/cli test → 161/161 pass, typecheck clean.

On your non-blocking observation about undefined values on the Docker-subprocess path: still in the test plan to eyeball the first real ingestion event. PostHog's node SDK strips undefined before sending (confirmed via the SDK's normalize path), so worst case the schema shows the keys only on renders that carried a real perfSummary. Will spot-check once this lands.

[miguel-heygen]

Re-checked the live stacked head. The telemetry wiring remains clean on top of the updated engine stack, local CLI validation is clean, and the latest CI is green.

[jrusso1020]

Merge activity

• Apr 24, 4:40 AM UTC: @jrusso1020 merged this pull request with Graphite.