Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
feat(cli): render telemetry reports how busy the machine's CPU was (#5646)
Miguel Ángel0e9f380c2e22
diff --git a/packages/cli/src/commands/render.test.ts b/packages/cli/src/commands/render.test.tsindex 1da6f7e30d..7a8a78066c 100644--- a/packages/cli/src/commands/render.test.ts+++ b/packages/cli/src/commands/render.test.ts@@ -1,5 +1,5 @@// fallow-ignore-file code-duplication-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from "vitest";import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";import { tmpdir } from "node:os";import { join } from "node:path";@@ -261,11 +261,31 @@ vi.mock("../utils/orphanCleanup.js", () => ({processParentPid: vi.fn((pid: number) => orphanCleanupState.parentPid(pid)),}));+const cpuSamplerState = vi.hoisted(() => ({+ samplers: [] as { requesterOptedIn: boolean; stopped: boolean }[],+}));+vi.mock("../telemetry/renderCpu.js", () => ({+ startRenderCpuSampler: (requesterOptedIn = true) => {+ const sampler = { requesterOptedIn, stopped: false };+ cpuSamplerState.samplers.push(sampler);+ return {+ stop: () => {+ sampler.stopped = true;+ return { cpuBusyAvgPct: 57, cpuBusyPeakPct: 90 };+ },+ };+ },+}));+// Collect the heavy render module once, after Vitest has hoisted the mocks// above. Keeping this import out of a hook means parallel monorepo contention// cannot turn module collection into a `beforeAll` timeout.const renderModule = await import("./render.js");+// A private folder, never a fixed /tmp path: a render writes history into its project.+const PROJECT_DIR = mkdtempSync(join(tmpdir(), "hf-render-project-"));+afterAll(() => rmSync(PROJECT_DIR, { recursive: true, force: true }));+describe("renderLocal browser GPU config", () => {const savedEnv = new Map<string, string | undefined>();const {@@ -314,9 +334,9 @@ describe("renderLocal browser GPU config", () => {await expect(runRenderLint({- project: { dir: "/tmp/project" },+ project: { dir: PROJECT_DIR },entryFile: undefined,- renderTarget: "/tmp/project/index.html",+ renderTarget: join(PROJECT_DIR, "index.html"),strictErrors: false,strictAll: false,effectiveQuiet: true,@@ -357,9 +377,9 @@ describe("renderLocal browser GPU config", () => {await expect(runRenderLint({- project: { dir: "/tmp/project" },+ project: { dir: PROJECT_DIR },entryFile: undefined,- renderTarget: "/tmp/project/index.html",+ renderTarget: join(PROJECT_DIR, "index.html"),strictErrors: false,strictAll: false,effectiveQuiet: false,@@ -400,9 +420,9 @@ describe("renderLocal browser GPU config", () => {await runRenderLint({- project: { dir: "/tmp/project" },+ project: { dir: PROJECT_DIR },entryFile: undefined,- renderTarget: "/tmp/project/index.html",+ renderTarget: join(PROJECT_DIR, "index.html"),strictErrors: false,strictAll: false,effectiveQuiet: false,@@ -417,9 +437,9 @@ describe("renderLocal browser GPU config", () => {logSpy.mockClear();await runRenderLint({- project: { dir: "/tmp/project" },+ project: { dir: PROJECT_DIR },entryFile: undefined,- renderTarget: "/tmp/project/index.html",+ renderTarget: join(PROJECT_DIR, "index.html"),strictErrors: false,strictAll: false,effectiveQuiet: false,@@ -471,10 +491,40 @@ describe("renderLocal browser GPU config", () => {delete process.env.HF_DE_PARALLEL_ROUTER;});+ it("reports the render's CPU use on render_complete and render_error and stops measuring", async () => {+ const { trackRenderComplete, trackRenderError } = await import("../telemetry/events.js");+ vi.mocked(trackRenderComplete).mockClear();+ vi.mocked(trackRenderError).mockClear();+ cpuSamplerState.samplers = [];+ const options = {+ fps: { num: 30, den: 1 },+ quality: "standard",+ format: "mp4",+ gpu: false,+ browserGpuMode: "software",+ hdrMode: "auto",+ quiet: true,+ throwOnError: true,+ } as const;++ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", options);+ producerState.executeImpl = async () => {+ throw new Error("capture failed");+ };+ await expect(renderLocal(PROJECT_DIR, "/tmp/out.mp4", options)).rejects.toThrow(+ "capture failed",+ );++ const cpu = { cpuBusyAvgPct: 57, cpuBusyPeakPct: 90 };+ expect(vi.mocked(trackRenderComplete).mock.calls[0]?.[0]).toMatchObject(cpu);+ expect(vi.mocked(trackRenderError).mock.calls[0]?.[0]).toMatchObject(cpu);+ expect(cpuSamplerState.samplers.map((s) => s.stopped)).toEqual([true, true]);+ });+it("cleans orphaned browser trees before starting a local render", async () => {orphanCleanupState.killed = 1;- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "standard",format: "mp4",@@ -503,7 +553,7 @@ describe("renderLocal browser GPU config", () => {};await expect(- renderLocal("/tmp/project", "/tmp/out.mp4", {+ renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "standard",format: "mp4",@@ -538,7 +588,7 @@ describe("renderLocal browser GPU config", () => {};const priorListeners = new Set(process.listeners(signal));- const render = renderLocal("/tmp/project", "/tmp/out.mp4", {+ const render = renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "standard",format: "mp4",@@ -585,7 +635,7 @@ describe("renderLocal browser GPU config", () => {await expect(renderLocal(- "/tmp/project",+ PROJECT_DIR,"/tmp/out.mp4",{fps: { num: 30, den: 1 },@@ -689,9 +739,9 @@ describe("renderLocal browser GPU config", () => {browserGpuMode: "software",hdrMode: "auto",} as const;- await renderLocal("/tmp/project", "/tmp/out.mp4", { ...options, quiet: true });- await renderLocal("/tmp/project", "/tmp/out.mp4", { ...options, quiet: false });- await renderLocal("/tmp/project", "/tmp/out.mp4", { ...options, quiet: true, debug: true });+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", { ...options, quiet: true });+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", { ...options, quiet: false });+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", { ...options, quiet: true, debug: true });expect(producerState.loggerLevels).toEqual(["warn", "info", "debug"]);});@@ -699,7 +749,7 @@ describe("renderLocal browser GPU config", () => {it("passes an explicit software override for --no-browser-gpu even when env requests hardware", async () => {setEnv("PRODUCER_BROWSER_GPU_MODE", "hardware");- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "standard",format: "mp4",@@ -740,7 +790,7 @@ describe("renderLocal browser GPU config", () => {});};- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "standard",format: "mp4",@@ -770,7 +820,7 @@ describe("renderLocal browser GPU config", () => {});it("forwards browserGpuMode='auto' into producer config (probe-then-choose)", async () => {- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "standard",format: "mp4",@@ -794,7 +844,7 @@ describe("renderLocal browser GPU config", () => {const prev = process.env.PRODUCER_FORCE_SCREENSHOT;process.env.PRODUCER_FORCE_SCREENSHOT = "true";try {- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "standard",format: "mp4",@@ -812,7 +862,7 @@ describe("renderLocal browser GPU config", () => {});it("keeps the screenshot clamp when --resolution supersamples", async () => {- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "standard",format: "mp4",@@ -828,7 +878,7 @@ describe("renderLocal browser GPU config", () => {});it("passes an explicit hardware override for default local browser GPU", async () => {- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "standard",format: "mp4",@@ -846,7 +896,7 @@ describe("renderLocal browser GPU config", () => {});it("passes preflight-resolved FFmpeg, FFprobe, and browser paths through env", async () => {- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "standard",format: "mp4",@@ -864,7 +914,7 @@ describe("renderLocal browser GPU config", () => {it("falls back to hardware encoding when FFmpeg omits libx264", async () => {ffmpegEncoderState.mode = "gpu";- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "high",format: "mp4",@@ -884,7 +934,7 @@ describe("renderLocal browser GPU config", () => {const stderr = vi.spyOn(console, "error").mockImplementation(() => undefined);await expect(- renderLocal("/tmp/project", "/tmp/out.mp4", {+ renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "high",format: "mp4",@@ -904,7 +954,7 @@ describe("renderLocal browser GPU config", () => {"does not require H.264 for %s",async (format) => {ffmpegEncoderState.encoders = " V....D libvpx-vp9 VP9\n";- await renderLocal("/tmp/project", `/tmp/out.${format}`, {+ await renderLocal(PROJECT_DIR, `/tmp/out.${format}`, {fps: { num: 30, den: 1 },quality: "high",format,@@ -921,7 +971,7 @@ describe("renderLocal browser GPU config", () => {"does not reject potential HEVC output in %s mode",async (hdrMode) => {ffmpegEncoderState.encoders = " V....D libx265 HEVC\n";- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "high",format: "mp4",@@ -938,7 +988,7 @@ describe("renderLocal browser GPU config", () => {ffmpegEncoderState.error = new Error("encoder probe timed out");const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "high",format: "mp4",@@ -956,7 +1006,7 @@ describe("renderLocal browser GPU config", () => {ffmpegEncoderState.error = new Error("encoder probe timed out");const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "high",format: "mp4",@@ -986,7 +1036,7 @@ describe("renderLocal browser GPU config", () => {});it("forwards parsed --variables payload to createRenderJob", async () => {- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "standard",format: "mp4",@@ -1001,7 +1051,7 @@ describe("renderLocal browser GPU config", () => {});it("forwards format: png-sequence through to createRenderJob", async () => {- await renderLocal("/tmp/project", "/tmp/frames", {+ await renderLocal(PROJECT_DIR, "/tmp/frames", {fps: { num: 30, den: 1 },quality: "standard",format: "png-sequence",@@ -1015,7 +1065,7 @@ describe("renderLocal browser GPU config", () => {});it("forwards format: hls and hlsSegmentSeconds through to createRenderJob", async () => {- await renderLocal("/tmp/project", "/tmp/stream", {+ await renderLocal(PROJECT_DIR, "/tmp/stream", {fps: { num: 30, den: 1 },quality: "standard",format: "hls",@@ -1037,7 +1087,7 @@ describe("renderLocal browser GPU config", () => {const stderr = vi.spyOn(console, "error").mockImplementation(() => undefined);await expect(- renderLocal("/tmp/project", "/tmp/stream", {+ renderLocal(PROJECT_DIR, "/tmp/stream", {fps: { num: 30, den: 1 },quality: "standard",format: "hls",@@ -1053,7 +1103,7 @@ describe("renderLocal browser GPU config", () => {});it("forwards format: gif and gifLoop through to createRenderJob", async () => {- await renderLocal("/tmp/project", "/tmp/demo.gif", {+ await renderLocal(PROJECT_DIR, "/tmp/demo.gif", {fps: { num: 15, den: 1 },quality: "standard",format: "gif",@@ -1069,7 +1119,7 @@ describe("renderLocal browser GPU config", () => {});it("forwards videoFrameFormat to createRenderJob", async () => {- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "standard",format: "mp4",@@ -1084,7 +1134,7 @@ describe("renderLocal browser GPU config", () => {});it("forwards debug mode to createRenderJob", async () => {- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "standard",format: "mp4",@@ -1099,7 +1149,7 @@ describe("renderLocal browser GPU config", () => {});it("defaults to best-effort readiness", async () => {- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "standard",format: "mp4",@@ -1113,7 +1163,7 @@ describe("renderLocal browser GPU config", () => {});it("forwards an explicit strict readiness opt-in", async () => {- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "standard",format: "mp4",@@ -1128,7 +1178,7 @@ describe("renderLocal browser GPU config", () => {});it("omits variables from createRenderJob when not provided", async () => {- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "standard",format: "mp4",@@ -1142,7 +1192,7 @@ describe("renderLocal browser GPU config", () => {});it("forwards entryFile to createRenderJob when --composition is set", async () => {- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "standard",format: "mp4",@@ -1157,7 +1207,7 @@ describe("renderLocal browser GPU config", () => {});it("omits entryFile from createRenderJob when --composition is not set", async () => {- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "standard",format: "mp4",@@ -1171,7 +1221,7 @@ describe("renderLocal browser GPU config", () => {});it("forwards --browser-timeout into resolveConfig as pageNavigationTimeout (ms)", async () => {- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "standard",format: "mp4",@@ -1188,7 +1238,7 @@ describe("renderLocal browser GPU config", () => {});it("forwards vp9CpuUsed into resolveConfig when set", async () => {- await renderLocal("/tmp/project", "/tmp/out.webm", {+ await renderLocal(PROJECT_DIR, "/tmp/out.webm", {fps: { num: 30, den: 1 },quality: "standard",format: "webm",@@ -1205,7 +1255,7 @@ describe("renderLocal browser GPU config", () => {});it("omits pageNavigationTimeout from resolveConfig when --browser-timeout is not set", async () => {- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "standard",format: "mp4",@@ -1223,7 +1273,7 @@ describe("renderLocal browser GPU config", () => {});it("forwards outputResolution to createRenderJob when --resolution is set", async () => {- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "standard",format: "mp4",@@ -1238,7 +1288,7 @@ describe("renderLocal browser GPU config", () => {});it("omits outputResolution from createRenderJob by default", async () => {- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "standard",format: "mp4",@@ -1256,7 +1306,7 @@ describe("renderLocal browser GPU config", () => {const { consumeCommandResult } = await import("../utils/commandResult.js");consumeCommandResult();- await renderLocal("/tmp/project", "/tmp/out.mp4", {+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {fps: { num: 30, den: 1 },quality: "standard",format: "mp4",@@ -1363,7 +1413,7 @@ describe("renderLocal — DE parallel-router circuit breaker", () => {telemetryNoticeShown: true,};delete process.env.HF_DE_PARALLEL_ROUTER;- await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();});@@ -1376,7 +1426,7 @@ describe("renderLocal — DE parallel-router circuit breaker", () => {telemetryNoticeShown: true,};process.env.HF_DE_PARALLEL_ROUTER = "true";- await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("true");});@@ -1389,7 +1439,7 @@ describe("renderLocal — DE parallel-router circuit breaker", () => {deParallelRouterTrialFired: false,telemetryNoticeShown: true,};- await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();});@@ -1400,7 +1450,7 @@ describe("renderLocal — DE parallel-router circuit breaker", () => {telemetryNoticeShown: true,};process.env.HF_DE_PARALLEL_ROUTER = "false";- await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");});@@ -1414,7 +1464,7 @@ describe("renderLocal — DE parallel-router circuit breaker", () => {deParallelRouterTrialFired: true,telemetryNoticeShown: true,};- await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");});@@ -1437,7 +1487,7 @@ describe("renderLocal — DE parallel-router circuit breaker", () => {drawElement: { parallelRouter: "reverted" },};};- await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");expect(configState.writeConfigCalls).toContainEqual(expect.objectContaining({ deParallelRouterTrialFired: true }),@@ -1459,7 +1509,7 @@ describe("renderLocal — DE parallel-router circuit breaker", () => {drawElement: { parallelRouter: "reverted" },};};- await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("true");});@@ -1473,7 +1523,7 @@ describe("renderLocal — DE parallel-router circuit breaker", () => {deParallelRouterTrialFired: false,telemetryNoticeShown: true,};- await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();});@@ -1489,7 +1539,7 @@ describe("renderLocal — DE parallel-router circuit breaker", () => {drawElement: { parallelRouter: "routed" },};};- await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);// A write DOES happen — the render-count backstop is tracked on every// engaged render — but it must not flip deParallelRouterTrialFired.expect(configState.writeConfigCalls).toContainEqual(@@ -1512,7 +1562,7 @@ describe("renderLocal — DE parallel-router circuit breaker", () => {drawElement: { parallelRouter: "reverted" },};};- await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);expect(configState.writeConfigCalls).toContainEqual(expect.objectContaining({ deParallelRouterTrialFired: true }),);@@ -1535,7 +1585,7 @@ describe("renderLocal — DE parallel-router circuit breaker", () => {drawElement: { parallelRouter: "none" },};};- await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);expect(configState.writeConfigCalls).toHaveLength(0);});@@ -1549,7 +1599,7 @@ describe("renderLocal — DE parallel-router circuit breaker", () => {job.errorDetails = { observability: { capture: { deParallelRouter: "routed" } } };throw new Error("render cancelled");};- await renderLocal("/tmp/project", "/tmp/out.mp4", { ...baseOptions, throwOnError: true }).catch(+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", { ...baseOptions, throwOnError: true }).catch(() => {},);// Still counts toward the render-count backstop (the router DID engage),@@ -1573,7 +1623,7 @@ describe("renderLocal — DE parallel-router circuit breaker", () => {job.errorDetails = { observability: { capture: { deParallelRouter: "reverted" } } };throw new Error("worker crashed even after fallback");};- await renderLocal("/tmp/project", "/tmp/out.mp4", { ...baseOptions, throwOnError: true }).catch(+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", { ...baseOptions, throwOnError: true }).catch(() => {},);expect(configState.writeConfigCalls).toContainEqual(@@ -1597,7 +1647,7 @@ describe("renderLocal — DE parallel-router circuit breaker", () => {drawElement: { parallelRouter: "routed" },};};- await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();expect(configState.disk.deParallelRouterTrialFired).toBe(false);@@ -1607,7 +1657,7 @@ describe("renderLocal — DE parallel-router circuit breaker", () => {drawElement: { parallelRouter: "reverted" },};};- await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);expect(configState.writeConfigCalls).toContainEqual(expect.objectContaining({ deParallelRouterTrialFired: true }),@@ -1629,7 +1679,7 @@ describe("renderLocal — DE parallel-router circuit breaker", () => {telemetryNoticeShown: true,};const { manageDeParallelRouterBreaker: _omitted, ...programmaticOptions } = baseOptions;- await renderLocal("/tmp/project", "/tmp/out.mp4", programmaticOptions);+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", programmaticOptions);expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();expect(configState.writeConfigCalls).toHaveLength(0);});@@ -1646,14 +1696,14 @@ describe("renderLocal — DE parallel-router circuit breaker", () => {drawElement: { parallelRouter: "routed" },};};- await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();// A real interactive user can't do this mid-batch, but a wrapper script// invoking the CLI programmatically in the same process could — the// explicit override must still win on the next call.process.env.HF_DE_PARALLEL_ROUTER = "false";- await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");});@@ -1674,7 +1724,7 @@ describe("renderLocal — DE parallel-router circuit breaker", () => {};for (let i = 0; i < 30; i++) {- await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);}expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();@@ -1700,7 +1750,7 @@ describe("renderLocal — DE parallel-router circuit breaker", () => {drawElement: { parallelRouter: "reverted" },};};- await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);expect(configState.disk.deParallelRouterTrialFired).toBe(true);// Two writes: the one whose mirror failed, then the retry that mirrored.@@ -1723,7 +1773,7 @@ describe("renderLocal — DE parallel-router circuit breaker", () => {drawElement: { parallelRouter: "reverted" },};};- await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);// The fired flag was verified and re-asserted (idempotent)...expect(configState.disk.deParallelRouterTrialFired).toBe(true);// ...but the render counter is deliberately NOT re-applied — a lost@@ -1745,14 +1795,14 @@ describe("renderLocal — DE parallel-router circuit breaker", () => {drawElement: { parallelRouter: "reverted" },};};- await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);// Nothing could persist...expect(configState.disk.deParallelRouterTrialFired).toBe(false);// ...but the in-process latch still blocks the next render from// re-running the path that just failed (review finding) — and now does// it by writing an explicit "false", since absent means ON.producerState.executeImpl = async () => undefined;- await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);+ await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");});});diff --git a/packages/cli/src/commands/render.ts b/packages/cli/src/commands/render.tsindex 8d08c1ce9c..c3dfd7178e 100644--- a/packages/cli/src/commands/render.ts+++ b/packages/cli/src/commands/render.ts@@ -92,6 +92,11 @@ import {type HyperframesConfig,} from "../telemetry/config.js";import { renderJobObservabilityTelemetryPayload } from "../telemetry/renderObservability.js";+import {+ startRenderCpuSampler,+ type RenderCpuSampler,+ type RenderCpuTelemetryPayload,+} from "../telemetry/renderCpu.js";import { bytesToMb } from "../telemetry/system.js";import { VERSION } from "../version.js";import { isDevMode } from "../utils/env.js";@@ -783,6 +788,7 @@ async function renderDocker(await registerRenderOutputOrWarn(projectDir, outputPath);const capture = await captureArtifactRevision(projectDir).catch(() => undefined);const startTime = Date.now();+ const cpu = startRenderCpuSampler();// Dev mode (tsx/ts-node) uses "latest" since the local version isn't on npmconst dockerVersion = isDevMode() ? "latest" : VERSION;@@ -796,6 +802,7 @@ async function renderDocker(try {imageTag = ensureDockerImage(dockerVersion, platform, options.quiet);} catch (error: unknown) {+ cpu.stop();const failure = describeDockerBuildFailure(error);errorBox(failure.title, failure.message, failure.hint);failCommand();@@ -861,10 +868,11 @@ async function renderDocker(child.on("error", (err) => reject(err));});} catch (error: unknown) {- handleRenderError(error, options, startTime, true, "Check Docker is running: docker info");+ handleRenderError(error, options, startTime, cpu, true, "Check Docker is running: docker info");}const elapsed = Date.now() - startTime;+ const cpuUsage = cpu.stop();// Docker child exited 0 → the containerized producer already validated// AND committed the artifact. Mirror renderLocal's post-success guarantee@@ -892,6 +900,7 @@ async function renderDocker(...renderOutputShapeTelemetryPayload(options),...renderEnvironmentTelemetryPayload(options),...getMemorySnapshot(),+ ...cpuUsage,}),);@@ -1058,6 +1067,7 @@ async function executeLocalRender(false;const startTime = Date.now();+ const cpu = startRenderCpuSampler();const logger = createRenderTelemetryLogger(producer.createConsoleLogger?.(options.debug ? "debug" : options.quiet ? "warn" : "info") ??createNoopProducerLogger(),@@ -1133,6 +1143,7 @@ async function executeLocalRender(error,options,startTime,+ cpu,false,inContainer ? "" : "Try --docker for containerized rendering",job.failedStage,@@ -1157,12 +1168,15 @@ async function executeLocalRender(maybeConsumeDeParallelRouterTrial(deParallelRouterActive, job, options.quiet);const elapsed = Date.now() - startTime;+ const cpuUsage = cpu.stop();if (job.outcome === "completed_with_warnings") {for (const warning of job.warnings) {console.warn(c.warn(` [${warning.code}] ${warning.message}`));}}- runPostRenderStep("trackRenderMetrics", () => trackRenderMetrics(job, elapsed, options, false));+ runPostRenderStep("trackRenderMetrics", () =>+ trackRenderMetrics(job, elapsed, options, false, cpuUsage),+ );runPostRenderStep("printRenderComplete", () =>printRenderComplete({outputPath,@@ -1700,6 +1714,7 @@ function handleRenderError(error: unknown,options: RenderOptions,startTime: number,+ cpu: RenderCpuSampler,docker: boolean,hint: string,failedStage?: string,@@ -1732,6 +1747,7 @@ function handleRenderError(failedStageCode: normalizeStageCode(failedStage || "pipeline"),...renderJobObservabilityTelemetryPayload(job),...getMemorySnapshot(),+ ...cpu.stop(),});// Failed renders join the recent-renders ring too — a bug report filed via// `hyperframes feedback` is MOST likely to be about a failed render.@@ -1786,6 +1802,7 @@ function trackRenderMetrics(elapsedMs: number,options: RenderOptions,docker: boolean,+ cpuUsage: RenderCpuTelemetryPayload,): void {// Successful render → recent-renders ring, so a later `hyperframes// feedback` can attach this render's telemetry id to the report.@@ -1909,6 +1926,7 @@ function trackRenderMetrics(extractCacheMisses: extract?.cacheMisses,...renderJobObservabilityTelemetryPayload(job),...getMemorySnapshot(),+ ...cpuUsage,});}diff --git a/packages/cli/src/server/studioRenderTelemetry.test.ts b/packages/cli/src/server/studioRenderTelemetry.test.tsindex 8e0762dd6a..0b9e1c0b18 100644--- a/packages/cli/src/server/studioRenderTelemetry.test.ts+++ b/packages/cli/src/server/studioRenderTelemetry.test.ts@@ -259,6 +259,14 @@ describe("studioRenderTelemetry", () => {});});+ it("forwards the render's CPU use on both events", () => {+ const cpu = { cpuBusyAvgPct: 57, cpuBusyPeakPct: 90, cpuCoresBusyPeak: 2 };+ emitStudioRenderComplete(opts, 5000, fullPerf, cpu);+ emitStudioRenderError(opts, 100, "encode", new Error("x"), undefined, cpu);+ expect(trackRenderComplete.mock.calls[0]![0]).toMatchObject(cpu);+ expect(trackRenderError.mock.calls[0]![0]).toMatchObject(cpu);+ });+describe("emitStudioRenderError", () => {it("tags with source: 'studio' and forwards failedStage + elapsedMs", () => {emitStudioRenderError(opts, 1200, "encode", new Error("boom"), undefined);diff --git a/packages/cli/src/server/studioRenderTelemetry.ts b/packages/cli/src/server/studioRenderTelemetry.tsindex b722d33d96..b0b1073bfd 100644--- a/packages/cli/src/server/studioRenderTelemetry.ts+++ b/packages/cli/src/server/studioRenderTelemetry.ts@@ -16,6 +16,7 @@ import {renderObservabilityTelemetryPayload,} from "../telemetry/renderObservability.js";import { bytesToMb } from "../telemetry/system.js";+import type { RenderCpuTelemetryPayload } from "../telemetry/renderCpu.js";export interface StudioRenderOpts {fps: Fps;@@ -118,6 +119,7 @@ export function emitStudioRenderError(failedStage: string | undefined,err: unknown,job: RenderJob | undefined,+ cpuUsage: RenderCpuTelemetryPayload = {},): void {// `workers` is intentionally omitted: studio renders don't accept a// user-supplied worker count (the producer picks its default), so on early@@ -138,6 +140,7 @@ export function emitStudioRenderError(distinctId: opts.distinctId,...renderJobObservabilityTelemetryPayload(job),...memSnapshot(),+ ...cpuUsage,});}@@ -145,6 +148,7 @@ export function emitStudioRenderComplete(opts: StudioRenderOpts,elapsedMs: number,perf: RenderPerfSummary | undefined,+ cpuUsage: RenderCpuTelemetryPayload = {},): void {if (opts.telemetryOptOut === true) return;trackRenderComplete({@@ -159,5 +163,6 @@ export function emitStudioRenderComplete(distinctId: opts.distinctId,...perfPayload(perf, elapsedMs),...memSnapshot(),+ ...cpuUsage,});}diff --git a/packages/cli/src/server/studioServer.test.ts b/packages/cli/src/server/studioServer.test.tsindex 339bf856c2..6094df01b1 100644--- a/packages/cli/src/server/studioServer.test.ts+++ b/packages/cli/src/server/studioServer.test.ts@@ -75,6 +75,22 @@ vi.mock("../browser/manager.js", () => ({ensureBrowser: async () => ({ executablePath: undefined, source: "system" }),}));+const cpuSamplerState = vi.hoisted(() => ({+ samplers: [] as { requesterOptedIn: boolean; stopped: boolean }[],+}));+vi.mock("../telemetry/renderCpu.js", () => ({+ startRenderCpuSampler: (requesterOptedIn = true) => {+ const sampler = { requesterOptedIn, stopped: false };+ cpuSamplerState.samplers.push(sampler);+ return {+ stop: () => {+ sampler.stopped = true;+ return { cpuBusyAvgPct: 57, cpuBusyPeakPct: 90 };+ },+ };+ },+}));+// Lets one test hold the project history in its opening; every other test opens the real one.const historyState = vi.hoisted(() => ({open: null as null | ((...args: unknown[]) => Promise<unknown>),@@ -347,6 +363,51 @@ describe("createStudioServer shutdown", () => {expect(meta.audioLoweredDb).toBe(1.44);});+ it("stops measuring CPU however a render ends, and never for an opted-out requester", async () => {+ cpuSamplerState.samplers = [];+ const outDir = mkdtempSync(join(tmpdir(), "hf-render-cpu-"));+ server = createStudioServer({ projectDir: tmpProject() });++ producerState.executeRenderJob = async () => {};+ const done = server.adapter.startRender(startRenderOpts("job-done", join(outDir, "a.mp4")));+ await vi.waitFor(() => expect(done.status, done.error).toBe("complete"), { timeout: 5_000 });++ producerState.executeRenderJob = async () => {+ throw new Error("boom");+ };+ const failed = server.adapter.startRender({+ ...startRenderOpts("job-failed", join(outDir, "b.mp4")),+ telemetryOptOut: true,+ });+ await vi.waitFor(() => expect(failed.status).toBe("failed"), { timeout: 5_000 });++ let started!: () => void;+ const startedPromise = new Promise<void>((resolve) => {+ started = resolve;+ });+ producerState.executeRenderJob = (_job, _dir, _outputPath, _onProgress, signal) => {+ started();+ return new Promise((_resolve, reject) => {+ const onAbort = () => reject(Object.assign(new Error("cancelled"), { name: "AbortError" }));+ if (signal.aborted) onAbort();+ else signal.addEventListener("abort", onAbort);+ });+ };+ const cancelled = server.adapter.startRender(+ startRenderOpts("job-cancelled", join(outDir, "c.mp4")),+ );+ await untilStarted(startedPromise, cancelled);+ cancelled.cancel?.();+ await vi.waitFor(() => expect(cancelled.status).toBe("cancelled"), { timeout: 5_000 });++ expect(cpuSamplerState.samplers).toEqual([+ { requesterOptedIn: true, stopped: true },+ { requesterOptedIn: false, stopped: true },+ { requesterOptedIn: true, stopped: true },+ ]);+ rmSync(outDir, { recursive: true, force: true });+ });+it("cancels an in-flight render's signal and waits for it before draining the browser pool", async () => {const events: string[] = [];let started!: () => void;diff --git a/packages/cli/src/server/studioServer.ts b/packages/cli/src/server/studioServer.tsindex 625cc0ddb3..ca404a0ec1 100644--- a/packages/cli/src/server/studioServer.ts+++ b/packages/cli/src/server/studioServer.ts@@ -32,6 +32,7 @@ import {resolveCliTelemetryDistinctId,} from "./telemetryIdentity.js";import { emitStudioRenderComplete, emitStudioRenderError } from "./studioRenderTelemetry.js";+import { startRenderCpuSampler } from "../telemetry/renderCpu.js";import { mountDesktopRoutes } from "./desktopRoutes.js";import { isDevMode } from "../utils/env.js";import { runRenderSetupWorker } from "../utils/cancellableProcess.js";@@ -591,6 +592,7 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {// Run render asynchronously, mutating the state objectconst startTime = Date.now();+ const cpu = startRenderCpuSampler(opts.telemetryOptOut !== true);const run = (async () => {let renderJob: RenderJob | undefined;const removeCancelledOutput = () => {@@ -669,7 +671,7 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {// /api/telemetry-identity, so this process would otherwise keep its// startup-cached posture for the life of the preview server.refreshTelemetryPosture();- emitStudioRenderComplete(opts, Date.now() - startTime, job.perfSummary);+ emitStudioRenderComplete(opts, Date.now() - startTime, job.perfSummary, cpu.stop());} catch (err) {if (abortController.signal.aborted) {removeCancelledOutput();@@ -679,13 +681,22 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {state.error = err instanceof Error ? err.message : String(err);// fallow-ignore-next-line code-duplicationrefreshTelemetryPosture();- emitStudioRenderError(opts, Date.now() - startTime, state.stage, err, renderJob);+ emitStudioRenderError(+ opts,+ Date.now() - startTime,+ state.stage,+ err,+ renderJob,+ cpu.stop(),+ );try {const metaPath = opts.outputPath.replace(/\.(mp4|webm|mov)$/, ".meta.json");writeFileSync(metaPath, JSON.stringify({ status: "failed" }));} catch {/* ignore */}+ } finally {+ cpu.stop();}})();inFlightRenders.set(abortController, run);diff --git a/packages/cli/src/telemetry/events.test.ts b/packages/cli/src/telemetry/events.test.tsindex 3db004d99f..a93fae90d2 100644--- a/packages/cli/src/telemetry/events.test.ts+++ b/packages/cli/src/telemetry/events.test.ts@@ -398,6 +398,35 @@ describe("render telemetry events", () => {expect(props.browser_version_major).toBe(118);});+ it("carries machine CPU use on render_complete and render_error", () => {+ const cpu = {+ cpuBusyAvgPct: 57,+ cpuBusyPeakPct: 90,+ cpuCoresBusyPeak: 2,+ loadAvgStart: 1.23,+ loadAvgEnd: 3.46,+ };+ trackRenderComplete({+ durationMs: 1,+ fps: 30,+ quality: "draft",+ docker: false,+ gpu: false,+ ...cpu,+ });+ trackRenderError({ fps: 30, quality: "draft", docker: false, ...cpu });+ for (const [, props] of trackEvent.mock.calls) {+ expect(props).toMatchObject({+ cpu_busy_avg_pct: 57,+ cpu_busy_peak_pct: 90,+ cpu_cores_busy_peak: 2,+ load_avg_start: 1.23,+ load_avg_end: 3.46,+ });+ }+ expect(trackEvent).toHaveBeenCalledTimes(2);+ });+it("carries the browser install path facts on both render events, never the path", () => {const browserInstall = {build: "152.0.7928.2",diff --git a/packages/cli/src/telemetry/events.ts b/packages/cli/src/telemetry/events.tsindex d91fb86ff0..d2560aac6a 100644--- a/packages/cli/src/telemetry/events.ts+++ b/packages/cli/src/telemetry/events.ts@@ -7,6 +7,7 @@ import type { CatalogUsage } from "../utils/catalogUsage.js";import { flush, shouldTrack, trackEvent } from "./client.js";import { readConfig } from "./config.js";import { getPowerState } from "./system.js";+import type { RenderCpuTelemetryPayload } from "./renderCpu.js";import { CliRuntimeError } from "../utils/commandResult.js";// Power state is volatile (a laptop docks/undocks mid-session), so it is@@ -255,6 +256,16 @@ function renderEnvironmentEventProperties(props: RenderEnvironmentTelemetryPaylo};}+function renderCpuEventProperties(props: RenderCpuTelemetryPayload) {+ return {+ cpu_busy_avg_pct: props.cpuBusyAvgPct,+ cpu_busy_peak_pct: props.cpuBusyPeakPct,+ cpu_cores_busy_peak: props.cpuCoresBusyPeak,+ load_avg_start: props.loadAvgStart,+ load_avg_end: props.loadAvgEnd,+ };+}+function redactTelemetryMessage(value: string): string {return redactTelemetryString(value);}@@ -470,7 +481,8 @@ export function trackRenderComplete(distinctId?: string;} & RenderObservabilityTelemetryPayload &RenderOutputShapeTelemetryPayload &- RenderEnvironmentTelemetryPayload,+ RenderEnvironmentTelemetryPayload &+ RenderCpuTelemetryPayload,): void {trackEvent("render_complete",@@ -593,6 +605,7 @@ export function trackRenderComplete(source: props.source ?? "cli",...renderOutputShapeEventProperties(props),...renderEnvironmentEventProperties(props),+ ...renderCpuEventProperties(props),composition_duration_ms: props.compositionDurationMs,composition_width: props.compositionWidth,composition_height: props.compositionHeight,@@ -666,7 +679,8 @@ export function trackRenderError(distinctId?: string;} & RenderObservabilityTelemetryPayload &RenderOutputShapeTelemetryPayload &- RenderEnvironmentTelemetryPayload,+ RenderEnvironmentTelemetryPayload &+ RenderCpuTelemetryPayload,): void {trackEvent("render_error",@@ -688,6 +702,7 @@ export function trackRenderError(elapsed_ms: props.elapsedMs,...renderOutputShapeEventProperties(props),...renderEnvironmentEventProperties(props),+ ...renderCpuEventProperties(props),peak_memory_mb: props.peakMemoryMb,memory_free_mb: props.memoryFreeMb,...powerStateFields(),diff --git a/packages/cli/src/telemetry/renderCpu.test.ts b/packages/cli/src/telemetry/renderCpu.test.tsnew file mode 100644index 0000000000..0b20dfedf0--- /dev/null+++ b/packages/cli/src/telemetry/renderCpu.test.ts@@ -0,0 +1,116 @@+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";++const osState = vi.hoisted(() => ({+ readings: [] as { busy: number; idle: number }[][],+ cpuReads: 0,+ loads: [] as number[],+ platform: "linux",+}));+vi.mock("node:os", async (importOriginal) => ({+ ...(await importOriginal<typeof import("node:os")>()),+ cpus: () => {+ const cores = osState.readings[osState.cpuReads++] ?? [];+ return cores.map(({ busy, idle }) => ({+ model: "test",+ speed: 1,+ times: { user: busy, nice: 0, sys: 0, idle, irq: 0 },+ }));+ },+ loadavg: () => [osState.loads.shift() ?? 0, 0, 0],+ platform: () => osState.platform,+}));++const trackingState = vi.hoisted(() => ({ shouldTrack: true }));+vi.mock("./client.js", () => ({ shouldTrack: () => trackingState.shouldTrack }));++const { startRenderCpuSampler, SAMPLE_INTERVAL_MS } = await import("./renderCpu.js");++// Cumulative per-core times for two cores: start, two interval samples, stop.+// Windows: 90% (both cores busy), 30%, then 50% (one core busy). Start to end: 3400/6000.+const READINGS = [+ [+ { busy: 0, idle: 0 },+ { busy: 0, idle: 0 },+ ],+ [+ { busy: 900, idle: 100 },+ { busy: 900, idle: 100 },+ ],+ [+ { busy: 1200, idle: 800 },+ { busy: 1200, idle: 800 },+ ],+ [+ { busy: 2100, idle: 900 },+ { busy: 1300, idle: 1700 },+ ],+];++describe("startRenderCpuSampler", () => {+ beforeEach(() => {+ vi.useFakeTimers();+ osState.readings = READINGS;+ osState.cpuReads = 0;+ osState.loads = [1.234, 3.456];+ osState.platform = "linux";+ trackingState.shouldTrack = true;+ });+ afterEach(() => {+ vi.useRealTimers();+ });++ it("reports the render's average, its busiest sample window, and load at start and end", () => {+ const sampler = startRenderCpuSampler();+ vi.advanceTimersByTime(SAMPLE_INTERVAL_MS * 2);++ expect(sampler.stop()).toEqual({+ cpuBusyAvgPct: 57,+ cpuBusyPeakPct: 90,+ cpuCoresBusyPeak: 2,+ loadAvgStart: 1.23,+ loadAvgEnd: 3.46,+ });+ });++ it("clears its interval on stop and returns the first result on a repeat stop", () => {+ const sampler = startRenderCpuSampler();+ expect(vi.getTimerCount()).toBe(1);+ vi.advanceTimersByTime(SAMPLE_INTERVAL_MS * 2);+ const first = sampler.stop();++ expect(vi.getTimerCount()).toBe(0);+ expect(sampler.stop()).toBe(first);+ expect(osState.cpuReads).toBe(4);+ });++ it("measures a render shorter than one sample window from its start and end", () => {+ osState.readings = [READINGS[0]!, READINGS[3]!];+ const sampler = startRenderCpuSampler();++ expect(sampler.stop()).toMatchObject({+ cpuBusyAvgPct: 57,+ cpuBusyPeakPct: 57,+ cpuCoresBusyPeak: 0,+ });+ });++ it("leaves load average out on Windows, where Node always reports 0", () => {+ osState.platform = "win32";+ const usage = startRenderCpuSampler().stop();++ expect(usage.loadAvgStart).toBeUndefined();+ expect(usage.loadAvgEnd).toBeUndefined();+ });++ it.each([+ ["telemetry is off", false, true],+ ["the requester opted out", true, false],+ ])("samples nothing when %s", (_label, tracking, requesterOptedIn) => {+ trackingState.shouldTrack = tracking;+ const sampler = startRenderCpuSampler(requesterOptedIn);++ expect(vi.getTimerCount()).toBe(0);+ expect(sampler.stop()).toEqual({});+ expect(osState.cpuReads).toBe(0);+ });+});diff --git a/packages/cli/src/telemetry/renderCpu.ts b/packages/cli/src/telemetry/renderCpu.tsnew file mode 100644index 0000000000..8e47b81ec9--- /dev/null+++ b/packages/cli/src/telemetry/renderCpu.ts@@ -0,0 +1,93 @@+import { cpus, loadavg, platform } from "node:os";+import { shouldTrack } from "./client.js";++// System-wide, not process CPU: a render's work runs in Chrome and FFmpeg+// child processes, so the CLI's own process.cpuUsage() would miss most of it.++/** How busy the machine's CPUs were during one render; shared by render_complete/render_error. */+export interface RenderCpuTelemetryPayload {+ /** Busy share of all cores, render start to end, 0-100. */+ cpuBusyAvgPct?: number;+ /** Busiest sample window's busy share of all cores, 0-100. */+ cpuBusyPeakPct?: number;+ /** Cores at or above BUSY_CORE_PCT in the busiest sample window. */+ cpuCoresBusyPeak?: number;+ /** One-minute load average; absent on Windows, where Node always reports 0. */+ loadAvgStart?: number;+ loadAvgEnd?: number;+}++export interface RenderCpuSampler {+ /** Clears the sampling interval; idempotent, later calls return the first result. */+ stop(): RenderCpuTelemetryPayload;+}++export const SAMPLE_INTERVAL_MS = 2000;+const BUSY_CORE_PCT = 80;++type CoreTimes = { busy: number; total: number }[];++function readCoreTimes(): CoreTimes {+ return cpus().map(({ times }) => {+ const total = times.user + times.nice + times.sys + times.idle + times.irq;+ return { busy: total - times.idle, total };+ });+}++function busyBetween(from: CoreTimes, to: CoreTimes): { pct: number; coresBusy: number } | null {+ let busy = 0;+ let total = 0;+ let coresBusy = 0;+ to.forEach((core, i) => {+ const before = from[i];+ if (!before) return;+ const dBusy = core.busy - before.busy;+ const dTotal = core.total - before.total;+ if (dTotal <= 0) return;+ busy += dBusy;+ total += dTotal;+ if ((dBusy / dTotal) * 100 >= BUSY_CORE_PCT) coresBusy++;+ });+ return total > 0 ? { pct: Math.round((busy / total) * 100), coresBusy } : null;+}++function readLoadAvg(): number | undefined {+ if (platform() === "win32") return undefined;+ return Math.round((loadavg()[0] ?? 0) * 100) / 100;+}++const DISABLED: RenderCpuSampler = { stop: () => ({}) };++/** Start at render start; samples nothing when telemetry is off or the requester opted out. */+export function startRenderCpuSampler(requesterOptedIn = true): RenderCpuSampler {+ if (!requesterOptedIn || !shouldTrack()) return DISABLED;+ const start = readCoreTimes();+ const loadAvgStart = readLoadAvg();+ let last = start;+ let peak: { pct: number; coresBusy: number } | null = null;+ const sample = () => {+ const now = readCoreTimes();+ const window = busyBetween(last, now);+ if (window && (!peak || window.pct > peak.pct)) peak = window;+ last = now;+ };+ const timer = setInterval(sample, SAMPLE_INTERVAL_MS);+ timer.unref?.();+ let result: RenderCpuTelemetryPayload | undefined;+ return {+ stop() {+ if (result) return result;+ clearInterval(timer);+ sample();+ const avg = busyBetween(start, last);+ result = {+ cpuBusyAvgPct: avg?.pct,+ cpuBusyPeakPct: peak?.pct,+ cpuCoresBusyPeak: peak?.coresBusy,+ loadAvgStart,+ loadAvgEnd: readLoadAvg(),+ };+ return result;+ },+ };+}diff --git a/scripts/ci/cli-telemetry-e2e.mjs b/scripts/ci/cli-telemetry-e2e.mjsindex 821bb5265c..4c0062bb56 100644--- a/scripts/ci/cli-telemetry-e2e.mjs+++ b/scripts/ci/cli-telemetry-e2e.mjs@@ -421,6 +421,28 @@ check(typeof posEvent.browser_version_major === "number" && posEvent.browser_version_major > 0,posEvent.browser_version_major,);+const isPct = (v) => typeof v === "number" && v >= 0 && v <= 100;+check(+ "cpu_busy_avg_pct is a percentage",+ isPct(posEvent.cpu_busy_avg_pct),+ posEvent.cpu_busy_avg_pct,+);+check(+ "cpu_busy_peak_pct is a percentage at or above the average",+ isPct(posEvent.cpu_busy_peak_pct) && posEvent.cpu_busy_peak_pct >= posEvent.cpu_busy_avg_pct,+ posEvent.cpu_busy_peak_pct,+);+check(+ "cpu_cores_busy_peak is a core count",+ Number.isInteger(posEvent.cpu_cores_busy_peak) &&+ posEvent.cpu_cores_busy_peak <= posEvent.cpu_count,+ posEvent.cpu_cores_busy_peak,+);+check(+ "load_avg_start and load_avg_end are present",+ typeof posEvent.load_avg_start === "number" && typeof posEvent.load_avg_end === "number",+ [posEvent.load_avg_start, posEvent.load_avg_end],+);console.log("render: negative fixture (no media, root/body matched, no skill flag, clean env)");const negDir = mkdtempSync(join(sandbox, "render-neg-"));