devtools-tracing 1.0.0

package/lib/front_end/models/trace/lantern/simulation/TCPConnection.ts

@@ -0,0 +1,192 @@
+// 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 {ConnectionTiming} from './SimulationTimingMap.js';
+
+interface DownloadOptions {
+  dnsResolutionTime?: number;
+  timeAlreadyElapsed?: number;
+  maximumTimeToElapse?: number;
+}
+
+interface DownloadResults {
+  roundTrips: number;
+  timeElapsed: number;
+  bytesDownloaded: number;
+  extraBytesDownloaded: number;
+  congestionWindow: number;
+  connectionTiming: ConnectionTiming;
+}
+
+const INITIAL_CONGESTION_WINDOW = 10;
+const TCP_SEGMENT_SIZE = 1460;
+
+class TCPConnection {
+  warmed: boolean;
+  ssl: boolean;
+  h2: boolean;
+  rtt: number;
+  throughput: number;
+  serverLatency: number;
+  _congestionWindow: number;
+  h2OverflowBytesDownloaded: number;
+
+  constructor(rtt: number, throughput: number, serverLatency = 0, ssl = true, h2 = false) {
+    this.warmed = false;
+    this.ssl = ssl;
+    this.h2 = h2;
+    this.rtt = rtt;
+    this.throughput = throughput;
+    this.serverLatency = serverLatency;
+    this._congestionWindow = INITIAL_CONGESTION_WINDOW;
+    this.h2OverflowBytesDownloaded = 0;
+  }
+
+  static maximumSaturatedConnections(rtt: number, availableThroughput: number): number {
+    const roundTripsPerSecond = 1000 / rtt;
+    const bytesPerRoundTrip = TCP_SEGMENT_SIZE;
+    const bytesPerSecond = roundTripsPerSecond * bytesPerRoundTrip;
+    const minimumThroughputRequiredPerRequest = bytesPerSecond * 8;
+    return Math.floor(availableThroughput / minimumThroughputRequiredPerRequest);
+  }
+
+  computeMaximumCongestionWindowInSegments(): number {
+    const bytesPerSecond = this.throughput / 8;
+    const secondsPerRoundTrip = this.rtt / 1000;
+    const bytesPerRoundTrip = bytesPerSecond * secondsPerRoundTrip;
+    return Math.floor(bytesPerRoundTrip / TCP_SEGMENT_SIZE);
+  }
+
+  setThroughput(throughput: number): void {
+    this.throughput = throughput;
+  }
+
+  setCongestionWindow(congestion: number): void {
+    this._congestionWindow = congestion;
+  }
+
+  setWarmed(warmed: boolean): void {
+    this.warmed = warmed;
+  }
+
+  isH2(): boolean {
+    return this.h2;
+  }
+
+  get congestionWindow(): number {
+    return this._congestionWindow;
+  }
+
+  /**
+   * Sets the number of excess bytes that are available to this connection on future downloads, only
+   * applies to H2 connections.
+   */
+  setH2OverflowBytesDownloaded(bytes: number): void {
+    if (!this.h2) {
+      return;
+    }
+    this.h2OverflowBytesDownloaded = bytes;
+  }
+
+  clone(): TCPConnection {
+    return Object.assign(new TCPConnection(this.rtt, this.throughput), this);
+  }
+
+  /**
+   * Simulates a network download of a particular number of bytes over an optional maximum amount of time
+   * and returns information about the ending state.
+   *
+   * See https://hpbn.co/building-blocks-of-tcp/#three-way-handshake and
+   *  https://hpbn.co/transport-layer-security-tls/#tls-handshake for details.
+   */
+  simulateDownloadUntil(bytesToDownload: number, options?: DownloadOptions): DownloadResults {
+    const {timeAlreadyElapsed = 0, maximumTimeToElapse = Infinity, dnsResolutionTime = 0} = options || {};
+
+    if (this.warmed && this.h2) {
+      bytesToDownload -= this.h2OverflowBytesDownloaded;
+    }
+    const twoWayLatency = this.rtt;
+    const oneWayLatency = twoWayLatency / 2;
+    const maximumCongestionWindow = this.computeMaximumCongestionWindowInSegments();
+
+    let handshakeAndRequest = oneWayLatency;
+    if (!this.warmed) {
+      handshakeAndRequest =
+          // DNS lookup
+          dnsResolutionTime +
+          // SYN
+          oneWayLatency +
+          // SYN ACK
+          oneWayLatency +
+          // ACK + initial request
+          oneWayLatency +
+          // ClientHello/ServerHello assuming TLS False Start is enabled (https://istlsfastyet.com/#server-performance).
+          (this.ssl ? twoWayLatency : 0);
+    }
+
+    let roundTrips = Math.ceil(handshakeAndRequest / twoWayLatency);
+    let timeToFirstByte = handshakeAndRequest + this.serverLatency + oneWayLatency;
+    if (this.warmed && this.h2) {
+      timeToFirstByte = 0;
+    }
+
+    const timeElapsedForTTFB = Math.max(timeToFirstByte - timeAlreadyElapsed, 0);
+    const maximumDownloadTimeToElapse = maximumTimeToElapse - timeElapsedForTTFB;
+
+    let congestionWindow = Math.min(this._congestionWindow, maximumCongestionWindow);
+    let totalBytesDownloaded = 0;
+    if (timeElapsedForTTFB > 0) {
+      totalBytesDownloaded = congestionWindow * TCP_SEGMENT_SIZE;
+    } else {
+      roundTrips = 0;
+    }
+
+    let downloadTimeElapsed = 0;
+    let bytesRemaining = bytesToDownload - totalBytesDownloaded;
+    while (bytesRemaining > 0 && downloadTimeElapsed <= maximumDownloadTimeToElapse) {
+      roundTrips++;
+      downloadTimeElapsed += twoWayLatency;
+      congestionWindow = Math.max(Math.min(maximumCongestionWindow, congestionWindow * 2), 1);
+
+      const bytesDownloadedInWindow = congestionWindow * TCP_SEGMENT_SIZE;
+      totalBytesDownloaded += bytesDownloadedInWindow;
+      bytesRemaining -= bytesDownloadedInWindow;
+    }
+
+    const timeElapsed = timeElapsedForTTFB + downloadTimeElapsed;
+    const extraBytesDownloaded = this.h2 ? Math.max(totalBytesDownloaded - bytesToDownload, 0) : 0;
+    const bytesDownloaded = Math.max(Math.min(totalBytesDownloaded, bytesToDownload), 0);
+
+    let connectionTiming: ConnectionTiming;
+    if (!this.warmed) {
+      connectionTiming = {
+        dnsResolutionTime,
+        connectionTime: handshakeAndRequest - dnsResolutionTime,
+        sslTime: this.ssl ? twoWayLatency : undefined,
+        timeToFirstByte,
+      };
+    } else if (this.h2) {
+      // TODO: timing information currently difficult to model for warm h2 connections.
+      connectionTiming = {
+        timeToFirstByte,
+      };
+    } else {
+      connectionTiming = {
+        connectionTime: handshakeAndRequest,
+        timeToFirstByte,
+      };
+    }
+
+    return {
+      roundTrips,
+      timeElapsed,
+      bytesDownloaded,
+      extraBytesDownloaded,
+      congestionWindow,
+      connectionTiming,
+    };
+  }
+}
+
+export {TCPConnection};

