mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-17 07:05:28 +00:00
* 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 "-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>
162 lines
5.9 KiB
TypeScript
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(),
|
|
});
|
|
}
|