devtools-tracing 1.0.0

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

@@ -0,0 +1,236 @@
+// 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 Platform from '../../core/platform/platform.js';
+
+import * as Handlers from './handlers/handlers.js';
+import * as Helpers from './helpers/helpers.js';
+import type * as Insights from './insights/insights.js';
+import {TraceParseProgressEvent, TraceProcessor} from './Processor.js';
+import * as Types from './types/types.js';
+
+// Note: this model is implemented in a way that can support multiple trace
+// processors. Currently there is only one implemented, but you will see
+// references to "processors" plural because it can easily be extended in the future.
+
+/**
+ * The Model is responsible for parsing arrays of raw trace events and storing the
+ * resulting data. It can store multiple traces at once, and can return the data for
+ * any of them.
+ *
+ * Most uses of this class should be through `createWithAllHandlers`, but
+ * `createWithSubsetOfHandlers` can be used to run just some handlers.
+ **/
+export class Model extends EventTarget {
+  readonly #traces: ParsedTrace[] = [];
+  readonly #nextNumberByDomain = new Map<string, number>();
+
+  readonly #recordingsAvailable: string[] = [];
+  #lastRecordingIndex = 0;
+  #processor: TraceProcessor;
+  #config: Types.Configuration.Configuration = Types.Configuration.defaults();
+
+  static createWithAllHandlers(config?: Types.Configuration.Configuration): Model {
+    return new Model(Handlers.ModelHandlers, config);
+  }
+
+  /**
+   * Runs only the provided handlers.
+   *
+   * Callers must ensure they are providing all dependant handlers (although Meta is included automatically),
+   * and must know that the result of `.parsedTrace` will be limited to the handlers provided, even though
+   * the type won't reflect that.
+   */
+  static createWithSubsetOfHandlers(
+      traceHandlers: Partial<Handlers.Types.Handlers>, config?: Types.Configuration.Configuration): Model {
+    return new Model(traceHandlers as Handlers.Types.Handlers, config);
+  }
+
+  constructor(handlers: Handlers.Types.Handlers, config?: Types.Configuration.Configuration) {
+    super();
+    if (config) {
+      this.#config = config;
+    }
+    this.#processor = new TraceProcessor(handlers, this.#config);
+  }
+
+  /**
+   * Parses an array of trace events into a structured object containing all the
+   * information parsed by the trace handlers.
+   * You can `await` this function to pause execution until parsing is complete,
+   * or instead rely on the `ModuleUpdateEvent` that is dispatched when the
+   * parsing is finished.
+   *
+   * Once parsed, you then have to call the `parsedTrace` method, providing an
+   * index of the trace you want to have the data for. This is because any model
+   * can store a number of traces. Each trace is given an index, which starts at 0
+   * and increments by one as a new trace is parsed.
+   *
+   * @example
+   * // Awaiting the parse method() to block until parsing complete
+   * await this.traceModel.parse(events);
+   * const data = this.traceModel.parsedTrace(0)
+   * @example
+   * // Using an event listener to be notified when tracing is complete.
+   * this.traceModel.addEventListener(Trace.ModelUpdateEvent.eventName, (event) => {
+   *   if(event.data.data === 'done') {
+   *     // trace complete
+   *     const data = this.traceModel.parsedTrace(0);
+   *   }
+   * });
+   * void this.traceModel.parse(events);
+   **/
+  async parse(traceEvents: readonly Types.Events.Event[], config: Types.Configuration.ParseOptions = {}):
+      Promise<void> {
+    if (config.showAllEvents === undefined) {
+      config.showAllEvents = this.#config.showAllEvents;
+    }
+
+    const metadata = config.metadata || {};
+    // During parsing, periodically update any listeners on each processors'
+    // progress (if they have any updates).
+    const onTraceUpdate = (event: Event): void => {
+      const {data} = event as TraceParseProgressEvent;
+      this.dispatchEvent(new ModelUpdateEvent({type: ModelUpdateType.PROGRESS_UPDATE, data}));
+    };
+
+    this.#processor.addEventListener(TraceParseProgressEvent.eventName, onTraceUpdate);
+
+    // TODO(cjamcl): this.#processor.parse needs this to work. So it should either take it as input, or create it itself.
+    const syntheticEventsManager = Helpers.SyntheticEvents.SyntheticEventsManager.createAndActivate(traceEvents);
+
+    try {
+      // Wait for all outstanding promises before finishing the async execution,
+      // but perform all tasks in parallel.
+      await this.#processor.parse(traceEvents, config);
+      if (!this.#processor.data) {
+        throw new Error('processor did not parse trace');
+      }
+      const file = this.#storeAndCreateParsedTraceFile(
+          syntheticEventsManager, traceEvents, metadata, this.#processor.data, this.#processor.insights);
+      // We only push the file onto this.#traces here once we know it's valid
+      // and there's been no errors in the parsing.
+      this.#traces.push(file);
+    } catch (e) {
+      throw e;
+    } finally {
+      // All processors have finished parsing, no more updates are expected.
+      this.#processor.removeEventListener(TraceParseProgressEvent.eventName, onTraceUpdate);
+      // Finally, update any listeners that all processors are 'done'.
+      this.dispatchEvent(new ModelUpdateEvent({type: ModelUpdateType.COMPLETE, data: 'done'}));
+    }
+  }
+
+  #storeAndCreateParsedTraceFile(
+      syntheticEventsManager: Helpers.SyntheticEvents.SyntheticEventsManager,
+      traceEvents: readonly Types.Events.Event[], metadata: Types.File.MetaData, data: Handlers.Types.HandlerData,
+      traceInsights: Insights.Types.TraceInsightSets|null): ParsedTrace {
+    this.#lastRecordingIndex++;
+    let recordingName = `Trace ${this.#lastRecordingIndex}`;
+    const origin = Helpers.Trace.extractOriginFromTrace(data.Meta.mainFrameURL);
+    if (origin) {
+      const nextSequenceForDomain = Platform.MapUtilities.getWithDefault(this.#nextNumberByDomain, origin, () => 1);
+      recordingName = `${origin} (${nextSequenceForDomain})`;
+      this.#nextNumberByDomain.set(origin, nextSequenceForDomain + 1);
+    }
+    this.#recordingsAvailable.push(recordingName);
+
+    return {
+      traceEvents,
+      metadata,
+      data,
+      insights: traceInsights,
+      syntheticEventsManager,
+    };
+  }
+
+  lastTraceIndex(): number {
+    return this.size() - 1;
+  }
+
+  /**
+   * Returns the parsed trace data indexed by the order in which it was stored.
+   * If no index is given, the last stored parsed data is returned.
+   */
+  parsedTrace(index: number = this.#traces.length - 1): ParsedTrace|null {
+    return this.#traces.at(index) ?? null;
+  }
+
+  overrideModifications(index: number, newModifications: Types.File.Modifications): void {
+    if (this.#traces[index]) {
+      this.#traces[index].metadata.modifications = newModifications;
+    }
+  }
+
+  syntheticTraceEventsManager(index: number = this.#traces.length - 1): Helpers.SyntheticEvents.SyntheticEventsManager
+      |null {
+    return this.#traces.at(index)?.syntheticEventsManager ?? null;
+  }
+
+  size(): number {
+    return this.#traces.length;
+  }
+
+  deleteTraceByIndex(recordingIndex: number): void {
+    this.#traces.splice(recordingIndex, 1);
+    this.#recordingsAvailable.splice(recordingIndex, 1);
+  }
+
+  getRecordingsAvailable(): string[] {
+    return this.#recordingsAvailable;
+  }
+
+  resetProcessor(): void {
+    this.#processor.reset();
+  }
+}
+
+/**
+ * This parsed trace is used by the Model. It keeps multiple instances
+ * of these so that the user can swap between them. The key is that it is
+ * essentially the TraceFile plus whatever the model has parsed from it.
+ */
+export type ParsedTrace = Types.File.TraceFile&{
+  data: Handlers.Types.HandlerData,
+  /** Is null for CPU profiles. */
+  insights: Insights.Types.TraceInsightSets | null,
+  syntheticEventsManager: Helpers.SyntheticEvents.SyntheticEventsManager,
+};
+
+export const enum ModelUpdateType {
+  COMPLETE = 'COMPLETE',
+  PROGRESS_UPDATE = 'PROGRESS_UPDATE',
+}
+
+export type ModelUpdateEventData = ModelUpdateEventComplete|ModelUpdateEventProgress;
+
+export interface ModelUpdateEventComplete {
+  type: ModelUpdateType.COMPLETE;
+  data: 'done';
+}
+export interface ModelUpdateEventProgress {
+  type: ModelUpdateType.PROGRESS_UPDATE;
+  data: TraceParseEventProgressData;
+}
+
+export interface TraceParseEventProgressData {
+  percent: number;
+}
+
+export class ModelUpdateEvent extends Event {
+  static readonly eventName = 'modelupdate';
+  constructor(public data: ModelUpdateEventData) {
+    super(ModelUpdateEvent.eventName);
+  }
+}
+
+declare global {
+  interface HTMLElementEventMap {
+    [ModelUpdateEvent.eventName]: ModelUpdateEvent;
+  }
+}
+
+export function isModelUpdateDataComplete(eventData: ModelUpdateEventData): eventData is ModelUpdateEventComplete {
+  return eventData.type === ModelUpdateType.COMPLETE;
+}

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

@@ -0,0 +1,136 @@
+// 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 Common from '../../core/common/common.js';
+import * as i18n from '../../core/i18n/i18n.js';
+
+import * as Handlers from './handlers/handlers.js';
+import type {ParsedTrace} from './ModelImpl.js';
+import {getEventStyle} from './Styles.js';
+import * as Types from './types/types.js';
+
+const UIStrings = {
+  /**
+   * @description Text shown for an entry in the flame chart that has no explicit name.
+   */
+  anonymous: '(anonymous)',
+  /**
+   * @description Text used to show an EventDispatch event which has a type associated with it
+   * @example {click} PH1
+   */
+  eventDispatchS: 'Event: {PH1}',
+  /**
+   * @description Text shown for an entry in the flame chart that represents a frame.
+   */
+  frame: 'Frame',
+  /**
+   * @description Text in Timeline Flame Chart Data Provider of the Performance panel
+   */
+  wsConnectionOpened: 'WebSocket opened',
+  /**
+   * @description Text in Timeline Flame Chart Data Provider of the Performance panel
+   * @example {ws://example.com} PH1
+   */
+  wsConnectionOpenedWithUrl: 'WebSocket opened: {PH1}',
+  /**
+   * @description Text in Timeline Flame Chart Data Provider of the Performance panel
+   */
+  wsConnectionClosed: 'WebSocket closed',
+  /**
+   * @description Text in Timeline Flame Chart Data Provider of the Performance panel
+   */
+  layoutShift: 'Layout shift',
+} as const;
+
+const str_ = i18n.i18n.registerUIStrings('models/trace/Name.ts', UIStrings);
+const i18nString = i18n.i18n.getLocalizedString.bind(undefined, str_);
+
+/**
+ * Calculates the display name for a given entry.
+ * @param parsedTrace If the trace data is provided
+ * as the second argument it can be used to find source map resolved names for
+ * profile calls.
+ * Use this function to customize the user visible name for an entry. If no
+ * custom name is found, we will fallback to the `name` property in the trace
+ * entry.
+ */
+export function forEntry(
+    entry: Types.Events.Event,
+    parsedTrace?: ParsedTrace,
+    ): string {
+  if (Types.Events.isProfileCall(entry)) {
+    if (parsedTrace) {
+      const potentialCallName =
+          Handlers.ModelHandlers.Samples.getProfileCallFunctionName(parsedTrace.data.Samples, entry);
+      // We need this extra check because the call name could be the empty
+      // string. If it is, we want to fallback.
+      if (potentialCallName) {
+        return potentialCallName;
+      }
+    }
+    return entry.callFrame.functionName || i18nString(UIStrings.anonymous);
+  }
+
+  if (Types.Events.isLegacyTimelineFrame(entry)) {
+    return i18n.i18n.lockedString(UIStrings.frame);
+  }
+
+  if (Types.Events.isDispatch(entry)) {
+    // EventDispatch represent user actions such as clicks, so in this case
+    // rather than show the event title (which is always just "Event"), we
+    // add the type ("click") to help the user understand the event.
+    return i18nString(UIStrings.eventDispatchS, {PH1: entry.args.data.type});
+  }
+  if (Types.Events.isSyntheticNetworkRequest(entry)) {
+    const parsedURL = new Common.ParsedURL.ParsedURL(entry.args.data.url);
+    const text =
+        parsedURL.isValid ? `${parsedURL.displayName} (${parsedURL.host})` : entry.args.data.url || 'Network request';
+    return text;
+  }
+
+  if (Types.Events.isWebSocketCreate(entry)) {
+    if (entry.args.data.url) {
+      return i18nString(UIStrings.wsConnectionOpenedWithUrl, {PH1: entry.args.data.url});
+    }
+
+    return i18nString(UIStrings.wsConnectionOpened);
+  }
+
+  if (Types.Events.isWebSocketDestroy(entry)) {
+    return i18nString(UIStrings.wsConnectionClosed);
+  }
+
+  if (Types.Events.isSyntheticInteraction(entry)) {
+    return nameForInteractionEvent(entry);
+  }
+
+  if (Types.Events.isSyntheticLayoutShift(entry)) {
+    return i18nString(UIStrings.layoutShift);
+  }
+
+  if (Types.Events.isSyntheticAnimation(entry) && entry.args.data.beginEvent.args.data.displayName) {
+    return entry.args.data.beginEvent.args.data.displayName;
+  }
+
+  const eventStyleCustomName = getEventStyle(entry.name as Types.Events.Name)?.title;
+
+  return eventStyleCustomName || entry.name;
+}
+
+function nameForInteractionEvent(event: Types.Events.SyntheticInteractionPair): string {
+  const category = Handlers.ModelHandlers.UserInteractions.categoryOfInteraction(event);
+  // Because we hide nested interactions, we do not want to show the
+  // specific type of the interaction that was not hidden, so instead we
+  // show just the category of that interaction.
+  if (category === 'OTHER') {
+    return 'Other';
+  }
+  if (category === 'KEYBOARD') {
+    return 'Keyboard';
+  }
+  if (category === 'POINTER') {
+    return 'Pointer';
+  }
+  return event.type;
+}