devtools-tracing 1.0.0

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

@@ -0,0 +1,306 @@
+// 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 Helpers from '../helpers/helpers.js';
+import * as Types from '../types/types.js';
+
+import type {HandlerName} from './types.js';
+import {data as userTimingsData} from './UserTimingsHandler.js';
+
+let extensionTrackEntries: Types.Extensions.SyntheticExtensionTrackEntry[] = [];
+let extensionTrackData: Types.Extensions.ExtensionTrackData[] = [];
+let extensionMarkers: Types.Extensions.SyntheticExtensionMarker[] = [];
+let entryToNode = new Map<Types.Events.Event, Helpers.TreeHelpers.TraceEntryNode>();
+let timeStampByName = new Map<string, Types.Events.ConsoleTimeStamp>();
+
+let syntheticConsoleEntriesForTimingsTrack: Types.Events.SyntheticConsoleTimeStamp[] = [];
+
+export interface ExtensionTraceData {
+  extensionTrackData: readonly Types.Extensions.ExtensionTrackData[];
+  extensionMarkers: readonly Types.Extensions.SyntheticExtensionMarker[];
+  // TODO(andoli): Can we augment Renderer's entryToNode instead? To avoid the split of TimelineUIUtils's getEventSelfTime()?
+  entryToNode: Map<Types.Events.Event, Helpers.TreeHelpers.TraceEntryNode>;
+  syntheticConsoleEntriesForTimingsTrack: Types.Events.SyntheticConsoleTimeStamp[];
+}
+
+export function handleEvent(_event: Types.Events.Event): void {
+  // Implementation not needed because data is sourced from UserTimingsHandler
+}
+
+export function reset(): void {
+  extensionTrackEntries = [];
+  syntheticConsoleEntriesForTimingsTrack = [];
+  extensionTrackData = [];
+  extensionMarkers = [];
+  entryToNode = new Map();
+  timeStampByName = new Map();
+}
+
+export async function finalize(): Promise<void> {
+  createExtensionFlameChartEntries();
+}
+
+function createExtensionFlameChartEntries(): void {
+  const pairedMeasures: readonly Types.Events.SyntheticUserTimingPair[] = userTimingsData().performanceMeasures;
+  const marks: readonly Types.Events.PerformanceMark[] = userTimingsData().performanceMarks;
+  const mergedRawExtensionEvents = Helpers.Trace.mergeEventsInOrder(pairedMeasures, marks);
+
+  extractPerformanceAPIExtensionEntries(mergedRawExtensionEvents);
+  extractConsoleAPIExtensionEntries();
+  // extensionTrackEntries is filled by the above two calls.
+  Helpers.Trace.sortTraceEventsInPlace(extensionTrackEntries);
+  Helpers.Extensions.buildTrackDataFromExtensionEntries(extensionTrackEntries, extensionTrackData, entryToNode);
+}
+
+/**
+ * Extracts extension entries from console.timeStamp events.
+ *
+ * Entries are built by pairing `console.timeStamp` events based on
+ * their names. When a `console.timeStamp` event includes a `start`
+ * argument (and optionally an `end` argument), it attempts to find
+ * previously recorded `console.timeStamp` events with names matching
+ * the `start` and `end` values. These matching events are then used to
+ * determine the start and end times of the new entry.
+ *
+ * If a `console.timeStamp` event includes data for a custom track
+ * (specified by the `track` argument), an extension track entry is
+ * created and added to the `extensionTrackEntries` array. These entries
+ * are used to visualize custom tracks in the Performance panel.
+ *
+ * If a `console.timeStamp` event includes data for a custom track
+ * (specified by the `track` argument), an extension track entry is
+ * created and added to the `extensionTrackEntries` array. These entries
+ * are used to visualize custom tracks in the Performance panel.
+ *
+ * If a `console.timeStamp` event does not specify a custom track but
+ * includes a start and/or end time (referencing other
+ * `console.timeStamp` names), a synthetic console time stamp entry is
+ * created and added to the `syntheticConsoleEntriesForTimingsTrack`
+ * array. These entries are displayed in the "Timings" track.
+ */
+export function extractConsoleAPIExtensionEntries(): void {
+  const consoleTimeStamps: readonly Types.Events.ConsoleTimeStamp[] = userTimingsData().timestampEvents;
+  for (const currentTimeStamp of consoleTimeStamps) {
+    if (!currentTimeStamp.args.data) {
+      continue;
+    }
+    const timeStampName = String(currentTimeStamp.args.data.name ?? currentTimeStamp.args.data.message);
+    timeStampByName.set(timeStampName, currentTimeStamp);
+    const {devtoolsObj: extensionData, userDetail} = extensionDataInConsoleTimeStamp(currentTimeStamp);
+    const start = currentTimeStamp.args.data.start;
+    const end = currentTimeStamp.args.data.end;
+    if (!extensionData && !start && !end) {
+      continue;
+    }
+    // If the start or end is a number, it's assumed to be a timestamp
+    // from the tracing clock, so we use that directly, otherwise we
+    // assume it's the label of a previous console timestamp, in which
+    // case we use its corresponding timestamp.
+    const startTimeStamp =
+        typeof start === 'number' ? Types.Timing.Micro(start) : timeStampByName.get(String(start))?.ts;
+    const endTimeStamp = typeof end === 'number' ? Types.Timing.Micro(end) : timeStampByName.get(String(end))?.ts;
+    if (endTimeStamp !== undefined && startTimeStamp === undefined) {
+      // Invalid data
+      continue;
+    }
+    const entryStartTime = startTimeStamp ?? currentTimeStamp.ts;
+    const entryEndTime = endTimeStamp ?? currentTimeStamp.ts;
+    if (extensionData) {
+      const unregisteredExtensionEntry: Omit<Types.Extensions.SyntheticExtensionTrackEntry, '_tag'> = {
+        ...currentTimeStamp,
+        name: timeStampName,
+        cat: 'devtools.extension',
+        devtoolsObj: extensionData,
+        userDetail,
+        rawSourceEvent: currentTimeStamp,
+        dur: Types.Timing.Micro(entryEndTime - entryStartTime),
+        ts: entryStartTime,
+        ph: Types.Events.Phase.COMPLETE,
+      };
+      const extensionEntry =
+          Helpers.SyntheticEvents.SyntheticEventsManager
+              .registerSyntheticEvent<Types.Extensions.SyntheticExtensionTrackEntry>(unregisteredExtensionEntry);
+      extensionTrackEntries.push(extensionEntry);
+      continue;
+    }
+    // If no extension data is found in the entry (no custom track name
+    // was passed), but the entry has a duration. we still save it here
+    // to be added in the timings track. Note that timings w/o duration
+    // and extension data are already handled by the UserTimingsHandler.
+    const unregisteredSyntheticTimeStamp: Omit<Types.Events.SyntheticConsoleTimeStamp, '_tag'> = {
+      ...currentTimeStamp,
+      name: timeStampName,
+      cat: 'disabled-by-default-v8.inspector',
+      ph: Types.Events.Phase.COMPLETE,
+      ts: entryStartTime,
+      dur: Types.Timing.Micro(entryEndTime - entryStartTime),
+      rawSourceEvent: currentTimeStamp
+    };
+    const syntheticTimeStamp =
+        Helpers.SyntheticEvents.SyntheticEventsManager.registerSyntheticEvent<Types.Events.SyntheticConsoleTimeStamp>(
+            unregisteredSyntheticTimeStamp);
+    syntheticConsoleEntriesForTimingsTrack.push(syntheticTimeStamp);
+  }
+}
+
+/**
+ * Extracts extension entries from Performance API events (marks and
+ * measures).
+ * It specifically looks for events that contain extension-specific data
+ * within their `detail` property.
+ *
+ * If an event's `detail` property can be parsed as a JSON object and
+ * contains a `devtools` field with a valid extension payload, a
+ * synthetic extension entry is created. The type of extension entry
+ * created depends on the payload:
+ *
+ * - If the payload conforms to `ExtensionPayloadMarker`, a
+ *   `SyntheticExtensionMarker` is created and added to the
+ *   `extensionMarkers` array. These markers represent single points in
+ *   time.
+ * - If the payload conforms to `ExtensionPayloadTrackEntry`, a
+ *   `SyntheticExtensionTrackEntry` is created and added to the
+ *   `extensionTrackEntries` array. These entries represent events with
+ *   a duration and are displayed on custom tracks in the Performance
+ *   panel.
+ *
+ * **Note:** Only events with a `detail` property that contains valid
+ * extension data are processed. Other `performance.mark` and
+ * `performance.measure` events are ignored.
+ *
+ * @param timings An array of `SyntheticUserTimingPair` or
+ *                `PerformanceMark` events, typically obtained from the
+ *                `UserTimingsHandler`.
+ */
+export function extractPerformanceAPIExtensionEntries(
+    timings: Array<Types.Events.SyntheticUserTimingPair|Types.Events.PerformanceMark>): void {
+  for (const timing of timings) {
+    const {devtoolsObj, userDetail} = extensionDataInPerformanceTiming(timing);
+    if (!devtoolsObj) {
+      // Not an extension user timing.
+      continue;
+    }
+
+    const extensionSyntheticEntry = {
+      name: timing.name,
+      ph: Types.Extensions.isExtensionPayloadMarker(devtoolsObj) ? Types.Events.Phase.INSTANT :
+                                                                   Types.Events.Phase.COMPLETE,
+      pid: timing.pid,
+      tid: timing.tid,
+      ts: timing.ts,
+      dur: timing.dur as Types.Timing.Micro,
+      cat: 'devtools.extension',
+      devtoolsObj,
+      userDetail,
+      rawSourceEvent: Types.Events.isSyntheticUserTiming(timing) ? timing.rawSourceEvent : timing,
+    };
+
+    if (Types.Extensions.isExtensionPayloadMarker(devtoolsObj)) {
+      const extensionMarker =
+          Helpers.SyntheticEvents.SyntheticEventsManager
+              .registerSyntheticEvent<Types.Extensions.SyntheticExtensionMarker>(
+                  extensionSyntheticEntry as Omit<Types.Extensions.SyntheticExtensionMarker, '_tag'>);
+      extensionMarkers.push(extensionMarker);
+      continue;
+    }
+
+    if (Types.Extensions.isExtensionEntryObj(extensionSyntheticEntry.devtoolsObj)) {
+      const extensionTrackEntry =
+          Helpers.SyntheticEvents.SyntheticEventsManager
+              .registerSyntheticEvent<Types.Extensions.SyntheticExtensionTrackEntry>(
+                  extensionSyntheticEntry as Omit<Types.Extensions.SyntheticExtensionTrackEntry, '_tag'>);
+      extensionTrackEntries.push(extensionTrackEntry);
+      continue;
+    }
+  }
+}
+
+/**
+ * Parses out the data in a performance.measure / mark call into two parts:
+ * 1. devtoolsObj: this is the data required to be passed by the user for the
+ *    event to be used to create a custom track in the performance panel.
+ * 2. userDetail: this is arbitrary data the user has attached to the event
+ *    that we show in the summary drawer.
+ */
+export function extensionDataInPerformanceTiming(
+    timing: Types.Events.SyntheticUserTimingPair|Types.Events.PerformanceMark):
+    {devtoolsObj: Types.Extensions.DevToolsObj|null, userDetail: Types.Extensions.JsonValue|null} {
+  const timingDetail =
+      Types.Events.isPerformanceMark(timing) ? timing.args.data?.detail : timing.args.data.beginEvent.args.detail;
+  if (!timingDetail) {
+    return {devtoolsObj: null, userDetail: null};
+  }
+  const devtoolsObj = Helpers.Trace.parseDevtoolsDetails(timingDetail, 'devtools') as Types.Extensions.DevToolsObj;
+
+  let userDetail = null;
+  try {
+    userDetail = JSON.parse(timingDetail);
+    delete userDetail.devtools;
+  } catch {
+    // Nothing to do here, we still want to return the `devtools` part to make
+    // this a custom event, even if the user detail failed to parse.
+  }
+
+  return {devtoolsObj, userDetail};
+}
+
+/**
+ * Extracts extension data from a `console.timeStamp` event.
+ *
+ * Checks if a `console.timeStamp` event contains data intended for
+ * creating a custom track entry in the DevTools Performance panel. It
+ * specifically looks for a `track` argument within the event's data.
+ *
+ * If a `track` argument is present (and not an empty string), the
+ * function constructs an `ExtensionTrackEntryPayload` object containing
+ * the track name, an optional color, an optional track group. This
+ * payload is then used to create a `SyntheticExtensionTrackEntry`.
+ *
+ * **Note:** The `color` argument is optional and its type is validated
+ * against a predefined palette (see
+ * `ExtensionUI::extensionEntryColor`).
+ *
+ * @param timeStamp The `ConsoleTimeStamp` event to extract data from.
+ * @returns An `ExtensionTrackEntryPayload` object if the event contains
+ *         valid extension data for a track entry, or `null` otherwise.
+ */
+export function extensionDataInConsoleTimeStamp(timeStamp: Types.Events.ConsoleTimeStamp):
+    {devtoolsObj: Types.Extensions.DevToolsObjEntry|null, userDetail: Types.Extensions.JsonValue|null} {
+  if (!timeStamp.args.data || !timeStamp.args.data.track) {
+    return {devtoolsObj: null, userDetail: null};
+  }
+
+  let userDetail = null;
+  try {
+    // While it's in the trace as 'devtools', it's just the 7th argument to console.timeStamp(), stringified.
+    // If no data, fall back to falsy empty string.
+    userDetail = JSON.parse(timeStamp.args.data?.devtools || '""') as Types.Extensions.JsonValue;
+  } catch {
+  }
+
+  const devtoolsObj: Types.Extensions.DevToolsObjEntry = {
+    // the color is defaulted to primary if it's value isn't one from
+    // the defined palette (see ExtensionUI::extensionEntryColor) so
+    // we don't need to check the value is valid here.
+    color: String(timeStamp.args.data.color) as Types.Extensions.DevToolsObjEntry['color'],
+    track: String(timeStamp.args.data.track),
+    dataType: 'track-entry',
+    trackGroup: timeStamp.args.data.trackGroup !== undefined ? String(timeStamp.args.data.trackGroup) : undefined,
+  };
+
+  return {devtoolsObj, userDetail};
+}
+
+export function data(): ExtensionTraceData {
+  return {
+    entryToNode,
+    extensionTrackData,
+    extensionMarkers,
+    syntheticConsoleEntriesForTimingsTrack,
+  };
+}
+
+export function deps(): HandlerName[] {
+  return ['UserTimings'];
+}

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