package/lib/front_end/models/trace/lantern/simulation/simulation.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 * from './ConnectionPool.js';
+export * from './Constants.js';
+export * from './DNSCache.js';
+export * from './SimulationTimingMap.js';
+export * from './Simulator.js';
+export * from './TCPConnection.js';

package/lib/front_end/models/trace/lantern/types/Lantern.ts

@@ -0,0 +1,220 @@
+// 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 Protocol from '../../../../generated/protocol.js';
+
+export const NetworkRequestTypes = {
+  XHR: 'XHR',
+  Fetch: 'Fetch',
+  EventSource: 'EventSource',
+  Script: 'Script',
+  Stylesheet: 'Stylesheet',
+  Image: 'Image',
+  Media: 'Media',
+  Font: 'Font',
+  Document: 'Document',
+  TextTrack: 'TextTrack',
+  WebSocket: 'WebSocket',
+  Other: 'Other',
+  Manifest: 'Manifest',
+  SignedExchange: 'SignedExchange',
+  Ping: 'Ping',
+  Preflight: 'Preflight',
+  CSPViolationReport: 'CSPViolationReport',
+  Prefetch: 'Prefetch',
+  FedCM: 'FedCM',
+} as const;
+
+export interface TraceEvent {
+  name: string;
+  args: {
+    name?: string,
+    data?: {
+      frame?: string,
+      readyState?: number,
+      stackTrace?: Array<{
+                  url: string,
+                }>,
+      url?: string,
+    },
+  };
+  pid: number;
+  tid: number;
+  /** Timestamp of the event in microseconds. */
+  ts: number;
+  dur: number;
+}
+export interface Trace {
+  traceEvents: TraceEvent[];
+}
+export type ResourcePriority = ('VeryLow'|'Low'|'Medium'|'High'|'VeryHigh');
+export type ResourceType = keyof typeof NetworkRequestTypes;
+type InitiatorType = ('parser'|'script'|'preload'|'SignedExchange'|'preflight'|'FedCM'|'other');
+export type ResourceTiming = Protocol.Network.ResourceTiming;
+export interface CallStack {
+  callFrames: Array<{
+    scriptId: string,
+    url: string,
+    lineNumber: number,
+    columnNumber: number,
+    functionName: string,
+  }>;
+  parent?: CallStack;
+}
+
+export interface ParsedURL {
+  /**
+   * Equivalent to a `new URL(url).protocol` BUT w/o the trailing colon (:)
+   */
+  scheme: string;
+  /**
+   * Equivalent to a `new URL(url).hostname`
+   */
+  host: string;
+  securityOrigin: string;
+}
+
+// When Lantern NetworkRequests are constructed, the source-of-truth of the network record is given as `rawRequest`.
+// Internally Lantern doesn't care about the type of this field, so a default type is given to simplify internal code
+// by avoiding unnecessary typescript overhead.
+// If callers want to access the underlying network record, they are expected to make use of this generic on top-level
+// interfaces like Simulator.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyNetworkObject = any;
+
+export interface NetworkRequest<T = AnyNetworkObject> {
+  requestId: string;
+  connectionId: number;
+  connectionReused: boolean;
+  url: string;
+  protocol: string;
+  parsedURL: ParsedURL;
+  documentURL: string;
+  /** When the renderer process initially discovers a network request, in milliseconds. */
+  rendererStartTime: number;
+  /**
+   * When the network service is about to handle a request, ie. just before going to the
+   * HTTP cache or going to the network for DNS/connection setup, in milliseconds.
+   */
+  networkRequestTime: number;
+  /**
+   * When the last byte of the response headers is received, in milliseconds.
+   * Equal to networkRequestTime if no data is received over the
+   * network (ex: cached requests or data urls).
+   */
+  responseHeadersEndTime: number;
+  /** When the last byte of the response body is received, in milliseconds. */
+  networkEndTime: number;
+  transferSize: number;
+  resourceSize: number;
+  fromDiskCache: boolean;
+  fromMemoryCache: boolean;
+  isLinkPreload: boolean;
+  finished: boolean;
+  failed: boolean;
+  statusCode: number;
+  /** The network request that redirected to this one */
+  redirectSource: NetworkRequest<T>|undefined;
+  /** The network request that this one redirected to */
+  redirectDestination: NetworkRequest<T>|undefined;
+  // TODO: can't use Protocol.Network.Initiator because of type mismatch in Lighthouse initiator.
+  initiator: {
+    type: InitiatorType,
+    url?: string,
+    stack?: CallStack,
+  };
+  initiatorRequest: NetworkRequest<T>|undefined;
+  /** The chain of network requests that redirected to this one */
+  redirects: NetworkRequest[]|undefined;
+  timing: Protocol.Network.ResourceTiming|undefined;
+  resourceType: ResourceType|undefined;
+  mimeType: string;
+  priority: ResourcePriority;
+  frameId: string|undefined;
+  fromWorker: boolean;
+  /**
+   * Optional value for how long the server took to respond to this request, in ms.
+   * When not provided, the server response time is derived from the timing object.
+   */
+  serverResponseTime?: number;
+  /**
+   * Implementation-specific canonical data structure that this Lantern NetworkRequest
+   * was derived from.
+   * Users of Lantern create a NetworkRequest matching this interface,
+   * but can store the source-of-truth for their network model in this property.
+   * This is then accessible as a read-only property on NetworkNode.
+   */
+  rawRequest?: T;
+}
+
+export namespace Simulation {
+  export interface URL {
+    /** URL of the initially requested URL */
+    requestedUrl?: string;
+    /** URL of the last document request */
+    mainDocumentUrl?: string;
+  }
+
+  /** Simulation settings that control the amount of network & cpu throttling in the run. */
+  export interface ThrottlingSettings {
+    /** The round trip time in milliseconds. */
+    rttMs?: number;
+    /** The network throughput in kilobits per second. */
+    throughputKbps?: number;
+    // devtools settings
+    /** The network request latency in milliseconds. */
+    requestLatencyMs?: number;
+    /** The network download throughput in kilobits per second. */
+    downloadThroughputKbps?: number;
+    /** The network upload throughput in kilobits per second. */
+    uploadThroughputKbps?: number;
+    // used by both
+    /** The amount of slowdown applied to the cpu (1/<cpuSlowdownMultiplier>). */
+    cpuSlowdownMultiplier?: number;
+  }
+
+  export interface PrecomputedLanternData {
+    additionalRttByOrigin: Record<string, number>;
+    serverResponseTimeByOrigin: Record<string, number>;
+  }
+
+  export interface Settings {
+    networkAnalysis: {
+      rtt: number,
+      additionalRttByOrigin: Map<string, number>,
+      serverResponseTimeByOrigin: Map<string, number>,
+      throughput: number,
+    };
+    /** The method used to throttle the network. */
+    throttlingMethod: 'devtools'|'simulate'|'provided';
+    /** The throttling config settings. */
+    throttling?: Required<ThrottlingSettings>;
+    /** Precomputed lantern estimates to use instead of observed analysis. */
+    precomputedLanternData?: PrecomputedLanternData|null;
+  }
+
+  export interface Options {
+    rtt?: number;
+    throughput?: number;
+    observedThroughput: number;
+    maximumConcurrentRequests?: number;
+    cpuSlowdownMultiplier?: number;
+    layoutTaskMultiplier?: number;
+    additionalRttByOrigin?: Map<string, number>;
+    serverResponseTimeByOrigin?: Map<string, number>;
+  }
+
+  export interface ProcessedNavigation {
+    timestamps: {
+      firstContentfulPaint: number,
+      largestContentfulPaint?: number,
+    };
+  }
+
+  export interface NodeTiming {
+    startTime: number;
+    endTime: number;
+    duration: number;
+  }
+}

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

