devtools-tracing 1.0.0

package/lib/front_end/models/trace/types/Extensions.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 type * as Platform from '../../../core/platform/platform.js';
+
+import type {
+  ConsoleTimeStamp, Event, PerformanceMark, PerformanceMeasureBegin, Phase, SyntheticBased} from './TraceEvents.js';
+
+export type ExtensionEntryType = 'track-entry'|'marker';
+
+export const extensionPalette = [
+  'primary',
+  'primary-light',
+  'primary-dark',
+  'secondary',
+  'secondary-light',
+  'secondary-dark',
+  'tertiary',
+  'tertiary-light',
+  'tertiary-dark',
+  'error',
+  'warning',
+] as const;
+
+export type ExtensionColorFromPalette = typeof extensionPalette[number];
+
+/**
+ * Represents any valid value that can be produced by JSON.parse()
+ * without a reviver.
+ */
+export type JsonValue = string|number|boolean|null|JsonValue[]|{[key: string]: JsonValue};
+
+export interface DevToolsObjBase {
+  color?: ExtensionColorFromPalette;
+  /**
+   * We document to users that we support only string values here, but because
+   * this is coming from user code the values could be anything, so we ensure we
+   * deal with bad data by typing this as unknown.
+   */
+  properties?: Array<[string, JsonValue]>;
+  tooltipText?: string;
+}
+
+export type DevToolsObj = DevToolsObjEntry|DevToolsObjMarker;
+
+export interface ExtensionTrackEntryPayloadDeeplink {
+  // The URL (deep-link) to show in the summary for the track.
+  url: Platform.DevToolsPath.UrlString;
+  // The label to show in front of the URL when the deep-link is shown in the
+  // graph.
+  description: string;
+}
+
+export interface DevToolsObjEntry extends DevToolsObjBase {
+  // Typed as possibly undefined since when no data type is provided
+  // the entry is defaulted to a track entry
+  dataType?: 'track-entry';
+  // The name of the track the entry will be displayed in.
+  // Entries intended to be displayed in the same track must contain the
+  // same value in this property.
+  // If undefined, measurement is added to the Timings track
+  track: string;
+  // The track group an entry’s track belongs to.
+  // Entries intended to be displayed in the same track must contain the
+  // same value in this property as well as the same value in the track
+  // property.
+  trackGroup?: string;
+  // Additional data (e.g. deep-link URL) that can be shown in the summary
+  // In perf.mark/measure, it's anything in the `detail` object that's not the `devtools` object
+  // In console.timestamp, it's the 7th argument to console.timeStamp().
+  userDetail?: JsonValue;
+}
+
+export interface DevToolsObjMarker extends DevToolsObjBase {
+  dataType: 'marker';
+}
+
+/**
+ * Synthetic events created for extension tracks.
+ */
+export interface SyntheticExtensionTrackEntry extends
+    SyntheticBased<Phase.COMPLETE, PerformanceMeasureBegin|PerformanceMark|ConsoleTimeStamp> {
+  devtoolsObj: DevToolsObjEntry;
+  userDetail: JsonValue|null;
+}
+
+/**
+ * Synthetic events created for extension marks.
+ */
+export interface SyntheticExtensionMarker extends SyntheticBased<Phase.INSTANT, PerformanceMark> {
+  devtoolsObj: DevToolsObjMarker;
+  userDetail: JsonValue|null;
+}
+
+export type SyntheticExtensionEntry = SyntheticExtensionTrackEntry|SyntheticExtensionMarker;
+
+/** Returns true if this is a devtoolsObj for a marker */
+export function isExtensionPayloadMarker(payload: {dataType?: string}): payload is DevToolsObjMarker {
+  return payload.dataType === 'marker';
+}
+
+/** Returns true if this is a devtoolsObj for an entry (non-instant) */
+export function isExtensionEntryObj(payload: {track?: string, dataType?: string}): payload is DevToolsObjEntry {
+  const hasTrack = 'track' in payload && Boolean(payload.track);
+  const validEntryType = payload.dataType === 'track-entry' || payload.dataType === undefined;
+  return validEntryType && hasTrack;
+}
+
+/** Returns true if this is a devtoolsObj for a console.timeStamp */
+export function isConsoleTimestampPayloadTrackEntry(payload: {description?: string, url?: string}):
+    payload is ExtensionTrackEntryPayloadDeeplink {
+  return payload.url !== undefined && payload.description !== undefined;
+}
+
+export function isValidExtensionPayload(
+    payload: {track?: string, dataType?: string, description?: string, url?: string}): payload is DevToolsObj|
+    ExtensionTrackEntryPayloadDeeplink {
+  return isExtensionPayloadMarker(payload) || isExtensionEntryObj(payload) ||
+      isConsoleTimestampPayloadTrackEntry(payload);
+}
+
+export function isSyntheticExtensionEntry(entry: Event): entry is SyntheticExtensionEntry {
+  return entry.cat === 'devtools.extension';
+}
+
+export interface ExtensionTrackData {
+  // Name of the top level track. If it's a track group then this value
+  // has the name of the group, otherwise it has the name of the track.
+  name: string;
+  isTrackGroup: boolean;
+  // If this contains the data of a track group, this property contains
+  // the entries of each of the tracks in the the group. If this is a
+  // standalone track, then this contains that track's entries only.
+  entriesByTrack: Record<string, SyntheticExtensionTrackEntry[]>;
+}

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

