devtools-tracing 1.0.0

package/lib/front_end/models/trace/handlers/PageFramesHandler.ts

@@ -0,0 +1,52 @@
+// Copyright 2024 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import * as Types from '../types/types.js';
+
+let frames = new Map<string, Types.Events.TraceFrame>();
+
+export function reset(): void {
+  frames = new Map();
+}
+
+export function handleEvent(event: Types.Events.Event): void {
+  if (Types.Events.isTracingStartedInBrowser(event)) {
+    for (const frame of event.args.data?.frames ?? []) {
+      // The ID of a frame is stored under the `frame` key.
+      frames.set(frame.frame, frame);
+    }
+    return;
+  }
+
+  // CommitLoad events can contain an updated URL or Name for a frame.
+  if (Types.Events.isCommitLoad(event)) {
+    const frameData = event.args.data;
+    if (!frameData) {
+      return;
+    }
+    // We don't want to mutate the original object, hence why
+    // we set a new object from the new and existing values.
+    const frame = frames.get(frameData.frame);
+    if (!frame) {
+      return;
+    }
+    frames.set(frameData.frame, {
+      ...frame,
+      url: frameData.url || frame.url,
+      name: frameData.name || frameData.name,
+    });
+  }
+}
+
+export async function finalize(): Promise<void> {
+}
+
+export interface PageFrameData {
+  frames: Map<string, Types.Events.TraceFrame>;
+}
+export function data(): PageFrameData {
+  return {
+    frames,
+  };
+}

package/lib/front_end/models/trace/handlers/PageLoadMetricsHandler.ts

