Skip to content

Commit eed3552

Browse files
committed
feat(studio): track timeline performance
1 parent 1481fe1 commit eed3552

5 files changed

Lines changed: 232 additions & 0 deletions

File tree

‎packages/studio/src/player/components/Timeline.tsx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ import { useTrackGapMenu } from "./useTrackGapMenu";
3636
import { useTimelineGapHighlights } from "./useTimelineGapHighlights";
3737
import { useStudioPlaybackContextOptional } from "../../contexts/StudioContext";
3838
import { TimelineRazorGuide, useTimelineRazorInteraction } from "./TimelineRazorInteraction";
39+
import { useTimelinePerformanceTelemetry } from "./useTimelinePerformanceTelemetry";
3940

4041
// Re-export pure utilities so existing imports from "./Timeline" still resolve.
4142
export {
@@ -276,6 +277,11 @@ export const Timeline = memo(function Timeline({
276277
});
277278

278279
const displayLayout = useTimelineDisplayLayout(draggedClip, trackOrder, rowHeights);
280+
const { recordTimelineScroll } = useTimelinePerformanceTelemetry({
281+
totalClipCount: expandedElements.length,
282+
totalRowCount: displayLayout.displayTrackOrder.length,
283+
zoomMode,
284+
});
279285
const { viewportWidth, showShortcutHint, setScrollRef } = useTimelineScrollViewport(scrollRef, [
280286
timelineReady,
281287
expandedElements.length,
@@ -469,6 +475,7 @@ export const Timeline = memo(function Timeline({
469475
className={`${zoomMode === "fit" ? "overflow-x-hidden" : "overflow-x-auto"} overflow-y-auto h-full outline-none`}
470476
onScroll={(e) => {
471477
lastScrollLeftRef.current = e.currentTarget.scrollLeft; // restored across post-edit reload
478+
recordTimelineScroll(e.currentTarget);
472479
}}
473480
onDragOver={handleAssetDragOver}
474481
onDragLeave={() => clearDropPreview()}
Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
// @vitest-environment happy-dom
2+
3+
import { describe, expect, it } from "vitest";
4+
import { summarizeTimelinePerformance } from "./useTimelinePerformanceTelemetry";
5+
6+
describe("summarizeTimelinePerformance", () => {
7+
it("reports raw mounted work and p95 scroll timings", () => {
8+
const scroll = document.createElement("div");
9+
Object.defineProperties(scroll, {
10+
clientWidth: { value: 1_200 },
11+
clientHeight: { value: 360 },
12+
});
13+
scroll.innerHTML = `
14+
<div>
15+
<div data-clip="true"></div>
16+
<div data-clip="true"><span></span></div>
17+
</div>
18+
`;
19+
20+
expect(
21+
summarizeTimelinePerformance(
22+
scroll,
23+
{ totalClipCount: 3_000, totalRowCount: 24, zoomMode: "fit" },
24+
[8, 10, 12, 80],
25+
[16, 17, 45],
26+
),
27+
).toEqual({
28+
total_clip_count: 3_000,
29+
mounted_clip_count: 2,
30+
total_row_count: 24,
31+
timeline_dom_node_count: 4,
32+
viewport_width: 1_200,
33+
viewport_height: 360,
34+
zoom_mode: "fit",
35+
scroll_sample_count: 4,
36+
scroll_frame_latency_p95_ms: 80,
37+
scroll_frame_latency_max_ms: 80,
38+
frame_interval_p95_ms: 45,
39+
});
40+
});
41+
42+
it("does not emit a summary without a completed animation frame", () => {
43+
const scroll = document.createElement("div");
44+
45+
expect(
46+
summarizeTimelinePerformance(
47+
scroll,
48+
{ totalClipCount: 1, totalRowCount: 1, zoomMode: "manual" },
49+
[],
50+
[],
51+
),
52+
).toBeNull();
53+
});
54+
});
Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
import { useRef } from "react";
2+
import { useMountEffect } from "../../hooks/useMountEffect";
3+
import {
4+
trackStudioTimelinePerformance,
5+
type StudioTimelinePerformanceSample,
6+
} from "../../telemetry/events";
7+
8+
const SCROLL_IDLE_MS = 400;
9+
const MIN_EVENT_INTERVAL_MS = 60_000;
10+
11+
interface TimelinePerformanceState {
12+
frameRequest: number;
13+
idleTimer: ReturnType<typeof setTimeout> | null;
14+
pendingScrollStartedAt: number;
15+
previousFrameAt: number | null;
16+
frameLatencies: number[];
17+
frameIntervals: number[];
18+
lastEmittedAt: number;
19+
}
20+
21+
interface TimelinePerformanceContext {
22+
totalClipCount: number;
23+
totalRowCount: number;
24+
zoomMode: string;
25+
}
26+
27+
function percentile(values: readonly number[], fraction: number): number | undefined {
28+
if (values.length === 0) return undefined;
29+
const sorted = [...values].sort((a, b) => a - b);
30+
const index = Math.min(sorted.length - 1, Math.ceil(sorted.length * fraction) - 1);
31+
return Number(sorted[Math.max(0, index)].toFixed(2));
32+
}
33+
34+
export function summarizeTimelinePerformance(
35+
scroll: HTMLElement,
36+
context: TimelinePerformanceContext,
37+
frameLatencies: readonly number[],
38+
frameIntervals: readonly number[],
39+
): StudioTimelinePerformanceSample | null {
40+
const latencyP95 = percentile(frameLatencies, 0.95);
41+
if (latencyP95 === undefined) return null;
42+
43+
const frameIntervalP95 = percentile(frameIntervals, 0.95);
44+
return {
45+
total_clip_count: context.totalClipCount,
46+
mounted_clip_count: scroll.querySelectorAll('[data-clip="true"]').length,
47+
total_row_count: context.totalRowCount,
48+
timeline_dom_node_count: scroll.querySelectorAll("*").length,
49+
viewport_width: scroll.clientWidth,
50+
viewport_height: scroll.clientHeight,
51+
zoom_mode: context.zoomMode,
52+
scroll_sample_count: frameLatencies.length,
53+
scroll_frame_latency_p95_ms: latencyP95,
54+
scroll_frame_latency_max_ms: Number(Math.max(...frameLatencies).toFixed(2)),
55+
...(frameIntervalP95 === undefined ? {} : { frame_interval_p95_ms: frameIntervalP95 }),
56+
};
57+
}
58+
59+
function resetMeasurements(state: TimelinePerformanceState): void {
60+
state.previousFrameAt = null;
61+
state.frameLatencies = [];
62+
state.frameIntervals = [];
63+
}
64+
65+
/**
66+
* Samples one event per timeline scroll burst, capped at one event per minute.
67+
* The event contains only aggregate counts and timings—never project content.
68+
*/
69+
export function useTimelinePerformanceTelemetry(context: TimelinePerformanceContext): {
70+
recordTimelineScroll: (scroll: HTMLDivElement) => void;
71+
} {
72+
const stateRef = useRef<TimelinePerformanceState>({
73+
frameRequest: 0,
74+
idleTimer: null,
75+
pendingScrollStartedAt: 0,
76+
previousFrameAt: null,
77+
frameLatencies: [],
78+
frameIntervals: [],
79+
lastEmittedAt: Number.NEGATIVE_INFINITY,
80+
});
81+
82+
const recordTimelineScroll = (scroll: HTMLDivElement) => {
83+
const state = stateRef.current;
84+
const now = performance.now();
85+
86+
if (state.frameRequest === 0) {
87+
state.pendingScrollStartedAt = now;
88+
state.frameRequest = requestAnimationFrame((frameAt) => {
89+
state.frameRequest = 0;
90+
state.frameLatencies.push(frameAt - state.pendingScrollStartedAt);
91+
if (state.previousFrameAt !== null) {
92+
state.frameIntervals.push(frameAt - state.previousFrameAt);
93+
}
94+
state.previousFrameAt = frameAt;
95+
});
96+
}
97+
98+
if (state.idleTimer !== null) clearTimeout(state.idleTimer);
99+
state.idleTimer = setTimeout(() => {
100+
state.idleTimer = null;
101+
if (state.frameRequest !== 0) {
102+
cancelAnimationFrame(state.frameRequest);
103+
state.frameRequest = 0;
104+
resetMeasurements(state);
105+
return;
106+
}
107+
108+
const emittedAt = performance.now();
109+
if (emittedAt - state.lastEmittedAt >= MIN_EVENT_INTERVAL_MS) {
110+
const sample = summarizeTimelinePerformance(
111+
scroll,
112+
context,
113+
state.frameLatencies,
114+
state.frameIntervals,
115+
);
116+
if (sample) {
117+
trackStudioTimelinePerformance(sample);
118+
state.lastEmittedAt = emittedAt;
119+
}
120+
}
121+
resetMeasurements(state);
122+
}, SCROLL_IDLE_MS);
123+
};
124+
125+
useMountEffect(() => () => {
126+
const state = stateRef.current;
127+
if (state.frameRequest !== 0) cancelAnimationFrame(state.frameRequest);
128+
if (state.idleTimer !== null) clearTimeout(state.idleTimer);
129+
});
130+
131+
return { recordTimelineScroll };
132+
}

‎packages/studio/src/telemetry/events.test.ts‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ const {
1515
trackStudioKeyframeLaneExpand,
1616
trackStudioSegmentEaseEdit,
1717
trackStudioFeedback,
18+
trackStudioTimelinePerformance,
1819
} = await import("./events");
1920

2021
describe("studio telemetry events", () => {
@@ -63,6 +64,26 @@ describe("studio telemetry events", () => {
6364
});
6465
});
6566

67+
it("trackStudioTimelinePerformance emits raw timeline measurements", () => {
68+
const sample = {
69+
total_clip_count: 3_000,
70+
mounted_clip_count: 160,
71+
total_row_count: 24,
72+
timeline_dom_node_count: 957,
73+
viewport_width: 1_200,
74+
viewport_height: 360,
75+
zoom_mode: "fit",
76+
scroll_sample_count: 20,
77+
scroll_frame_latency_p95_ms: 24.5,
78+
scroll_frame_latency_max_ms: 31.2,
79+
frame_interval_p95_ms: 42.3,
80+
};
81+
82+
trackStudioTimelinePerformance(sample);
83+
84+
expect(trackEvent).toHaveBeenCalledWith("studio_timeline_performance", sample);
85+
});
86+
6687
it("trackStudioRazorSplit emits 'studio_razor_split' with mode and count", () => {
6788
trackStudioRazorSplit({ mode: "all", count: 3 });
6889
expect(trackEvent).toHaveBeenCalledWith("studio_razor_split", { mode: "all", count: 3 });

‎packages/studio/src/telemetry/events.ts‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,24 @@ export function trackStudioRenderStart(props: {
2626
});
2727
}
2828

29+
export type StudioTimelinePerformanceSample = {
30+
total_clip_count: number;
31+
mounted_clip_count: number;
32+
total_row_count: number;
33+
timeline_dom_node_count: number;
34+
viewport_width: number;
35+
viewport_height: number;
36+
zoom_mode: string;
37+
scroll_sample_count: number;
38+
scroll_frame_latency_p95_ms: number;
39+
scroll_frame_latency_max_ms: number;
40+
frame_interval_p95_ms?: number;
41+
};
42+
43+
export function trackStudioTimelinePerformance(props: StudioTimelinePerformanceSample): void {
44+
trackEvent("studio_timeline_performance", props);
45+
}
46+
2947
function getBrowserDoctorSummary(): string {
3048
try {
3149
const nav = navigator as Navigator & {

0 commit comments

Comments
 (0)