Skip to content

Write HTML. Render video. Built for agents.

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.ts
index 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.ts
index 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 npm
const 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 object
const 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-duplication
refreshTelemetryPosture();
- 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.mjs
index 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-"));