@@ -0,0 +1,460 @@
+// Copyright 2022 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+/**
+ * This handler stores page load metrics, including web vitals,
+ * and exports them in the shape of a map with the following shape:
+ * Map(FrameId -> Map(navigationID -> metrics) )
+ *
+ * It also exports all markers in a trace in an array.
+ *
+ * Some metrics are taken directly from a page load events (AKA markers) like DCL.
+ * Others require processing multiple events to be determined, like CLS and TBT.
+ */
+
+import * as Platform from '../../../core/platform/platform.js';
+import * as Helpers from '../helpers/helpers.js';
+import * as Types from '../types/types.js';
+
+import {data as metaHandlerData} from './MetaHandler.js';
+import type {HandlerName} from './types.js';
+
+// Small helpers to make the below type easier to read.
+type FrameId = string;
+type NavigationId = string;
+/**
+ * This represents the metric scores for all navigations, for all frames in a trace.
+ * Given a frame id, the map points to another map from navigation id to metric scores.
+ * The metric scores include the event related to the metric as well as the data regarding
+ * the score itself.
+ */
+let metricScoresByFrameId = new Map<FrameId, Map<NavigationId, Map<MetricName, MetricScore>>>();
+
+/**
+ * Page load events with no associated duration that happened in the
+ * main frame.
+ */
+let allMarkerEvents: Types.Events.PageLoadEvent[] = [];
+
+export function reset(): void {
+  metricScoresByFrameId = new Map();
+  pageLoadEventsArray = [];
+  allMarkerEvents = [];
+  selectedLCPCandidateEvents = new Set();
+}
+
+let pageLoadEventsArray: Types.Events.PageLoadEvent[] = [];
+
+// Once we've found the LCP events in the trace we want to fetch their DOM Node
+// from the backend. We could do this by parsing through our Map of frame =>
+// navigation => metric, but it's easier to keep a set of LCP events. As we
+// parse the trace, any time we store an LCP candidate as the potential LCP
+// event, we store the event here. If we later find a new candidate in the
+// trace, we store that and delete the prior event. When we've parsed the
+// entire trace this set will contain all the LCP events that were used - e.g.
+// the candidates that were the actual LCP events.
+let selectedLCPCandidateEvents = new Set<Types.Events.LargestContentfulPaintCandidate>();
+
+export function handleEvent(event: Types.Events.Event): void {
+  if (!Types.Events.eventIsPageLoadEvent(event)) {
+    return;
+  }
+  pageLoadEventsArray.push(event);
+}
+
+function storePageLoadMetricAgainstNavigationId(
+    navigation: Types.Events.NavigationStart, event: Types.Events.PageLoadEvent): void {
+  const navigationId = navigation.args.data?.navigationId;
+  if (!navigationId) {
+    throw new Error('Navigation event unexpectedly had no navigation ID.');
+  }
+  const frameId = getFrameIdForPageLoadEvent(event);
+  const {rendererProcessesByFrame} = metaHandlerData();
+
+  // If either of these pieces of data do not exist, the most likely
+  // explanation is that the page load metric we found is for a frame/process
+  // combo that the MetaHandler discarded. This typically happens if we get a
+  // navigation event with an empty URL. Therefore, we will silently return and
+  // drop this metric. If we didn't care about the navigation, we certainly do
+  // not need to care about metrics for that navigation.
+  const rendererProcessesInFrame = rendererProcessesByFrame.get(frameId);
+  if (!rendererProcessesInFrame) {
+    return;
+  }
+  const processData = rendererProcessesInFrame.get(event.pid);
+  if (!processData) {
+    return;
+  }
+
+  if (Types.Events.isNavigationStart(event)) {
+    return;
+  }
+
+  if (Types.Events.isFirstContentfulPaint(event)) {
+    const fcpTime = Types.Timing.Micro(event.ts - navigation.ts);
+    const classification = scoreClassificationForFirstContentfulPaint(fcpTime);
+    const metricScore = {event, metricName: MetricName.FCP, classification, navigation, timing: fcpTime};
+    storeMetricScore(frameId, navigationId, metricScore);
+    return;
+  }
+
+  if (Types.Events.isFirstPaint(event)) {
+    const paintTime = Types.Timing.Micro(event.ts - navigation.ts);
+    const classification = ScoreClassification.UNCLASSIFIED;
+    const metricScore = {event, metricName: MetricName.FP, classification, navigation, timing: paintTime};
+    storeMetricScore(frameId, navigationId, metricScore);
+    return;
+  }
+
+  if (Types.Events.isMarkDOMContent(event)) {
+    const dclTime = Types.Timing.Micro(event.ts - navigation.ts);
+    const metricScore = {
+      event,
+      metricName: MetricName.DCL,
+      classification: scoreClassificationForDOMContentLoaded(dclTime),
+      navigation,
+      timing: dclTime,
+    };
+    storeMetricScore(frameId, navigationId, metricScore);
+    return;
+  }
+
+  if (Types.Events.isInteractiveTime(event)) {
+    const ttiValue = Types.Timing.Micro(event.ts - navigation.ts);
+    const tti = {
+      event,
+      metricName: MetricName.TTI,
+      classification: scoreClassificationForTimeToInteractive(ttiValue),
+      navigation,
+      timing: ttiValue,
+    };
+    storeMetricScore(frameId, navigationId, tti);
+
+    const tbtValue = Helpers.Timing.milliToMicro(Types.Timing.Milli(event.args.args.total_blocking_time_ms));
+    const tbt = {
+      event,
+      metricName: MetricName.TBT,
+      classification: scoreClassificationForTotalBlockingTime(tbtValue),
+      navigation,
+      timing: tbtValue,
+    };
+    storeMetricScore(frameId, navigationId, tbt);
+    return;
+  }
+
+  if (Types.Events.isMarkLoad(event)) {
+    const loadTime = Types.Timing.Micro(event.ts - navigation.ts);
+    const metricScore = {
+      event,
+      metricName: MetricName.L,
+      classification: ScoreClassification.UNCLASSIFIED,
+      navigation,
+      timing: loadTime,
+    };
+    storeMetricScore(frameId, navigationId, metricScore);
+    return;
+  }
+
+  if (Types.Events.isLargestContentfulPaintCandidate(event)) {
+    const candidateIndex = event.args.data?.candidateIndex;
+    if (!candidateIndex) {
+      throw new Error('Largest Contentful Paint unexpectedly had no candidateIndex.');
+    }
+    const lcpTime = Types.Timing.Micro(event.ts - navigation.ts);
+    const lcp = {
+      event,
+      metricName: MetricName.LCP,
+      classification: scoreClassificationForLargestContentfulPaint(lcpTime),
+      navigation,
+      timing: lcpTime,
+    };
+    const metricsByNavigation = Platform.MapUtilities.getWithDefault(metricScoresByFrameId, frameId, () => new Map());
+    const metrics = Platform.MapUtilities.getWithDefault(metricsByNavigation, navigationId, () => new Map());
+    const lastLCPCandidate = metrics.get(MetricName.LCP);
+    if (lastLCPCandidate === undefined) {
+      selectedLCPCandidateEvents.add(lcp.event);
+      storeMetricScore(frameId, navigationId, lcp);
+      return;
+    }
+    const lastLCPCandidateEvent = lastLCPCandidate.event;
+
+    if (!Types.Events.isLargestContentfulPaintCandidate(lastLCPCandidateEvent)) {
+      return;
+    }
+    const lastCandidateIndex = lastLCPCandidateEvent.args.data?.candidateIndex;
+    if (!lastCandidateIndex) {
+      // lastCandidateIndex cannot be undefined because we don't store candidates with
+      // with an undefined candidateIndex value. This check is only to make TypeScript
+      // treat the field as not undefined below.
+      return;
+    }
+    if (lastCandidateIndex < candidateIndex) {
+      selectedLCPCandidateEvents.delete(lastLCPCandidateEvent);
+      selectedLCPCandidateEvents.add(lcp.event);
+      storeMetricScore(frameId, navigationId, lcp);
+    }
+    return;
+  }
+  if (Types.Events.isLayoutShift(event)) {
+    return;
+  }
+  return Platform.assertNever(event, `Unexpected event type: ${event}`);
+}
+
+function storeMetricScore(frameId: string, navigationId: string, metricScore: MetricScore): void {
+  const metricsByNavigation = Platform.MapUtilities.getWithDefault(metricScoresByFrameId, frameId, () => new Map());
+  const metrics = Platform.MapUtilities.getWithDefault(metricsByNavigation, navigationId, () => new Map());
+  // If an entry with that metric name is present, delete it so that the new entry that
+  // will replace it is added at the end of the map. This way we guarantee the map entries
+  // are ordered in ASC manner by timestamp.
+  metrics.delete(metricScore.metricName);
+  metrics.set(metricScore.metricName, metricScore);
+}
+
+export function getFrameIdForPageLoadEvent(event: Types.Events.PageLoadEvent): string {
+  if (Types.Events.isFirstContentfulPaint(event) || Types.Events.isInteractiveTime(event) ||
+      Types.Events.isLargestContentfulPaintCandidate(event) || Types.Events.isNavigationStart(event) ||
+      Types.Events.isLayoutShift(event) || Types.Events.isFirstPaint(event)) {
+    return event.args.frame;
+  }
+  if (Types.Events.isMarkDOMContent(event) || Types.Events.isMarkLoad(event)) {
+    const frameId = event.args.data?.frame;
+    if (!frameId) {
+      throw new Error('MarkDOMContent unexpectedly had no frame ID.');
+    }
+    return frameId;
+  }
+  Platform.assertNever(event, `Unexpected event type: ${event}`);
+}
+
+function getNavigationForPageLoadEvent(event: Types.Events.PageLoadEvent): Types.Events.NavigationStart|null {
+  if (Types.Events.isFirstContentfulPaint(event) || Types.Events.isLargestContentfulPaintCandidate(event) ||
+      Types.Events.isFirstPaint(event)) {
+    const navigationId = event.args.data?.navigationId;
+    if (!navigationId) {
+      throw new Error('Trace event unexpectedly had no navigation ID.');
+    }
+    const {navigationsByNavigationId} = metaHandlerData();
+    const navigation = navigationsByNavigationId.get(navigationId);
+
+    if (!navigation) {
+      // This event's navigation has been filtered out by the meta handler as a noise event.
+      return null;
+    }
+    return navigation;
+  }
+
+  if (Types.Events.isMarkDOMContent(event) || Types.Events.isInteractiveTime(event) ||
+      Types.Events.isLayoutShift(event) || Types.Events.isMarkLoad(event)) {
+    const frameId = getFrameIdForPageLoadEvent(event);
+    const {navigationsByFrameId} = metaHandlerData();
+    return Helpers.Trace.getNavigationForTraceEvent(event, frameId, navigationsByFrameId);
+  }
+
+  if (Types.Events.isNavigationStart(event)) {
+    // We don't want to compute metrics of the navigation relative to itself, so we'll avoid avoid all that.
+    return null;
+  }
+
+  return Platform.assertNever(event, `Unexpected event type: ${event}`);
+}
+
+/**
+ * Classifications sourced from
+ * https://web.dev/fcp/
+ */
+export function scoreClassificationForFirstContentfulPaint(fcpScoreInMicroseconds: Types.Timing.Micro):
+    ScoreClassification {
+  const FCP_GOOD_TIMING = Helpers.Timing.secondsToMicro(Types.Timing.Seconds(1.8));
+  const FCP_MEDIUM_TIMING = Helpers.Timing.secondsToMicro(Types.Timing.Seconds(3.0));
+  let scoreClassification = ScoreClassification.BAD;
+  if (fcpScoreInMicroseconds <= FCP_MEDIUM_TIMING) {
+    scoreClassification = ScoreClassification.OK;
+  }
+  if (fcpScoreInMicroseconds <= FCP_GOOD_TIMING) {
+    scoreClassification = ScoreClassification.GOOD;
+  }
+  return scoreClassification;
+}
+
+/**
+ * Classifications sourced from
+ * https://web.dev/interactive/#how-lighthouse-determines-your-tti-score
+ */
+
+export function scoreClassificationForTimeToInteractive(ttiTimeInMicroseconds: Types.Timing.Micro):
+    ScoreClassification {
+  const TTI_GOOD_TIMING = Helpers.Timing.secondsToMicro(Types.Timing.Seconds(3.8));
+  const TTI_MEDIUM_TIMING = Helpers.Timing.secondsToMicro(Types.Timing.Seconds(7.3));
+  let scoreClassification = ScoreClassification.BAD;
+  if (ttiTimeInMicroseconds <= TTI_MEDIUM_TIMING) {
+    scoreClassification = ScoreClassification.OK;
+  }
+  if (ttiTimeInMicroseconds <= TTI_GOOD_TIMING) {
+    scoreClassification = ScoreClassification.GOOD;
+  }
+  return scoreClassification;
+}
+
+/**
+ * Classifications sourced from
+ * https://web.dev/lcp/#what-is-lcp
+ */
+
+export function scoreClassificationForLargestContentfulPaint(lcpTimeInMicroseconds: Types.Timing.Micro):
+    ScoreClassification {
+  const LCP_GOOD_TIMING = Helpers.Timing.secondsToMicro(Types.Timing.Seconds(2.5));
+  const LCP_MEDIUM_TIMING = Helpers.Timing.secondsToMicro(Types.Timing.Seconds(4));
+  let scoreClassification = ScoreClassification.BAD;
+  if (lcpTimeInMicroseconds <= LCP_MEDIUM_TIMING) {
+    scoreClassification = ScoreClassification.OK;
+  }
+  if (lcpTimeInMicroseconds <= LCP_GOOD_TIMING) {
+    scoreClassification = ScoreClassification.GOOD;
+  }
+  return scoreClassification;
+}
+
+/**
+ * DCL does not have a classification.
+ */
+export function scoreClassificationForDOMContentLoaded(_dclTimeInMicroseconds: Types.Timing.Micro):
+    ScoreClassification {
+  return ScoreClassification.UNCLASSIFIED;
+}
+
+/**
+ * Classifications sourced from
+ * https://web.dev/lighthouse-total-blocking-#time/
+ */
+
+export function scoreClassificationForTotalBlockingTime(tbtTimeInMicroseconds: Types.Timing.Micro):
+    ScoreClassification {
+  const TBT_GOOD_TIMING = Helpers.Timing.milliToMicro(Types.Timing.Milli(200));
+  const TBT_MEDIUM_TIMING = Helpers.Timing.milliToMicro(Types.Timing.Milli(600));
+  let scoreClassification = ScoreClassification.BAD;
+  if (tbtTimeInMicroseconds <= TBT_MEDIUM_TIMING) {
+    scoreClassification = ScoreClassification.OK;
+  }
+  if (tbtTimeInMicroseconds <= TBT_GOOD_TIMING) {
+    scoreClassification = ScoreClassification.GOOD;
+  }
+  return scoreClassification;
+}
+
+/**
+ * Gets all the Largest Contentful Paint scores of all the frames in the
+ * trace.
+ */
+function gatherFinalLCPEvents(): Types.Events.PageLoadEvent[] {
+  const allFinalLCPEvents: Types.Events.PageLoadEvent[] = [];
+  const dataForAllFrames = [...metricScoresByFrameId.values()];
+  const dataForAllNavigations = dataForAllFrames.flatMap(frameData => [...frameData.values()]);
+  for (let i = 0; i < dataForAllNavigations.length; i++) {
+    const navigationData = dataForAllNavigations[i];
+    const lcpInNavigation = navigationData.get(MetricName.LCP);
+    if (!lcpInNavigation?.event) {
+      continue;
+    }
+
+    allFinalLCPEvents.push(lcpInNavigation.event);
+  }
+  return allFinalLCPEvents;
+}
+
+export async function finalize(): Promise<void> {
+  pageLoadEventsArray.sort((a, b) => a.ts - b.ts);
+
+  for (const pageLoadEvent of pageLoadEventsArray) {
+    const navigation = getNavigationForPageLoadEvent(pageLoadEvent);
+    if (navigation) {
+      // Event's navigation was not filtered out as noise.
+      storePageLoadMetricAgainstNavigationId(navigation, pageLoadEvent);
+    }
+  }
+  // NOTE: if you are looking for the TBT calculation, it has temporarily been
+  // removed. See crbug.com/1424335 for details.
+  const allFinalLCPEvents = gatherFinalLCPEvents();
+  const mainFrame = metaHandlerData().mainFrameId;
+  // Filter out LCP candidates to use only definitive LCP values
+  const allEventsButLCP = pageLoadEventsArray.filter(event => !Types.Events.isLargestContentfulPaintCandidate(event));
+  const markerEvents = [...allFinalLCPEvents, ...allEventsButLCP].filter(Types.Events.isMarkerEvent);
+  // Filter by main frame and sort.
+  allMarkerEvents =
+      markerEvents.filter(event => getFrameIdForPageLoadEvent(event) === mainFrame).sort((a, b) => a.ts - b.ts);
+}
+
+export interface PageLoadMetricsData {
+  /**
+   * This represents the metric scores for all navigations, for all frames in a trace.
+   * Given a frame id, the map points to another map from navigation id to metric scores.
+   * The metric scores include the event related to the metric as well as the data regarding
+   * the score itself.
+   */
+  metricScoresByFrameId: Map<string, Map<string, Map<MetricName, MetricScore>>>;
+  /**
+   * Page load events with no associated duration that happened in the
+   * main frame.
+   */
+  allMarkerEvents: Types.Events.PageLoadEvent[];
+}
+
+export function data(): PageLoadMetricsData {
+  return {
+    metricScoresByFrameId,
+    allMarkerEvents,
+  };
+}
+
+export function deps(): HandlerName[] {
+  return ['Meta'];
+}
+
+export const enum ScoreClassification {
+  GOOD = 'good',
+  OK = 'ok',
+  BAD = 'bad',
+  // Some metrics (such as DOMContentLoaded) don't have a Good/OK/Bad classification, hence this additional entry.
+  UNCLASSIFIED = 'unclassified',
+}
+
+export const enum MetricName {
+  // First Contentful Paint
+  FCP = 'FCP',
+  // First Paint
+  FP = 'FP',
+  // MarkLoad
+  L = 'L',
+  LCP = 'LCP',
+  // Mark DOM Content
+  DCL = 'DCL',
+  // Time To Interactive
+  TTI = 'TTI',
+  // Total Blocking Time
+  TBT = 'TBT',
+  // Cumulative Layout Shift
+  CLS = 'CLS',
+  // Navigation
+  NAV = 'Nav',
+  // Note: INP is handled in UserInteractionsHandler
+}
+
+export interface MetricScore {
+  metricName: MetricName;
+  classification: ScoreClassification;
+  event?: Types.Events.PageLoadEvent;
+  // The last navigation that occurred before this metric score.
+  navigation?: Types.Events.NavigationStart;
+  estimated?: boolean;
+  timing: Types.Timing.Micro;
+}
+
+export type LCPMetricScore = MetricScore&{
+  event: Types.Events.LargestContentfulPaintCandidate,
+  metricName: MetricName.LCP,
+};
+
+export function metricIsLCP(metric: MetricScore): metric is LCPMetricScore {
+  return metric.metricName === MetricName.LCP;
+}