@@ -0,0 +1,175 @@
+// 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 Platform from '../../../core/platform/platform.js';
+import * as Types from '../types/types.js';
+
+// A flow is a logic connection between trace events. We display this
+// connection as arrows between trace events belonging to the same flow.
+
+// In the trace event format, flows are represented with pairing "flow
+// phase" events. Each flow phase event corresponds to one trace event
+// and indicates the role a trace event plays in a flow (start, step or
+// end). For each flow, one `start` and one `end` phase events are
+// included, while the amount of `step` phase events can be >= 0.
+
+// A flow phase event is assigned to a trace event when their cat, tid,
+// pid and ts are equal (see @flowPhaseBindingTokenForEvent ).
+
+// It's possible for a single event to belong to multiple flows. In that
+// case, it will have multiple corresponding flow phase events (one
+// per flow).
+
+// To parse flows, we first handle flow phase events, by creating unique
+// flows with the timestamps of each phase. Then, we place trace events
+// in the flows where their corresponding phase events were placed (if
+// there are any corresponding flow phase events at all).
+let flowDataByGroupToken = new Map<string, number>();
+
+interface EventFlowData {
+  flows: Set<number>;
+  bindingParsed: boolean;
+}
+type FlowBindingTuple =
+    Map<Types.Timing.Micro, Map<Types.Events.ProcessID, Map<Types.Events.ThreadID, Map<string, EventFlowData>>>>;
+
+// Given a trace event's flow binding tuple (timestamp, process id,
+// thread id and category) we determine if there is any flow data bound
+// to it by using this map's content. It's built when processing flow
+// events in a trace.
+// An alternative to having a map of four levels is having single map
+// from a string token built from concatenating the binding data to the
+// corresponding flow data. However, this token would be calculated for
+// every event in a trace, resulting in a lot of memory overhead and
+// major GC triggering. So we are trading off readability for
+// performance.
+let boundFlowData: FlowBindingTuple = new Map();
+
+let flowsById = new Map<number, Map<Types.Timing.Micro, Types.Events.Event>>();
+let flowEvents: Types.Events.FlowEvent[] = [];
+let nonFlowEvents: Types.Events.Event[] = [];
+let flows: Types.Events.Event[][] = [];
+const ID_COMPONENT_SEPARATOR = '-$-';
+export function reset(): void {
+  flows = [];
+  flowEvents = [];
+  nonFlowEvents = [];
+  flowDataByGroupToken = new Map();
+  boundFlowData = new Map();
+  flowsById = new Map();
+}
+
+export function handleEvent(event: Types.Events.Event): void {
+  if (Types.Events.isFlowPhaseEvent(event)) {
+    flowEvents.push(event);
+    return;
+  }
+  nonFlowEvents.push(event);
+}
+
+function processNonFlowEvent(event: Types.Events.Event): void {
+  const flowDataForEvent = boundFlowData.get(event.ts)?.get(event.pid)?.get(event.tid)?.get(event.cat);
+  if (!flowDataForEvent) {
+    return;
+  }
+  const {flows, bindingParsed} = flowDataForEvent;
+  if (bindingParsed) {
+    // We only consider the first event for a given flow binding tuple.
+    return;
+  }
+  for (const flowId of flows) {
+    const flow = Platform.MapUtilities.getWithDefault(
+        flowsById, flowId, () => new Map<Types.Timing.Micro, Types.Events.Event>());
+    flow.set(event.ts, event);
+  }
+  flowDataForEvent.bindingParsed = true;
+}
+
+/**
+ * Creates unique flows by tracking flow phase events. A new created
+ * flow whenever a flow start phase event is detected.
+ * Subsequent flow phase events with the same group token are added to
+ * this flow until a flow end phase is detected.
+ */
+function processFlowEvent(flowPhaseEvent: Types.Events.FlowEvent): void {
+  const flowGroup = flowGroupTokenForFlowPhaseEvent(flowPhaseEvent);
+  switch (flowPhaseEvent.ph) {
+    case (Types.Events.Phase.FLOW_START): {
+      const flowMetadata = {flowId: flowPhaseEvent.id, times: new Map([[flowPhaseEvent.ts, undefined]])};
+      flowDataByGroupToken.set(flowGroup, flowPhaseEvent.id);
+      addFlowIdToEventBinding(flowPhaseEvent, flowMetadata.flowId);
+      return;
+    }
+    case (Types.Events.Phase.FLOW_STEP): {
+      const flowId = flowDataByGroupToken.get(flowGroup);
+      if (flowId === undefined) {
+        // Found non-start flow event with no corresponding start flow,
+        // start event. Quietly ignore the problematic event.
+        return;
+      }
+      addFlowIdToEventBinding(flowPhaseEvent, flowId);
+      return;
+    }
+    case (Types.Events.Phase.FLOW_END): {
+      const flowId = flowDataByGroupToken.get(flowGroup);
+      if (flowId === undefined) {
+        // Found non-start flow event with no corresponding start flow,
+        // start event. Quietly ignore the problematic event.
+        return;
+      }
+      addFlowIdToEventBinding(flowPhaseEvent, flowId);
+      // We don't need this data anymore as the flow has been finished,
+      // so we can drop it.
+      flowDataByGroupToken.delete(flowGroup);
+    }
+  }
+}
+
+type MapValueType<T extends Map<unknown, unknown>> = NonNullable<ReturnType<T['get']>>;
+/**
+ * A single trace event can belong to multiple flows. This method
+ * tracks which flows (flowId) an event belongs to given its flow
+ * binding tuple (made of its ts, pid, tid and cat).
+ */
+function addFlowIdToEventBinding(event: Types.Events.Event, flowId: number): void {
+  const flowsByPid = Platform.MapUtilities.getWithDefault<Types.Timing.Micro, MapValueType<typeof boundFlowData>>(
+      boundFlowData, event.ts, () => new Map());
+  const flowsByTid = Platform.MapUtilities.getWithDefault<Types.Events.ProcessID, MapValueType<typeof flowsByPid>>(
+      flowsByPid, event.pid, () => new Map());
+  const flowsByCat = Platform.MapUtilities.getWithDefault<Types.Events.ThreadID, MapValueType<typeof flowsByTid>>(
+      flowsByTid, event.tid, () => new Map());
+  const flowData =
+      Platform.MapUtilities.getWithDefault(flowsByCat, event.cat, () => ({flows: new Set(), bindingParsed: false}));
+  flowData.flows.add(flowId);
+}
+
+/**
+ * Returns a token to group flow phase events (start, step and end)
+ * belonging to the same flow. Flow phase events belonging to the same
+ * flow share category, thread id, process id and name.
+ *
+ * Note that other phase events of other flows can share these
+ * attributes too. For this reason, we group flow phase events in
+ * cycles. A cycle starts on a flow start phase event and finishes on a
+ * flow end phase event. For this reason, flow phase events need to be
+ * handled in timestamp order.
+ */
+function flowGroupTokenForFlowPhaseEvent(event: Types.Events.FlowEvent): string {
+  return `${event.cat}${ID_COMPONENT_SEPARATOR}${event.name}${ID_COMPONENT_SEPARATOR}${event.id}`;
+}
+
+export async function finalize(): Promise<void> {
+  // Order is important: flow events need to be handled first.
+  flowEvents.forEach(processFlowEvent);
+  nonFlowEvents.forEach(processNonFlowEvent);
+  flows = [...flowsById.values()]
+              .map(flowMapping => [...flowMapping.values()])
+              .map(flow => flow.filter(event => event !== undefined))
+              .filter(flow => flow.length > 1);
+}
+
+export function data(): {flows: Types.Events.Event[][]} {
+  return {
+    flows,
+  };
+}