@@ -0,0 +1,281 @@
+// 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 SDK from '../../../core/sdk/sdk.js';
+import type * as Protocol from '../../../generated/protocol.js';
+import type * as CrUXManager from '../../../models/crux-manager/crux-manager.js';
+
+import type {TraceWindowMicro} from './Timing.js';
+import type {Event, LegacyTimelineFrame, ProcessID, SampleIndex, ThreadID} from './TraceEvents.js';
+
+export interface TraceFile {
+  traceEvents: readonly Event[];
+  metadata: MetaData;
+}
+
+export interface Breadcrumb {
+  window: TraceWindowMicro;
+  child: Breadcrumb|null;
+}
+
+export const enum DataOrigin {
+  CPU_PROFILE = 'CPUProfile',
+  TRACE_EVENTS = 'TraceEvents',
+}
+
+/**
+ * The Entries link can have 3 stated:
+ *  1. The Link creation is not started yet, meaning only the button that needs to be clicked to start creating the link is visible.
+ *  2. Pending to event - the creation is started, but the entry that the link points to has not been chosen yet
+ *  3. Link connected - final state, both entries present
+ */
+export const enum EntriesLinkState {
+  CREATION_NOT_STARTED = 'creation_not_started',
+  PENDING_TO_EVENT = 'pending_to_event',
+  CONNECTED = 'connected',
+}
+
+export const enum EventKeyType {
+  RAW_EVENT = 'r',
+  SYNTHETIC_EVENT = 's',
+  PROFILE_CALL = 'p',
+  LEGACY_TIMELINE_FRAME = 'l',
+}
+
+/**
+ * Represents an object that is saved in the file when user created annotations in the timeline.
+ *
+ * Expected to add more annotations.
+ */
+export interface SerializedAnnotations {
+  entryLabels: EntryLabelAnnotationSerialized[];
+  labelledTimeRanges: TimeRangeAnnotationSerialized[];
+  linksBetweenEntries: EntriesLinkAnnotationSerialized[];
+}
+
+/**
+ * Represents an object that is used to store the Entry Label annotation that is created when a user creates a label for an entry in the timeline.
+ */
+export interface EntryLabelAnnotation {
+  type: 'ENTRY_LABEL';
+  entry: Event|LegacyTimelineFrame;
+  label: string;
+}
+
+/**
+ * Represents an object that is used to store the Labelled Time Range Annotation that is created when a user creates a Time Range Selection in the timeline.
+ */
+export interface TimeRangeAnnotation {
+  type: 'TIME_RANGE';
+  label: string;
+  bounds: TraceWindowMicro;
+}
+
+export interface EntriesLinkAnnotation {
+  type: 'ENTRIES_LINK';
+  state: EntriesLinkState;
+  entryFrom: Event;
+  entryTo?: Event;
+}
+
+/**
+ * Represents an object that is saved in the file when a user creates a label for an entry in the timeline.
+ */
+export interface EntryLabelAnnotationSerialized {
+  entry: SerializableKey;
+  label: string;
+}
+
+/**
+ * Represents an object that is saved in the file when a user creates a time range with a label in the timeline.
+ */
+export interface TimeRangeAnnotationSerialized {
+  bounds: TraceWindowMicro;
+  label: string;
+}
+
+/**
+ * Represents an object that is saved in the file when a user creates a link between entries in the timeline.
+ */
+export interface EntriesLinkAnnotationSerialized {
+  entryFrom: SerializableKey;
+  entryTo: SerializableKey;
+}
+
+/**
+ * `Annotation` are the user-created annotations that are saved into the metadata.
+ * Those annotations are rendered on the timeline by `Overlays.ts`
+ *
+ * TODO: Implement other OverlayAnnotations (annotated time ranges, links between entries).
+ * TODO: Save/load overlay annotations to/from the trace file.
+ */
+export type Annotation = EntryLabelAnnotation|TimeRangeAnnotation|EntriesLinkAnnotation;
+
+export function isTimeRangeAnnotation(annotation: Annotation): annotation is TimeRangeAnnotation {
+  return annotation.type === 'TIME_RANGE';
+}
+
+export function isEntryLabelAnnotation(annotation: Annotation): annotation is EntryLabelAnnotation {
+  return annotation.type === 'ENTRY_LABEL';
+}
+
+export function isEntriesLinkAnnotation(annotation: Annotation): annotation is EntriesLinkAnnotation {
+  return annotation.type === 'ENTRIES_LINK';
+}
+
+/**
+ * Serializable keys are created for trace events to be able to save
+ * references to timeline events in a trace file. These keys enable
+ * user modifications that can be saved. See go/cpq:event-data-json for
+ * more details on the key format.
+ **/
+export type RawEventKey = `${EventKeyType.RAW_EVENT}-${number}`;
+export type SyntheticEventKey = `${EventKeyType.SYNTHETIC_EVENT}-${number}`;
+export type ProfileCallKey = `${EventKeyType.PROFILE_CALL}-${ProcessID}-${ThreadID}-${SampleIndex}-${Protocol.integer}`;
+export type LegacyTimelineFrameKey = `${EventKeyType.LEGACY_TIMELINE_FRAME}-${number}`;
+export type SerializableKey = RawEventKey|ProfileCallKey|SyntheticEventKey|LegacyTimelineFrameKey;
+
+/** Serializable keys values objects contain data that maps the keys to original Trace Events **/
+export interface RawEventKeyValues {
+  type: EventKeyType.RAW_EVENT;
+  rawIndex: number;
+}
+
+export interface SyntheticEventKeyValues {
+  type: EventKeyType.SYNTHETIC_EVENT;
+  rawIndex: number;
+}
+
+export interface ProfileCallKeyValues {
+  type: EventKeyType.PROFILE_CALL;
+  processID: ProcessID;
+  threadID: ThreadID;
+  sampleIndex: SampleIndex;
+  protocol: Protocol.integer;
+}
+
+export interface LegacyTimelineFrameKeyValues {
+  type: EventKeyType.LEGACY_TIMELINE_FRAME;
+  rawIndex: number;
+}
+
+export type SerializableKeyValues =
+    RawEventKeyValues|ProfileCallKeyValues|SyntheticEventKeyValues|LegacyTimelineFrameKeyValues;
+
+export interface Modifications {
+  entriesModifications: {
+    // Entries hidden by the user
+    hiddenEntries: SerializableKey[],
+    // Entries that parent a hiddenEntry
+    expandableEntries: SerializableKey[],
+  };
+  initialBreadcrumb: Breadcrumb;
+  annotations: SerializedAnnotations;
+}
+
+/**
+ * IMPORTANT: this is the same as PerfUI.FlameChart.PersistedGroupConfig
+ * However, the PerfUI code should not depend on the model/trace, and similarly
+ * this model cannot depend on that code, so we duplicate it.
+ **/
+export interface TrackVisualConfig {
+  hidden: boolean;
+  expanded: boolean;
+  originalIndex: number;
+  visualIndex: number;
+  trackName: string;
+}
+
+/**
+ * Stores the visual config if the user has modified it. Split into "main" and
+ * "network" so we can pass the relevant config into the right data provider.
+ * NOTE: as of August 2025 (M141) we currently do not export this in new
+ * traces, or use it if an existing trace is imported with it.
+ */
+export interface PersistedTraceVisualConfig {
+  main: TrackVisualConfig[]|null;
+  network: TrackVisualConfig[]|null;
+}
+
+/**
+ * Trace metadata that we persist to the file. This will allow us to
+ * store specifics for the trace, e.g., which tracks should be visible
+ * on load.
+ */
+export interface MetaData {
+  source?: 'DevTools';
+  startTime?: string;
+  emulatedDeviceTitle?: string;
+  // Only set if network throttling is active.
+  networkThrottling?: string;
+  // Only set if network throttling is active.
+  networkThrottlingConditions?: Omit<SDK.NetworkManager.Conditions, 'title'>;
+  // Only set if CPU throttling is active.
+  cpuThrottling?: number;
+  dataOrigin?: DataOrigin;
+  enhancedTraceVersion?: number;
+  modifications?: Modifications;
+  cruxFieldData?: CrUXManager.PageResult[];
+  /** Currently only stores JS maps, not CSS. This never stores data url source maps. */
+  sourceMaps?: MetadataSourceMap[];
+  visualTrackConfig?: PersistedTraceVisualConfig;
+  hostDPR?: number;
+}
+
+export interface MetadataSourceMap {
+  url: string;
+  /** If not defined, then this was a data url. */
+  sourceMapUrl?: string;
+  sourceMap: SDK.SourceMap.SourceMapV3;
+}
+
+export type Contents = TraceFile|Event[];
+
+export function traceEventKeyToValues(key: SerializableKey): SerializableKeyValues {
+  const parts = key.split('-');
+  const type = parts[0];
+
+  switch (type) {
+    case EventKeyType.PROFILE_CALL:
+      if (parts.length !== 5 ||
+          !(parts.every((part, i) => i === 0 || typeof part === 'number' || !isNaN(parseInt(part, 10))))) {
+        throw new Error(`Invalid ProfileCallKey: ${key}`);
+      }
+      return {
+        type: parts[0],
+        processID: parseInt(parts[1], 10),
+        threadID: parseInt(parts[2], 10),
+        sampleIndex: parseInt(parts[3], 10),
+        protocol: parseInt(parts[4], 10),
+      } as ProfileCallKeyValues;
+    case EventKeyType.RAW_EVENT:
+      if (parts.length !== 2 || !(typeof parts[1] === 'number' || !isNaN(parseInt(parts[1], 10)))) {
+        throw new Error(`Invalid RawEvent Key: ${key}`);
+      }
+      return {
+        type: parts[0],
+        rawIndex: parseInt(parts[1], 10),
+      } as RawEventKeyValues;
+    case EventKeyType.SYNTHETIC_EVENT:
+      if (parts.length !== 2 || !(typeof parts[1] === 'number' || !isNaN(parseInt(parts[1], 10)))) {
+        throw new Error(`Invalid SyntheticEvent Key: ${key}`);
+      }
+      return {
+        type: parts[0],
+        rawIndex: parseInt(parts[1], 10),
+      } as SyntheticEventKeyValues;
+    case EventKeyType.LEGACY_TIMELINE_FRAME: {
+      if (parts.length !== 2 || Number.isNaN(parseInt(parts[1], 10))) {
+        throw new Error(`Invalid LegacyTimelineFrame Key: ${key}`);
+      }
+      return {
+        type,
+        rawIndex: parseInt(parts[1], 10),
+      };
+    }
+
+    default:
+      throw new Error(`Unknown trace event key: ${key}`);
+  }
+}

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

