devtools-tracing 1.0.0

package/lib/front_end/models/trace/insights/Viewport.ts

@@ -0,0 +1,138 @@
+// 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 i18n from '../../../core/i18n/i18n.js';
+import * as Platform from '../../../core/platform/platform.js';
+import * as Handlers from '../handlers/handlers.js';
+import * as Helpers from '../helpers/helpers.js';
+import * as Types from '../types/types.js';
+
+import {
+  InsightCategory,
+  InsightKeys,
+  type InsightModel,
+  type InsightSetContext,
+  InsightWarning,
+  type PartialInsightModel,
+} from './types.js';
+
+export const UIStrings = {
+  /** Title of an insight that provides details about if the page's viewport is optimized for mobile viewing. */
+  title: 'Optimize viewport for mobile',
+  /**
+   * @description Text to tell the user how a viewport meta element can improve performance. \xa0 is a non-breaking space
+   */
+  description:
+      'Tap interactions may be [delayed by up to 300\xA0ms](https://developer.chrome.com/docs/performance/insights/viewport) if the viewport is not optimized for mobile.',
+  /**
+   * @description Text for a label describing the portion of an interaction event that was delayed due to a bad mobile viewport.
+   */
+  mobileTapDelayLabel: 'Mobile tap delay',
+} as const;
+
+const str_ = i18n.i18n.registerUIStrings('models/trace/insights/Viewport.ts', UIStrings);
+export const i18nString = i18n.i18n.getLocalizedString.bind(undefined, str_);
+
+export type ViewportInsightModel = InsightModel<typeof UIStrings, {
+  mobileOptimized: boolean | null,
+  viewportEvent?: Types.Events.ParseMetaViewport,
+  longPointerInteractions?: Types.Events.SyntheticInteractionPair[],
+}>;
+
+function finalize(partialModel: PartialInsightModel<ViewportInsightModel>): ViewportInsightModel {
+  return {
+    insightKey: InsightKeys.VIEWPORT,
+    strings: UIStrings,
+    title: i18nString(UIStrings.title),
+    description: i18nString(UIStrings.description),
+    docs: 'https://developer.chrome.com/docs/performance/insights/viewport',
+    category: InsightCategory.INP,
+    state: partialModel.mobileOptimized === false ? 'fail' : 'pass',
+    ...partialModel,
+  };
+}
+
+export function isViewportInsight(model: InsightModel): model is ViewportInsightModel {
+  return model.insightKey === InsightKeys.VIEWPORT;
+}
+
+export function generateInsight(data: Handlers.Types.HandlerData, context: InsightSetContext): ViewportInsightModel {
+  const viewportEvent = data.UserInteractions.parseMetaViewportEvents.find(event => {
+    if (event.args.data.frame !== context.frameId) {
+      return false;
+    }
+
+    return Helpers.Timing.eventIsInBounds(event, context.bounds);
+  });
+
+  const compositorEvents = data.UserInteractions.beginCommitCompositorFrameEvents.filter(event => {
+    if (event.args.frame !== context.frameId) {
+      return false;
+    }
+
+    // Commit compositor frame events can be emitted before the viewport tag is parsed.
+    // We shouldn't count these since the browser hasn't had time to make the viewport mobile optimized.
+    if (viewportEvent && event.ts < viewportEvent.ts) {
+      return false;
+    }
+
+    return Helpers.Timing.eventIsInBounds(event, context.bounds);
+  });
+
+  if (!compositorEvents.length) {
+    // Trace doesn't have the data we need.
+    return finalize({
+      mobileOptimized: null,
+      warnings: [InsightWarning.NO_LAYOUT],
+    });
+  }
+
+  // Returns true only if all events are mobile optimized.
+  for (const event of compositorEvents) {
+    if (!event.args.is_mobile_optimized) {
+      // Grab all the pointer events with at least 50ms of input delay.
+      const longPointerInteractions = [...data.UserInteractions.interactionsOverThreshold.values()].filter(
+          interaction => Handlers.ModelHandlers.UserInteractions.categoryOfInteraction(interaction) === 'POINTER' &&
+              interaction.inputDelay >= 50_000);
+
+      // The actual impact varies between 0 and 300.
+      // Using inputDelay as the closest thing we have for measuring this, though inputDelay may be high for other reasons.
+      // b/371566378#comment8
+      const inputDelay = Math.max(0, ...longPointerInteractions.map(interaction => interaction.inputDelay)) / 1000;
+      const inpMetricSavings = Platform.NumberUtilities.clamp(inputDelay, 0, 300);
+
+      return finalize({
+        mobileOptimized: false,
+        viewportEvent,
+        longPointerInteractions,
+        metricSavings: {INP: inpMetricSavings as Types.Timing.Milli},
+      });
+    }
+  }
+
+  return finalize({
+    mobileOptimized: true,
+    viewportEvent,
+  });
+}
+
+export function createOverlays(model: ViewportInsightModel): Types.Overlays.Overlay[] {
+  if (!model.longPointerInteractions) {
+    return [];
+  }
+
+  return model.longPointerInteractions.map(interaction => {
+    const delay = Math.min(interaction.inputDelay, 300 * 1000);
+    const bounds = Helpers.Timing.traceWindowFromMicroSeconds(
+        Types.Timing.Micro(interaction.ts),
+        Types.Timing.Micro(interaction.ts + delay),
+    );
+    return {
+      type: 'TIMESPAN_BREAKDOWN',
+      entry: interaction,
+      sections: [{bounds, label: i18nString(UIStrings.mobileTapDelayLabel), showDuration: true}],
+      renderLocation: 'ABOVE_EVENT',
+    };
+  });
+}

