Files
hyperframes/packages/cli/src/server/studioRenderTelemetry.ts
T
miga-heygenandMiguel Ángel 71bb88719e feat(telemetry): render output-shape, adapter, count, and environment properties (#4017)
* feat(telemetry): add output-shape request facts to render events

output_resolution_preset, output_format, hdr_mode, video_frame_format,
and gif_fps_capped join render_complete/render_error, all threaded
from already-resolved RenderOptions/RenderPlan fields rather than
recomputed: createRenderPlan already computes gifFpsCapped (clamping a
requested --fps above 30 to 30 for --format gif) but only used it for
a console warning; this threads that same decision into RenderOptions
and telemetry. All five are known before the pipeline starts, so both
events carry them even when a render fails before a perfSummary
exists.

Also wires output_format/output_resolution_preset into Studio's
separate emitStudioRenderComplete/emitStudioRenderError path, since
Studio's request genuinely varies those two per-request. hdr_mode,
video_frame_format, and gif_fps_capped stay CLI-only: Studio exposes
no HDR-mode, video-frame-format, or GIF output control to users at
all, so there is no per-request value to report for those three.

Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>

* feat(telemetry): add adapters_used to render events

adapters_used lists the runtime deterministic adapters
(packages/core/src/runtime/adapters/) a composition exercises.
Investigated the actual codebase rather than the ticket's guessed
7-adapter list and found 12 real registered adapters (gsap, css,
waapi, animejs, lottie, three, typegpu, d3, leaflet, mapbox, maplibre,
google-maps) — the map/data-source adapters share the exact same
window.__hf<Name> registration mechanism and are equally real
"adapters used" facts, so all 12 are included.

Detection unions a live page.evaluate probe (piggybacked on the same
probeSession resolveCompositionElementCount already uses) with a
static regex fallback over the compiled HTML, since this is purely
observational with no gating role (unlike compositionElementCount) —
union strictly increases recall rather than needing one source of
truth. Threaded through the same plumbing chain as the already-merged
composition_element_tags/aroll_video_count/heygen_video_count.

Studio's emitStudioRenderComplete/emitStudioRenderError get this field
automatically, with no Studio-side code change, via the same shared
capture-observability spread heygen_video_count already uses.

Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>

* feat(telemetry): add audio/image/sub-composition/color-grading counts

audio_count, image_count, sub_composition_count, audio_group_count,
color_grading_count, and has_lut join composition_element_tags in the
same single scanElementTags pass — audio/image/audio-group counts read
from the scan's uncapped tag map so a 50+-distinct-tag composition
can't push a named count into the "other" bucket. sub_composition_count
counts data-composition-src mounts directly rather than reusing
collectSubCompositionSrcs, which dedupes by src and drops
placeholder/remote mounts (a different, smaller fact than the mount
count this field reports).

has_lut decodes the HTML-entity-escaped form of data-color-grading
before parsing, since linkedom's serializer re-emits it
&quot;-escaped on every compile-pipeline round-trip — without the
decode this silently reported false for every LUT-graded composition.
The LUT-presence check now mirrors normalizeLut's own definition of
"has a LUT" exactly, closing a gap where a blank or empty lut value
would have reported true.

Threaded through the same plumbing chain as the already-merged
per-tag/provenance/adapter fields; Studio's emitter picks these up
automatically via the shared capture-observability spread.

Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>

* feat(telemetry): add browser_version_major and ffmpeg_version_major

Both are already-run subprocess calls whose output was discarded:
readToolVersion (checkFFmpeg's preflight) already runs `ffmpeg
-version`, and chromeLaunchOutcome already runs `--version` as a
Chrome launch sanity probe on every render. A shared
extractMajorVersion helper pulls the first X.Y-shaped number from
either banner, threaded onto EnvironmentCheckOutcome/
EnvironmentCheckResult, then RenderOptions right after
runEnvironmentChecks resolves in the local render path only.

Docker renders never populate these two RenderOptions fields (the
containerized producer runs its own preflight the host CLI never
sees), so both properties come back absent there rather than
reporting the host's own toolchain versions for a render that didn't
use them.

Studio does not call runEnvironmentChecks or this ffmpeg/Chrome
preflight at all before creating a render job, so its render_complete/
render_error events will not carry these two properties unless
Studio's own startup path is separately instrumented — a genuine
parity gap, not an oversight in this change.

Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>

* feat(telemetry): add authoring_skill_source and authoring_skill_invalid

Both derive from resolution logic createRenderPlan already runs:
authoring_skill_source names whichever step actually won attribution
(an explicit --skill flag, or the skill persisted in hyperframes.json)
using the same flagSkill/projectConfigSkill values already computed
for authoringSkill itself, not a second lookup. authoring_skill_invalid
surfaces the raw --skill value when it fails slug-shape validation
(normalizeSkillSlug rejects malformed input, not unregistered skill
names) — this value already exists as RenderPlan.invalidAuthoringSkill
and already drives a CLI warning in present.ts; this change threads
the same field into telemetry rather than adding a parallel one.

Threaded through both RenderOptions builders in execute.ts (single and
batch render) and all three telemetry call sites in render.ts,
including the Docker path — skill attribution is a request-level fact
independent of which backend executes the render.

Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>

* feat(telemetry): add root_body_mismatch and root_body_delta_px_bucket

Measures the composition root's authored data-width/data-height
against the scaffold's own html/body CSS size, straight from the
compiled document string scanElementTags already scans — the
source-level fact, not runtime DOM state. init.ts's applyCompositionSizing
(the #4001 fix) only patches the live DOM after the browser loads this
same HTML, so this measurement stays meaningful whether or not that fix
ran for a given render.

Reuses @hyperframes/parsers' canvasScaffoldPatterns regexes (the same
ones packages/lint's root_dimensions_mismatch rule reads) for the CSS
side. Root-tag detection here is a lighter first-data-composition-id-match
heuristic, not lint's more thorough findRootTag (which also handles a
leading decorative <svg> defs block) — that helper isn't part of
@hyperframes/lint's public API, and expanding it is out of scope here.

The delta is bucketed (0 / 1-10 / 11-50 / 51+ px) rather than reported
raw, and both fields come back absent — not a false/"0" default — when
the root or the CSS block can't be read at all.

Threaded through the same plumbing as every other static-scan field
this week, including the live-capture-observability fallback used on a
crash that never reaches perfSummary.

Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>

* feat(telemetry): add hf_env_overrides (names only, capped at 20)

Reports the sorted names of HF_*/HYPERFRAMES_* env vars present when
createRenderPlan resolves — never their values, since several of these
carry filesystem paths. Snapshotting at plan-resolution time (the very
first line of the render command, before any pipeline code runs)
matters: this render's own preflight later injects
HYPERFRAMES_FFMPEG_PATH/HYPERFRAMES_FFPROBE_PATH into its own
process.env, which would otherwise make those two always read back as
"operator overrides" whether or not the operator ever set them.

Reports an empty array, never an absent key, when nothing is set,
matching every other capped/bucketed field added this week. Capped at
20 names, documented alongside the cap constant.

Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>

* fix(cli): stop clobbering studio render_complete fields, fix an env leak

trackRenderComplete's explicit audio_count/image_count/root_body_mismatch/
adapters_used/etc. keys, sourced from perfSummary.drawElement and only ever
populated on the CLI's own render.ts path, always won the object spread over
the observability-capture fallback those same keys share with trackRenderError,
even when the direct value was undefined. studioRenderTelemetry.ts's
emitStudioRenderComplete never populates drawElement, only the capture
fallback, so 24 fields silently came back missing from every studio-triggered
render_complete event despite Studio having computed and sent the capture
value. Each field now falls back to its captureXxx counterpart via a new
directOrCapture() helper when the direct field is absent, with regression
tests proving both the fallback and that the direct value still wins when
both are present.

Also excludes HF_SHADER_WORKER_ENTRY from hf_env_overrides: cli.ts sets this
on every invocation to point the bundled shader worker pool at its own file,
sharing the HF_ prefix by coincidence rather than because an operator set it.

Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>

* style: remove em and en dashes from added code comments

No behavior change. Rewrites 22 comment lines this PR's own diff introduced,
using a comma or a period where the dash separated two clauses.

Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>

* test(producer): add a temporary diagnostic for a CI-only rootBodyMismatch failure

Not a real fix. The rootBodyMismatch test group fails deterministically in
CI (confirmed on two runs of the same head) but will not reproduce locally
by any method tried, including an isolated file run, the exact combined
producer:test:unit command, a worker-count-constrained run, and a fresh
clone with a clean install and build matching CI's own steps.

This dumps the intermediate regex-match state for the simplest failing
fixture to stderr so the next CI run's log says what actually differs.
To be removed once that answer lands.

Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>

* test(producer): widen the rootBodyMismatch diagnostic to compare import paths

Still not a real fix. The previous diagnostic (ca4e73983) proved the
imported HTML_BODY_CSS_WIDTH_FIRST_RE has 4 capture groups in the failing
CI run instead of the 2 the source and production code expect, but it used
a dynamic import(), which can resolve through a different codepath than
renderOrchestrator.ts's static import. This adds a static import of the
same binding, a require.resolve() of the resolved file path, and a direct
read of that file's own regex line, so the next run can rule in or out a
static/dynamic resolution split versus a genuinely different file on disk.

Locally both imports agree (2 groups, same object, correct file). To be
removed once the CI answer lands.

Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>

* fix(producer): read the merged 4-group scaffold-size regex correctly

main merged #4012 while this branch was in flight, consolidating
HTML_BODY_CSS_WIDTH_FIRST_RE/HEIGHT_FIRST_RE from 2 capture groups (digits
only) to 4 (prefix text, digits, suffix text, digits) so cli's
applyResolutionPreset could reuse the same regex for its in-place replace.
detectRootBodySizeMismatch still read groups 1/2 as the digits, now the
prefix/suffix text, so Number() on them was NaN and every render's
rootBodyMismatch/rootBodyDeltaPxBucket silently came back undefined. Fixed
to read groups 2/4, matching lint's core.ts readHtmlBodyCssSize exactly.

Removes the temporary diagnostic test (ca4e73983, e2e384c8e) now that its
CI log gave the real answer: both a static and dynamic import of the
regex resolved to the same file, and that file's own content had 4 groups
because this branch's merge-base predates #4012, not because of any
resolution or caching difference. A fresh CI run confirmed no CI-only
failure remains after merging main and fixing the indices.

Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>

* chore: nudge CI (no workflow run triggered on previous push)

* chore: nudge CI again now that #4017 is out of draft

---------

Co-authored-by: Miguel Ángel <miguel.sierra@heygen.com>
2026-09-17 02:10:27 +00:00

162 lines
5.9 KiB
TypeScript

// ---------------------------------------------------------------------------
// Maps studio-triggered renders into the existing `render_complete` /
// `render_error` telemetry events with `source: "studio"`, so they land
// alongside CLI renders in one unified taxonomy.
//
// Kept in its own file so `studioServer.ts` only needs two function calls.
// ---------------------------------------------------------------------------
import { freemem } from "node:os";
import type { CanvasResolution, Fps } from "@hyperframes/core";
import { fpsToNumber } from "@hyperframes/core";
import type { RenderJob, RenderPerfSummary } from "@hyperframes/producer";
import { trackRenderComplete, trackRenderError } from "../telemetry/events.js";
import {
renderJobObservabilityTelemetryPayload,
renderObservabilityTelemetryPayload,
} from "../telemetry/renderObservability.js";
import { bytesToMb } from "../telemetry/system.js";
export interface StudioRenderOpts {
fps: Fps;
quality: string;
/** Output container format; Studio requests are constrained to these three. */
format?: "mp4" | "webm" | "mov";
/** Named canvas preset the Studio request asked for; undefined renders at the composition's native dimensions. */
outputResolution?: CanvasResolution;
// gif_fps_capped/hdr_mode/video_frame_format are deliberately absent: Studio
// has no gif/png-sequence option and createRenderJob never receives an
// hdrMode or videoFrameFormat from the Studio request type, so there is no
// per-request value: see the PR description for the full reasoning.
// Telemetry id of the browser user who triggered the render, so the render
// outcome joins their studio_session_start / studio_render_start events.
// Undefined for older studio clients → falls back to the install anonymousId.
distinctId?: string;
/**
* The browser profile that triggered this render has telemetry disabled.
*
* The CLI's own policy cannot see a localStorage opt-out or `DoNotTrack` in
* someone else's browser, so without this the server happily emitted
* render_complete / render_error for a user who had opted out — the events
* merely landed on the install id instead of theirs, which is worse, not
* better. Explicit `true` only: an old client sends nothing here, and that
* is not consent withdrawn.
*/
telemetryOptOut?: boolean;
}
type RenderCompleteProps = Parameters<typeof trackRenderComplete>[0];
function memSnapshot(): { peakMemoryMb: number; memoryFreeMb: number } {
return {
peakMemoryMb: bytesToMb(process.memoryUsage.rss()),
memoryFreeMb: bytesToMb(freemem()),
};
}
function stagesPayload(stages: Record<string, number>): Partial<RenderCompleteProps> {
return {
stageCompileMs: stages.compileMs,
stageVideoExtractMs: stages.videoExtractMs,
stageAudioProcessMs: stages.audioProcessMs,
stageCaptureMs: stages.captureMs,
stageCaptureSetupMs: stages.captureSetupMs,
stageCaptureFrameMs: stages.captureFrameMs,
stageEncodeMs: stages.encodeMs,
stageAssembleMs: stages.assembleMs,
};
}
function extractPayload(
extract: RenderPerfSummary["videoExtractBreakdown"],
): Partial<RenderCompleteProps> {
if (!extract) return {};
return {
extractResolveMs: extract.resolveMs,
extractHdrProbeMs: extract.hdrProbeMs,
extractHdrPreflightMs: extract.hdrPreflightMs,
extractHdrPreflightCount: extract.hdrPreflightCount,
extractVfrProbeMs: extract.vfrProbeMs,
extractVfrPreflightMs: extract.vfrPreflightMs,
extractVfrPreflightCount: extract.vfrPreflightCount,
extractPhase3Ms: extract.extractMs,
extractCacheHits: extract.cacheHits,
extractCacheMisses: extract.cacheMisses,
};
}
function perfPayload(
perf: RenderPerfSummary | undefined,
elapsedMs: number,
): Partial<RenderCompleteProps> {
if (!perf) return {};
const compositionDurationMs = Math.round(perf.compositionDurationSeconds * 1000);
const speedRatio =
compositionDurationMs > 0 && elapsedMs > 0
? Math.round((compositionDurationMs / elapsedMs) * 100) / 100
: undefined;
return {
workers: perf.workers,
compositionDurationMs,
compositionWidth: perf.resolution.width,
compositionHeight: perf.resolution.height,
totalFrames: perf.totalFrames,
speedRatio,
captureAvgMs: perf.captureAvgMs,
capturePeakMs: perf.capturePeakMs,
tmpPeakBytes: perf.tmpPeakBytes,
...stagesPayload(perf.stages),
...extractPayload(perf.videoExtractBreakdown),
...renderObservabilityTelemetryPayload(perf.observability),
};
}
export function emitStudioRenderError(
opts: StudioRenderOpts,
elapsedMs: number,
failedStage: string | undefined,
err: unknown,
job: RenderJob | undefined,
): void {
// `workers` is intentionally omitted: studio renders don't accept a
// user-supplied worker count (the producer picks its default), so on early
// failures we genuinely don't know one. The CLI side has the value from
// `options.workers` even before `job.perfSummary` exists; studio doesn't.
if (opts.telemetryOptOut === true) return;
trackRenderError({
fps: fpsToNumber(opts.fps),
quality: opts.quality,
docker: false,
source: "studio",
failedStage,
errorMessage: err instanceof Error ? err.message : String(err),
elapsedMs,
outputFormat: opts.format,
outputResolutionPreset: opts.outputResolution,
distinctId: opts.distinctId,
...renderJobObservabilityTelemetryPayload(job),
...memSnapshot(),
});
}
export function emitStudioRenderComplete(
opts: StudioRenderOpts,
elapsedMs: number,
perf: RenderPerfSummary | undefined,
): void {
if (opts.telemetryOptOut === true) return;
trackRenderComplete({
durationMs: elapsedMs,
fps: fpsToNumber(opts.fps),
quality: opts.quality,
docker: false,
gpu: false,
source: "studio",
outputFormat: opts.format,
outputResolutionPreset: opts.outputResolution,
distinctId: opts.distinctId,
...perfPayload(perf, elapsedMs),
...memSnapshot(),
});
}