devtools-tracing 1.1.0 → 1.2.0

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

@@ -1,136 +0,0 @@
-// 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

@@ -1,281 +0,0 @@
-// 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

@@ -1,138 +0,0 @@
-// 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

@@ -1,30 +0,0 @@
-// 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>;