package/lib/front_end/models/trace/insights/insights.ts

@@ -0,0 +1,10 @@
+// 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.
+
+export * as Cache from './Cache.js';  // TODO(crbug.com/444191656): Exported for tests.
+export * as Common from './Common.js';
+export * as Models from './Models.js';
+export * as ModernHTTP from './ModernHTTP.js';  // TODO(crbug.com/444191656): Exported for tests.
+export * as Statistics from './Statistics.js';
+export * as Types from './types.js';

package/lib/front_end/models/trace/insights/types.ts

@@ -0,0 +1,157 @@
+// 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 type * as Common from '../../../core/common/common.js';
+import type * as Lantern from '../lantern/lantern.js';
+import type * as Types from '../types/types.js';
+
+import type * as Models from './Models.js';
+
+/**
+ * Context for the portion of the trace an insight should look at.
+ */
+export type InsightSetContext = InsightSetContextWithoutNavigation|InsightSetContextWithNavigation;
+
+export interface InsightSetContextWithoutNavigation {
+  options: Types.Configuration.ParseOptions;
+  bounds: Types.Timing.TraceWindowMicro;
+  frameId: string;
+  navigation?: never;
+}
+
+export interface InsightSetContextWithNavigation {
+  options: Types.Configuration.ParseOptions;
+  bounds: Types.Timing.TraceWindowMicro;
+  frameId: string;
+  navigation: Types.Events.NavigationStart;
+  navigationId: string;
+  lantern?: LanternContext;
+}
+
+export interface LanternContext {
+  requests: Array<Lantern.Types.NetworkRequest<Types.Events.SyntheticNetworkRequest>>;
+  graph: Lantern.Graph.Node<Types.Events.SyntheticNetworkRequest>;
+  simulator: Lantern.Simulation.Simulator<Types.Events.SyntheticNetworkRequest>;
+  metrics: Record<string, Lantern.Metrics.MetricResult>;
+}
+
+export type InsightModelsType = typeof Models;
+
+export enum InsightWarning {
+  NO_FP = 'NO_FP',
+  NO_LCP = 'NO_LCP',
+  // No network request could be identified as the primary HTML document.
+  NO_DOCUMENT_REQUEST = 'NO_DOCUMENT_REQUEST',
+  NO_LAYOUT = 'NO_LAYOUT',
+}
+
+export interface MetricSavings {
+  /* eslint-disable @typescript-eslint/naming-convention */
+  FCP?: Types.Timing.Milli;
+  LCP?: Types.Timing.Milli;
+  TBT?: Types.Timing.Milli;
+  CLS?: number;
+  INP?: Types.Timing.Milli;
+  /* eslint-enable @typescript-eslint/naming-convention */
+}
+
+export enum InsightCategory {
+  ALL = 'All',
+  INP = 'INP',
+  LCP = 'LCP',
+  CLS = 'CLS',
+}
+
+export type RelatedEventsMap = Map<Types.Events.Event, string[]>;
+
+export type Checklist<Keys extends string> = Record<Keys, {label: Common.UIString.LocalizedString, value: boolean}>;
+
+export type InsightModel<UIStrings extends Record<string, string> = Record<string, string>,
+                                           ExtraDetail extends Record<string, unknown> = Record<string, unknown>> =
+    ExtraDetail&{
+      /** Used internally to identify the type of a model, not shown visibly to users **/
+      insightKey: keyof InsightModelsType,
+      /** Not used within DevTools - this is for external consumers (like Lighthouse). */
+      strings: UIStrings,
+      title: Common.UIString.LocalizedString,
+      description: Common.UIString.LocalizedString,
+      docs: string,
+      category: InsightCategory,
+      state: 'pass' | 'fail' | 'informative',
+      /** Used by RelatedInsightChips.ts */
+      relatedEvents?: RelatedEventsMap | Types.Events.Event[],
+      warnings?: InsightWarning[],
+      metricSavings?: MetricSavings,
+      /**
+       * An estimate for the number of bytes that this insight deems to have been wasted.
+       * Bytes are in terms of transfer size: for each component of savings related to an
+       * individual request, the insight will estimate its impact on transfer size by using
+       * the compression ratio of the resource.
+       *
+       * This field is only displayed for informational purposes.
+       */
+      wastedBytes?: number,
+      frameId?: string,
+      /**
+       * If this insight is attached to a navigation, this stores its ID.
+       */
+      navigationId?: string,
+      /** This is lazily-generated because some insights may create many overlays. */
+      createOverlays?: () => Types.Overlays.Overlay[],
+    };
+
+export type PartialInsightModel<T> =
+    Omit<T, 'strings'|'title'|'description'|'docs'|'category'|'state'|'insightKey'|'navigationId'|'frameId'>;
+
+/**
+ * Contains insights for a specific navigation. If a trace began after a navigation already started,
+ * this could instead represent the duration from the beginning of the trace up to the first recorded
+ * navigation (or the end of the trace).
+ */
+export interface InsightSet {
+  /** If for a navigation, this is the navigationId. Else it is Trace.Types.Events.NO_NAVIGATION. */
+  id: Types.Events.NavigationId;
+  /** The URL to show in the accordion list. */
+  url: URL;
+  frameId: string;
+  bounds: Types.Timing.TraceWindowMicro;
+  model: InsightModels;
+  navigation?: Types.Events.NavigationStart;
+}
+
+/**
+ * Contains insights for a specific insight set.
+ */
+export type InsightModels = {
+  [I in keyof InsightModelsType]: ReturnType<InsightModelsType[I]['generateInsight']>;
+};
+
+/**
+ * Contains insights for the entire trace. Insights are mostly grouped by `navigationId`, with one exception:
+ *
+ * If the analyzed trace started after the navigation, and has meaningful work with that span, there is no
+ * navigation to map it to. In this case `Types.Events.NO_NAVIGATION` is used for the key.
+ */
+export type TraceInsightSets = Map<Types.Events.NavigationId, InsightSet>;
+
+export const enum InsightKeys {
+  LCP_BREAKDOWN = 'LCPBreakdown',
+  INP_BREAKDOWN = 'INPBreakdown',
+  CLS_CULPRITS = 'CLSCulprits',
+  THIRD_PARTIES = 'ThirdParties',
+  DOCUMENT_LATENCY = 'DocumentLatency',
+  DOM_SIZE = 'DOMSize',
+  DUPLICATE_JAVASCRIPT = 'DuplicatedJavaScript',
+  FONT_DISPLAY = 'FontDisplay',
+  FORCED_REFLOW = 'ForcedReflow',
+  IMAGE_DELIVERY = 'ImageDelivery',
+  LCP_DISCOVERY = 'LCPDiscovery',
+  LEGACY_JAVASCRIPT = 'LegacyJavaScript',
+  NETWORK_DEPENDENCY_TREE = 'NetworkDependencyTree',
+  RENDER_BLOCKING = 'RenderBlocking',
+  SLOW_CSS_SELECTOR = 'SlowCSSSelector',
+  VIEWPORT = 'Viewport',
+  MODERN_HTTP = 'ModernHTTP',
+  CACHE = 'Cache',
+}

package/lib/front_end/models/trace/lantern/core/LanternError.ts

@@ -0,0 +1,7 @@
+// 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.
+
+class LanternError extends Error {}
+
+export {LanternError};