@@ -0,0 +1,138 @@
+// Copyright 2025 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 {EntriesLinkState} from './File.js';
+import type {Micro, TraceWindowMicro} from './Timing.js';
+import type {Event, LegacyTimelineFrame, PageLoadEvent} from './TraceEvents.js';
+
+/**
+ * Represents which flamechart an entry is rendered in.
+ * We need to know this because when we place an overlay for an entry we need
+ * to adjust its Y value if it's in the main chart which is drawn below the
+ * network chart
+ */
+export type EntryChartLocation = 'main'|'network';
+
+/**
+ * You can add overlays to trace events, but also right now frames are drawn on
+ * the timeline but they are not trace events, so we need to allow for that.
+ * In the future when the frames track has been migrated to be powered by
+ * animation frames (crbug.com/345144583), we can remove the requirement to
+ * support TimelineFrame instances (which themselves will be removed from the
+ * codebase.)
+ */
+export type OverlayEntry = Event|LegacyTimelineFrame;
+
+/**
+ * Represents when a user has selected an entry in the timeline
+ */
+export interface EntrySelected {
+  type: 'ENTRY_SELECTED';
+  entry: OverlayEntry;
+}
+
+/**
+ * Drawn around an entry when we want to highlight it to the user.
+ */
+export interface EntryOutline {
+  type: 'ENTRY_OUTLINE';
+  entry: OverlayEntry;
+  outlineReason: 'ERROR'|'INFO';
+}
+
+/**
+ * Represents an object created when a user creates a label for an entry in the timeline.
+ */
+export interface EntryLabel {
+  type: 'ENTRY_LABEL';
+  entry: OverlayEntry;
+  label: string;
+}
+
+export interface EntriesLink {
+  type: 'ENTRIES_LINK';
+  state: EntriesLinkState;
+  entryFrom: OverlayEntry;
+  entryTo?: OverlayEntry;
+}
+
+/**
+ * Represents a time range on the trace. Also used when the user shift+clicks
+ * and drags to create a time range.
+ */
+export interface TimeRangeLabel {
+  type: 'TIME_RANGE';
+  bounds: TraceWindowMicro;
+  label: string;
+  showDuration: boolean;
+}
+
+/**
+ * Used to highlight with a red-candy stripe a time range. It takes an entry
+ * because this entry is the row that will be used to place the candy stripe,
+ * and its height will be set to the height of that row.
+ */
+export interface CandyStripedTimeRange {
+  type: 'CANDY_STRIPED_TIME_RANGE';
+  bounds: TraceWindowMicro;
+  entry: Event;
+}
+
+/**
+ * An EntryBreakdown, or section, that makes up a TimespanBreakdown.
+ */
+export interface TimespanBreakdownEntryBreakdown {
+  bounds: TraceWindowMicro;
+  label: string|HTMLElement;
+  showDuration: boolean;
+}
+
+/**
+ * Represents a timespan on a trace broken down into parts. Each part has a label to it.
+ * If an entry is defined, the breakdown will be vertically positioned based on it.
+ */
+export interface TimespanBreakdown {
+  type: 'TIMESPAN_BREAKDOWN';
+  sections: TimespanBreakdownEntryBreakdown[];
+  entry?: Event;
+  renderLocation?: 'BOTTOM_OF_TIMELINE'|'BELOW_EVENT'|'ABOVE_EVENT';
+}
+
+export interface TimestampMarker {
+  type: 'TIMESTAMP_MARKER';
+  timestamp: Micro;
+}
+
+/**
+ * Represents a timings marker. This has a line that runs up the whole canvas.
+ * We can hold an array of entries, in the case we want to hold more than one with the same timestamp.
+ * The adjusted timestamp being the timestamp for the event adjusted by closest navigation.
+ */
+export interface TimingsMarker {
+  type: 'TIMINGS_MARKER';
+  entries: PageLoadEvent[];
+  entryToFieldResult: Map<PageLoadEvent, TimingsMarkerFieldResult>;
+  adjustedTimestamp: Micro;
+}
+
+export interface TimingsMarkerFieldResult {
+  value: Micro;
+  pageScope: 'url'|'origin';
+}
+
+export interface BottomInfoBar {
+  type: 'BOTTOM_INFO_BAR';
+  // In DevTools, this infobar is a UI.Infobar.Infobar but we can't refer to
+  // the type here.
+  infobar: {
+    element: HTMLElement,
+    dispose: () => void,
+  };
+}
+
+/**
+ * All supported overlay types.
+ */
+export type Overlay = EntrySelected|EntryOutline|TimeRangeLabel|EntryLabel|EntriesLink|TimespanBreakdown|
+    TimestampMarker|CandyStripedTimeRange|TimingsMarker|BottomInfoBar;

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

@@ -0,0 +1,30 @@
+// 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.
+
+export type Micro = number&{_tag: 'MicroSeconds'};
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function Micro(value: number): Micro {
+  return value as Micro;
+}
+
+export type Milli = number&{_tag: 'MilliSeconds'};
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function Milli(value: number): Milli {
+  return value as Milli;
+}
+export type Seconds = number&{_tag: 'Seconds'};
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function Seconds(value: number): Seconds {
+  return value as Seconds;
+}
+
+export interface TraceWindow<TimeFormat extends Micro|Milli> {
+  min: TimeFormat;
+  max: TimeFormat;
+  range: TimeFormat;
+}
+
+/** See front_end/models/trace/helpers/Timing.ts for helpful utility functions like traceWindowFromMicroSeconds **/
+export type TraceWindowMicro = TraceWindow<Micro>;
+export type TraceWindowMilli = TraceWindow<Milli>;