@@ -0,0 +1,5 @@
+// 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 * from './Lantern.js';

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

@@ -0,0 +1,33 @@
+// 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.
+
+import * as EntityMapper from './EntityMapper.js';
+import * as EventsSerializer from './EventsSerializer.js';
+import * as Extras from './extras/extras.js';
+import * as Handlers from './handlers/handlers.js';
+import * as Helpers from './helpers/helpers.js';
+import * as Insights from './insights/insights.js';
+import * as Lantern from './lantern/lantern.js';
+import * as LanternComputationData from './LanternComputationData.js';
+import * as TraceModel from './ModelImpl.js';
+import * as Name from './Name.js';
+import * as Processor from './Processor.js';
+import * as Styles from './Styles.js';
+import * as Types from './types/types.js';
+
+export {
+  EntityMapper,
+  EventsSerializer,
+  Extras,
+  Handlers,
+  Helpers,
+  Insights,
+  Lantern,
+  LanternComputationData,
+  Name,
+  Processor,
+  Styles,
+  TraceModel,
+  Types,
+};

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

@@ -0,0 +1,110 @@
+// Copyright 2023 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 Platform from '../../../core/platform/platform.js';
+import type * as SDK from '../../../core/sdk/sdk.js';
+import type * as Protocol from '../../../generated/protocol.js';
+import type * as Lantern from '../lantern/lantern.js';
+
+import type * as File from './File.js';
+import type {Milli} from './Timing.js';
+
+export interface Configuration {
+  /**
+   * Include V8 RCS functions in the JS stacks
+   */
+  includeRuntimeCallStats: boolean;
+  /**
+   * Show all events: disable the default filtering which hides and excludes some events.
+   */
+  showAllEvents: boolean;
+  /**
+   * Extra detail for RPP developers (eg Trace Event json in Summary, and individual JS Sample events)
+   */
+  debugMode: boolean;
+  /**
+   * How many invalidation events will be stored for a layout (or similar) event.
+   * On large sites with a lot of DOM there can be thousands of invalidations
+   * associated with any given event. It is not useful to show the user 1000s of
+   * invalidations in the UI, but it is also expensive for us to hold onto them
+   * all, and it helps prevents OOM issues when running in NodeJS
+   * [https://github.com/GoogleChrome/lighthouse/issues/16111].
+   * Therefore, instead, we store only the latest 20 per event. We do also store
+   * the total count, so we can show that, but we'll only ever hold on to the
+   * last 20 invalidations (in DESC trace order - so the latest 20 in the trace file)
+   *
+   * If you set this to 0, we will skip the Invalidations processing entirely.
+   * 0 effectively disables the InvalidationsHandler and it will not even
+   * attempt to gather or track invalidations.
+   */
+  maxInvalidationEventsPerEvent: number;
+  /**
+   * Determines if the AnimationFramesHandler should be enabled. Currently in
+   * DevTools we do not use it, so we disable it by default to avoid work that
+   * we do not use. If you disable it, you will still see `data.AnimationFrames`
+   * from the model, but the contents will be empty.
+   */
+  enableAnimationsFrameHandler: boolean;
+}
+
+export const defaults = (): Configuration => ({
+  includeRuntimeCallStats: false,
+  showAllEvents: false,
+  debugMode: false,
+  maxInvalidationEventsPerEvent: 20,
+  enableAnimationsFrameHandler: false,
+});
+
+/**
+ * Generates a key that can be used to represent this config in a cache. This is
+ * used mainly in tests, where we want to avoid re-parsing a file if we have
+ * already processed it with the same configuration.
+ */
+export function configToCacheKey(config: Configuration): string {
+  return JSON.stringify(config);
+}
+
+export interface ParseOptions {
+  showAllEvents?: boolean;
+  /**
+   * If the trace was just recorded on the current page, rather than an imported file.
+   * TODO(paulirish): Maybe remove. This is currently unused by the Processor and Handlers
+   * @default false
+   */
+  isFreshRecording?: boolean;
+  /**
+   * If the trace is a CPU Profile rather than a Chrome tracing trace.
+   * @default false
+   */
+  isCPUProfile?: boolean;
+  metadata?: File.MetaData;
+  resolveSourceMap?: (params: ResolveSourceMapParams) => Promise<SDK.SourceMap.SourceMap|null>;
+  logger?: {
+    start: (id: string) => void,
+    end: (id: string) => void,
+  };
+  lanternSettings?: Omit<Lantern.Types.Simulation.Settings, 'networkAnalysis'>;
+  /**
+   * Used when an Insight needs to format a time to string as part of its
+   * output. By default we use the i18n.TimeUtilities in DevTools but this
+   * enables it to be overridden, which is useful if you are consuming the trace
+   * engine outside of DevTools.
+   */
+  insightTimeFormatters?: InsightTimeFormatters;
+}
+
+export interface InsightTimeFormatters {
+  milli: (x: Milli) => string;
+}
+
+export interface ResolveSourceMapParams {
+  scriptId: string;
+  scriptUrl: Platform.DevToolsPath.UrlString;
+  /** The url as resolved by any sourceUrl comment. */
+  sourceUrl: Platform.DevToolsPath.UrlString;
+  sourceMapUrl: Platform.DevToolsPath.UrlString;
+  frame: Protocol.Page.FrameId;
+  /** Set only if the raw source map was found on the provided metadata. Never set for source maps from data urls. */
+  cachedRawSourceMap?: SDK.SourceMap.SourceMapV3;
+}