RPP: add AnimationFramesHandler

This CL adds the first pass at AnimationFrames parsing.

It pairs AnimationFrame begin & end events based on the fact that they
are a stack. It also does this per PID+TID to prevent against merging
incorrectly from different threads.

Additionally, it uses the ID field that is on the begin event + the
AnimationFrame::Presentation event to pair those up. This allows us to
know the time that a given frame was shown to the user.

Bug: 352242870
Change-Id: Id8a120d5c7b13cd4751e23cbccc83ccee8d4c265
Reviewed-on: https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/6054290
Reviewed-by: Andres Olivares <[email protected]>
Commit-Queue: Jack Franklin <[email protected]>

Author: jackfranklin

config/gni/devtools_grd_files.gni

@@ -1051,6 +1051,7 @@ grd_files_debug_sources = [
   "front_end/models/trace/extras/TraceFilter.js",
   "front_end/models/trace/extras/TraceTree.js",
   "front_end/models/trace/extras/URLForEntry.js",
+  "front_end/models/trace/handlers/AnimationFramesHandler.js",
   "front_end/models/trace/handlers/AnimationHandler.js",
   "front_end/models/trace/handlers/AsyncCallStacksHandler.js",
   "front_end/models/trace/handlers/AuctionWorkletsHandler.js",

front_end/models/trace/handlers/AnimationFramesHandler.test.ts

@@ -0,0 +1,40 @@
+// Copyright 2024 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+import {TraceLoader} from '../../../testing/TraceLoader.js';
+import * as Trace from '../trace.js';
+
+async function parseEvents(events: readonly Trace.Types.Events.Event[]) {
+  Trace.Handlers.ModelHandlers.FlowsHandler.reset();
+  Trace.Handlers.ModelHandlers.AnimationFrames.reset();
+  for (const event of events) {
+    Trace.Handlers.ModelHandlers.FlowsHandler.handleEvent(event);
+    Trace.Handlers.ModelHandlers.AnimationFrames.handleEvent(event);
+  }
+  await Trace.Handlers.ModelHandlers.FlowsHandler.finalize();
+  await Trace.Handlers.ModelHandlers.AnimationFrames.finalize();
+}
+
+describe('AnimationFramesHandler', () => {
+  it('can group all related animation frame events', async function() {
+    Trace.Handlers.ModelHandlers.AnimationFrames.reset();
+    const events = await TraceLoader.rawEvents(this, 'web-dev-animation-frames.json.gz');
+    await parseEvents(events);
+    const data = Trace.Handlers.ModelHandlers.AnimationFrames.data();
+    assert.lengthOf(data.animationFrames, 32);
+    const firstFrame = data.animationFrames[0];
+    assert.strictEqual(firstFrame.args.data.beginEvent.args?.animation_frame_timing_info.duration_ms, 76);
+    assert.strictEqual(firstFrame.dur, Trace.Types.Timing.MicroSeconds(76038));
+  });
+
+  it('links an animation frame to its presentation event', async function() {
+    Trace.Handlers.ModelHandlers.AnimationFrames.reset();
+    const events = await TraceLoader.rawEvents(this, 'web-dev-animation-frames.json.gz');
+    await parseEvents(events);
+    const data = Trace.Handlers.ModelHandlers.AnimationFrames.data();
+    const firstFrame = data.animationFrames[0];
+    const presentationEvent = data.presentationForFrame.get(firstFrame);
+    assert.isDefined(presentationEvent);
+    assert.strictEqual(presentationEvent.args?.id, firstFrame.args.data.beginEvent.args?.id);
+  });
+});

front_end/models/trace/handlers/AnimationFramesHandler.ts

@@ -0,0 +1,119 @@
+// Copyright 2024 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+import * as Helpers from '../helpers/helpers.js';
+import * as Types from '../types/types.js';
+
+import type {HandlerName} from './types.js';
+
+export interface Data {
+  animationFrames: Types.Events.SyntheticAnimationFramePair[];
+  presentationForFrame: Map<Types.Events.SyntheticAnimationFramePair, Types.Events.AnimationFramePresentation>;
+}
+
+function threadKey(data: Types.Events.Event): string {
+  return `${data.pid}-${data.tid}`;
+}
+// Track all the start + end events. We key them by the PID+TID so we don't
+// accidentally pair across different threads.
+const animationFrameStarts: Map<string, Types.Events.AnimationFrameAsyncStart[]> = new Map();
+const animationFrameEnds: Map<string, Types.Events.AnimationFrameAsyncEnd[]> = new Map();
+// Store all the AnimationFrame::Presentation events. Key them by their ID for
+// easy look-up later on when we associate one to the AnimationFrame event.
+const animationFramePresentations: Map<string, Types.Events.AnimationFramePresentation> = new Map();
+
+// The final list of animation frames that we return.
+const animationFrames: Types.Events.SyntheticAnimationFramePair[] = [];
+
+const presentationForFrame: Map<Types.Events.SyntheticAnimationFramePair, Types.Events.AnimationFramePresentation> =
+    new Map();
+
+export function reset(): void {
+  animationFrameStarts.clear();
+  animationFrameEnds.clear();
+  animationFrames.length = 0;
+  presentationForFrame.clear();
+  animationFramePresentations.clear();
+}
+
+export function handleEvent(event: Types.Events.Event): void {
+  if (Types.Events.isAnimationFrameAsyncStart(event)) {
+    const key = threadKey(event);
+    const existing = animationFrameStarts.get(key) ?? [];
+    existing.push(event);
+    animationFrameStarts.set(key, existing);
+  } else if (Types.Events.isAnimationFrameAsyncEnd(event)) {
+    const key = threadKey(event);
+    const existing = animationFrameEnds.get(key) ?? [];
+    existing.push(event);
+    animationFrameEnds.set(key, existing);
+  } else if (Types.Events.isAnimationFramePresentation(event) && event.args?.id) {
+    animationFramePresentations.set(event.args.id, event);
+  }
+}
+
+export async function finalize(): Promise<void> {
+  // AnimationFrames are represented with begin & end events on a stack; so we
+  // can pair them by walking through the list of start events and pairing with
+  // the same index in the list of end events, once both lists are sorted by
+  // timestamp.
+  // We walk through the set of begin/end events we gathered per pid+tid and
+  // pair those up.
+  // Unfortunately we cannot use the pairing helpers in Helpers.Trace because
+  // only the begin event has an ID; the end event does not. But because we
+  // know that AnimationFrames are sequential and do not overlap, we can pair
+  // up events easily.
+  for (const [key, startEvents] of animationFrameStarts.entries()) {
+    const endEvents = animationFrameEnds.get(key);
+    if (!endEvents) {
+      continue;
+    }
+
+    Helpers.Trace.sortTraceEventsInPlace(startEvents);
+    Helpers.Trace.sortTraceEventsInPlace(endEvents);
+
+    for (let i = 0; i < startEvents.length; i++) {
+      const endEvent = endEvents.at(i);
+      if (!endEvent) {
+        // Invalid data: break. We can't pair any other events up.
+        break;
+      }
+      const startEvent = startEvents[i];
+
+      const syntheticEvent = Helpers.SyntheticEvents.SyntheticEventsManager
+                                 .registerSyntheticEvent<Types.Events.SyntheticAnimationFramePair>({
+                                   rawSourceEvent: startEvent,
+                                   ...startEvent,
+                                   dur: Types.Timing.MicroSeconds(endEvent.ts - startEvent.ts),
+                                   args: {
+                                     data: {
+                                       beginEvent: startEvent,
+                                       endEvent,
+                                     },
+                                   },
+                                 });
+      animationFrames.push(syntheticEvent);
+
+      // AnimationFrame begin events + AnimationFrame::Presentation events share
+      // an args.id, so we can pair them up based on that.
+      const id = startEvent.args?.id;
+      if (id) {
+        const presentationEvent = animationFramePresentations.get(id);
+        if (presentationEvent) {
+          presentationForFrame.set(syntheticEvent, presentationEvent);
+        }
+      }
+    }
+  }
+}
+
+export function data(): Data {
+  return {
+    animationFrames,
+    presentationForFrame,
+  };
+}
+
+export function deps(): HandlerName[] {
+  return ['Meta'];
+}

front_end/models/trace/handlers/BUILD.gn

@@ -9,6 +9,7 @@ import("../../visibility.gni")
 
 devtools_module("handlers") {
   sources = [
+    "AnimationFramesHandler.ts",
     "AnimationHandler.ts",
     "AsyncCallStacksHandler.ts",
     "AuctionWorkletsHandler.ts",
@@ -66,6 +67,7 @@ ts_library("unittests") {
   testonly = true
 
   sources = [
+    "AnimationFramesHandler.test.ts",
     "AnimationHandler.test.ts",
     "AsyncCallStacksHandler.test.ts",
     "AuctionWorkletsHandler.test.ts",

front_end/models/trace/handlers/ModelHandlers.ts

@@ -2,6 +2,7 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+export * as AnimationFrames from './AnimationFramesHandler.js';
 export * as Animations from './AnimationHandler.js';
 export * as AsyncCallStacks from './AsyncCallStacksHandler.js';
 export * as AuctionWorklets from './AuctionWorkletsHandler.js';

front_end/models/trace/types/TraceEvents.ts

@@ -1269,6 +1269,44 @@ export interface PairableAsyncEnd extends PairableAsync {
   ph: Phase.ASYNC_NESTABLE_END;
 }
 
+export interface AnimationFrame extends PairableAsync {
+  name: Name.ANIMATION_FRAME;
+  args?: AnimationFrameArgs;
+}
+export type AnimationFrameArgs = Args&{
+  animation_frame_timing_info: {
+    blocking_duration_ms: number,
+    duration_ms: number,
+    num_scripts: number,
+  },
+  id: string,
+};
+
+export interface AnimationFrameAsyncStart extends AnimationFrame {
+  ph: Phase.ASYNC_NESTABLE_START;
+}
+export interface AnimationFrameAsyncEnd extends AnimationFrame {
+  ph: Phase.ASYNC_NESTABLE_END;
+}
+
+export function isAnimationFrameAsyncStart(data: Event): data is AnimationFrameAsyncStart {
+  return data.name === Name.ANIMATION_FRAME && data.ph === Phase.ASYNC_NESTABLE_START;
+}
+export function isAnimationFrameAsyncEnd(data: Event): data is AnimationFrameAsyncEnd {
+  return data.name === Name.ANIMATION_FRAME && data.ph === Phase.ASYNC_NESTABLE_END;
+}
+
+export interface AnimationFramePresentation extends Event {
+  name: Name.ANIMATION_FRAME_PRESENTATION;
+  ph: Phase.ASYNC_NESTABLE_INSTANT;
+  args?: Args&{
+    id: string,
+  };
+}
+export function isAnimationFramePresentation(data: Event): data is AnimationFramePresentation {
+  return data.name === Name.ANIMATION_FRAME_PRESENTATION;
+}
+
 export interface UserTiming extends Event {
   id2?: {local?: string, global?: string};
   id?: string;
@@ -1475,6 +1513,7 @@ export interface SyntheticEventPair<T extends PairableAsync = PairableAsync> ext
 }
 
 export type SyntheticPipelineReporterPair = SyntheticEventPair<PipelineReporter>;
+export type SyntheticAnimationFramePair = SyntheticEventPair<AnimationFrame>;
 
 export type SyntheticUserTimingPair = SyntheticEventPair<PerformanceMeasure>;
 
@@ -2891,6 +2930,9 @@ export const enum Name {
 
   DOM_LOADING = 'domLoading',
   BEGIN_REMOTE_FONT_LOAD = 'BeginRemoteFontLoad',
+
+  ANIMATION_FRAME = 'AnimationFrame',
+  ANIMATION_FRAME_PRESENTATION = 'AnimationFrame::Presentation',
 }
 
 // NOT AN EXHAUSTIVE LIST: just some categories we use and refer

front_end/panels/timeline/fixtures/traces/BUILD.gn

@@ -100,6 +100,7 @@ copy_to_gen("traces") {
     "user-timings-complex.json.gz",
     "user-timings-details.json.gz",
     "user-timings.json.gz",
+    "web-dev-animation-frames.json.gz",
     "web-dev-initial-url.json.gz",
     "web-dev-modifications.json.gz",
     "web-dev-outermost-frames.json.gz",

front_end/panels/timeline/fixtures/traces/web-dev-animation-frames.json.gz

@@ -575,6 +575,10 @@ type ParsedTrace = Trace.Handlers.Types.ParsedTrace;
 export function getBaseTraceParseModelData(overrides: Partial<ParsedTrace> = {}): ParsedTrace {
   return {
     Animations: {animations: []},
+    AnimationFrames: {
+      animationFrames: [],
+      presentationForFrame: new Map(),
+    },
     LayoutShifts: {
       clusters: [],
       clustersByNavigationId: new Map(),