@paulirish/trace_engine 0.0.41 → 0.0.42

package/models/trace/types/TraceEvents.d.ts

@@ -1,5 +1,5 @@
 import type * as Protocol from '../../../generated/protocol.js';
-import type { MicroSeconds, MilliSeconds, Seconds, TraceWindowMicroSeconds } from './Timing.js';
+import type { Micro, Milli, Seconds, TraceWindowMicro } from './Timing.js';
 export declare const enum Phase {
     BEGIN = "B",
     END = "E",
@@ -26,9 +26,6 @@ export declare const enum Phase {
     MARK = "R",
     CLOCK_SYNC = "c"
 }
-export type NonEmptyString = string & {
-    _tag: 'NonEmptyString';
-};
 export declare function isNestableAsyncPhase(phase: Phase): boolean;
 export declare function isPhaseAsync(phase: Phase): boolean;
 export declare function isFlowPhase(phase: Phase): boolean;
@@ -44,10 +41,10 @@ export interface Event {
     ph: Phase;
     pid: ProcessID;
     tid: ThreadID;
-    tts?: MicroSeconds;
-    ts: MicroSeconds;
-    tdur?: MicroSeconds;
-    dur?: MicroSeconds;
+    tts?: Micro;
+    ts: Micro;
+    tdur?: Micro;
+    dur?: Micro;
 }
 export interface Args {
     data?: ArgsData;
@@ -97,7 +94,7 @@ export interface Profile extends Sample {
     id: ProfileID;
     args: Args & {
         data: ArgsData & {
-            startTime: MicroSeconds;
+            startTime: Micro;
         };
     };
 }
@@ -107,14 +104,20 @@ export interface ProfileChunk extends Sample {
     args: Args & {
         data?: ArgsData & {
             cpuProfile?: PartialProfile;
-            timeDeltas?: MicroSeconds[];
-            lines?: MicroSeconds[];
+            timeDeltas?: Micro[];
+            lines?: Micro[];
         };
     };
 }
 export interface PartialProfile {
     nodes?: PartialNode[];
     samples: CallFrameID[];
+    /**
+     * Contains trace ids assigned to samples, if any. Trace ids are
+     * keyed by the sample index in the profile (the keys of the object
+     * are strings containing the numeric index).
+     */
+    trace_ids?: Record<string, number>;
 }
 export interface PartialNode {
     callFrame: CallFrame;
@@ -123,7 +126,7 @@ export interface PartialNode {
 }
 export interface Complete extends Event {
     ph: Phase.COMPLETE;
-    dur: MicroSeconds;
+    dur: Micro;
 }
 export interface RunTask extends Complete {
     name: Name.RUN_TASK;
@@ -133,7 +136,7 @@ export interface FireIdleCallback extends Complete {
     name: Name.FIRE_IDLE_CALLBACK;
     args: Args & {
         data: ArgsData & {
-            allottedMilliseconds: MilliSeconds;
+            allottedMilliseconds: Milli;
             frame: string;
             id: number;
             timedOut: boolean;
@@ -199,17 +202,17 @@ export interface EventTimingBegin extends Event {
     args: Args & {
         data: ArgsData & {
             cancelable: boolean;
-            duration: MilliSeconds;
+            duration: Milli;
             type: string;
             interactionId: number;
             interactionOffset: number;
             nodeId: Protocol.DOM.BackendNodeId;
             frame?: string;
-            processingEnd?: MilliSeconds;
-            processingStart?: MilliSeconds;
-            timeStamp?: MilliSeconds;
-            enqueuedToMainThreadTime?: MilliSeconds;
-            commitFinishTime?: MilliSeconds;
+            processingEnd?: Milli;
+            processingStart?: Milli;
+            timeStamp?: Milli;
+            enqueuedToMainThreadTime?: Milli;
+            commitFinishTime?: Milli;
         };
         frame?: string;
     };
@@ -233,31 +236,31 @@ export interface SyntheticNetworkRedirect {
     url: string;
     priority: string;
     requestMethod?: string;
-    ts: MicroSeconds;
-    dur: MicroSeconds;
+    ts: Micro;
+    dur: Micro;
 }
 interface SyntheticArgsData {
-    dnsLookup: MicroSeconds;
-    download: MicroSeconds;
-    downloadStart: MicroSeconds;
-    finishTime: MicroSeconds;
-    initialConnection: MicroSeconds;
+    dnsLookup: Micro;
+    download: Micro;
+    downloadStart: Micro;
+    finishTime: Micro;
+    initialConnection: Micro;
     isDiskCached: boolean;
     isHttps: boolean;
     isMemoryCached: boolean;
     isPushedResource: boolean;
-    networkDuration: MicroSeconds;
-    processingDuration: MicroSeconds;
-    proxyNegotiation: MicroSeconds;
-    queueing: MicroSeconds;
-    redirectionDuration: MicroSeconds;
-    requestSent: MicroSeconds;
-    sendStartTime: MicroSeconds;
-    ssl: MicroSeconds;
-    stalled: MicroSeconds;
-    totalTime: MicroSeconds;
+    networkDuration: Micro;
+    processingDuration: Micro;
+    proxyNegotiation: Micro;
+    queueing: Micro;
+    redirectionDuration: Micro;
+    requestSent: Micro;
+    sendStartTime: Micro;
+    ssl: Micro;
+    stalled: Micro;
+    totalTime: Micro;
     /** Server response time (receiveHeadersEnd - sendEnd) */
-    waiting: MicroSeconds;
+    waiting: Micro;
 }
 export interface SyntheticNetworkRequest extends Complete, SyntheticBased<Phase.COMPLETE> {
     rawSourceEvent: ResourceSendRequest;
@@ -310,12 +313,12 @@ export interface SyntheticNetworkRequest extends Complete, SyntheticBased<Phase.
         };
     };
     cat: 'loading';
-    name: 'SyntheticNetworkRequest';
+    name: Name.SYNTHETIC_NETWORK_REQUEST;
     ph: Phase.COMPLETE;
-    dur: MicroSeconds;
-    tdur: MicroSeconds;
-    ts: MicroSeconds;
-    tts: MicroSeconds;
+    dur: Micro;
+    tdur: Micro;
+    ts: Micro;
+    tts: Micro;
     pid: ProcessID;
     tid: ThreadID;
 }
@@ -331,8 +334,8 @@ export interface SyntheticWebSocketConnection extends Complete, SyntheticBased<P
     cat: string;
     name: 'SyntheticWebSocketConnection';
     ph: Phase.COMPLETE;
-    dur: MicroSeconds;
-    ts: MicroSeconds;
+    dur: Micro;
+    ts: Micro;
     pid: ProcessID;
     tid: ThreadID;
     s: Scope;
@@ -391,11 +394,26 @@ export interface AuctionWorkletDoneWithProcess extends Event {
 }
 export declare function isAuctionWorkletRunningInProcess(event: Event): event is AuctionWorkletRunningInProcess;
 export declare function isAuctionWorkletDoneWithProcess(event: Event): event is AuctionWorkletDoneWithProcess;
-export interface Screenshot extends Event {
+/**
+ * In January 2025 when crrev.com/c/6197645 landed, it changed the format of screenshot events.
+ * That is why we two screenshot types:
+ * `LegacyScreenshot` and `LegacySyntheticScreenshot`: BEFORE the above CL.
+ * `Screenshot`: AFTER the above CL.
+ * Important things to note:
+ * 1. Both the "old" and "new" events share the name "Screenshot" but their format is very different.
+ * 2. The old events had both a raw event (LegacyScreenshot) and a synthetic
+ *    event (LegacySyntheticScreenshot). The new events only have a raw event, as
+ *    we do not need the additional complexity of a synthetic event.
+ * 3. Because we like to support "old" traces, DevTools will maintain its
+ *    support for both screenshot events for the foreseeable future. If you are
+ *    consuming screenshot events from the ScreenshotHandler, you must make sure
+ *    to have your code deal with the two different formats.
+ */
+export interface LegacyScreenshot extends Event {
     /**
      * @deprecated This value is incorrect. Use ScreenshotHandler.getPresentationTimestamp()
      */
-    ts: MicroSeconds;
+    ts: Micro;
     /** The id is the frame sequence number in hex */
     id: string;
     args: Args & {
@@ -405,11 +423,13 @@ export interface Screenshot extends Event {
     cat: 'disabled-by-default-devtools.screenshot';
     ph: Phase.OBJECT_SNAPSHOT;
 }
+export declare function isLegacyScreenshot(event: Event): event is LegacyScreenshot;
+export declare function isLegacySyntheticScreenshot(event: Event): event is LegacySyntheticScreenshot;
 export declare function isScreenshot(event: Event): event is Screenshot;
-export interface SyntheticScreenshot extends Event, SyntheticBased {
-    rawSourceEvent: Screenshot;
+export interface LegacySyntheticScreenshot extends Event, SyntheticBased {
+    rawSourceEvent: LegacyScreenshot;
     /** This is the correct presentation timestamp. */
-    ts: MicroSeconds;
+    ts: Micro;
     args: Args & {
         dataUri: string;
     };
@@ -417,6 +437,14 @@ export interface SyntheticScreenshot extends Event, SyntheticBased {
     cat: 'disabled-by-default-devtools.screenshot';
     ph: Phase.OBJECT_SNAPSHOT;
 }
+export interface Screenshot extends Instant {
+    args: Args & {
+        snapshot: string;
+        source_id: number;
+        frame_sequence: number;
+        expected_display_time: number;
+    };
+}
 export interface Animation extends Event {
     args: Args & {
         data: ArgsData & {
@@ -455,29 +483,30 @@ export interface ProcessName extends Metadata {
 export interface Mark extends Event {
     ph: Phase.MARK;
 }
-export interface NavigationStartUnreliable extends Mark {
+export interface NavigationStart extends Mark {
     name: 'navigationStart';
     args: Args & {
+        frame: string;
         data?: ArgsData & {
-            /** An empty documentLoaderURL means this navigationStart is unreliable noise and can be ignored. */
-            documentLoaderURL: never;
+            /** Must be non-empty to be valid. An empty documentLoaderURL means the event can be ignored. */
+            documentLoaderURL: string;
             isLoadingMainFrame: boolean;
-            isOutermostMainFrame?: boolean;
             navigationId: string;
+            /**
+             * `isOutermostMainFrame` was introduced in crrev.com/c/3625434 and exists because of Fenced Frames
+             * [github.com/WICG/fenced-frame/tree/master/explainer]. Fenced frames introduce a situation where
+             * `isLoadingMainFrame` could be true for a navigation, but that navigation be within an embedded "main frame", and
+             * therefore it wouldn't be on the top level main frame. In situations where we need to distinguish that, we can
+             * rely on `isOutermostMainFrame`, which will only be true for navigations on the top level main frame.
+             * This flag is optional as it was introduced in May 2022; so users reasonably may import traces from before that
+             * date that do not have this field present.
+             */
+            isOutermostMainFrame?: boolean;
             /**
              * @deprecated use documentLoaderURL for navigation events URLs
              */
             url?: string;
         };
-        frame: string;
-    };
-}
-export interface NavigationStart extends NavigationStartUnreliable {
-    args: NavigationStartUnreliable['args'] & {
-        data: NavigationStartUnreliable['args']['data'] & {
-            /** This navigationStart is valid, as the documentLoaderURL isn't empty. */
-            documentLoaderURL: NonEmptyString;
-        };
     };
 }
 export interface FirstContentfulPaint extends Mark {
@@ -698,10 +727,10 @@ interface LayoutShiftSessionWindowData {
 export interface LayoutShiftParsedData {
     /** screenshot taken before and after this shift. Before *should* always exist, but after might not at the end of a trace. */
     screenshots: {
-        before: SyntheticScreenshot | null;
-        after: SyntheticScreenshot | null;
+        before: LegacySyntheticScreenshot | Screenshot | null;
+        after: LegacySyntheticScreenshot | Screenshot | null;
     };
-    timeFromNavigation?: MicroSeconds;
+    timeFromNavigation?: Micro;
     cumulativeWeightedScoreInWindow: number;
     sessionWindowData: LayoutShiftSessionWindowData;
 }
@@ -729,18 +758,18 @@ export type NavigationId = string | typeof NO_NAVIGATION;
  */
 export interface SyntheticLayoutShiftCluster {
     name: 'SyntheticLayoutShiftCluster';
-    clusterWindow: TraceWindowMicroSeconds;
+    clusterWindow: TraceWindowMicro;
     clusterCumulativeScore: number;
     events: SyntheticLayoutShift[];
     scoreWindows: {
-        good: TraceWindowMicroSeconds;
-        needsImprovement?: TraceWindowMicroSeconds;
-        bad?: TraceWindowMicroSeconds;
+        good: TraceWindowMicro;
+        needsImprovement?: TraceWindowMicro;
+        bad?: TraceWindowMicro;
     };
     navigationId?: NavigationId;
     worstShiftEvent?: Event;
-    ts: MicroSeconds;
-    dur: MicroSeconds;
+    ts: Micro;
+    dur: Micro;
     cat: '';
     ph: Phase.COMPLETE;
     pid: ProcessID;
@@ -816,24 +845,24 @@ export interface ResourceReceivedData extends Instant {
 }
 /** See https://mdn.github.io/shared-assets/images/diagrams/api/performance/timestamp-diagram.svg  */
 interface ResourceReceiveResponseTimingData {
-    connectEnd: MilliSeconds;
-    connectStart: MilliSeconds;
-    dnsEnd: MilliSeconds;
-    dnsStart: MilliSeconds;
-    proxyEnd: MilliSeconds;
-    proxyStart: MilliSeconds;
-    pushEnd: MilliSeconds;
-    pushStart: MilliSeconds;
-    receiveHeadersEnd: MilliSeconds;
-    receiveHeadersStart: MilliSeconds;
+    connectEnd: Milli;
+    connectStart: Milli;
+    dnsEnd: Milli;
+    dnsStart: Milli;
+    proxyEnd: Milli;
+    proxyStart: Milli;
+    pushEnd: Milli;
+    pushStart: Milli;
+    receiveHeadersEnd: Milli;
+    receiveHeadersStart: Milli;
     /** 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. */
     requestTime: Seconds;
-    sendEnd: MilliSeconds;
-    sendStart: MilliSeconds;
-    sslEnd: MilliSeconds;
-    sslStart: MilliSeconds;
-    workerReady: MilliSeconds;
-    workerStart: MilliSeconds;
+    sendEnd: Milli;
+    sendStart: Milli;
+    sslEnd: Milli;
+    sslStart: Milli;
+    workerReady: Milli;
+    workerStart: Milli;
 }
 export interface ResourceReceiveResponse extends Instant {
     name: 'ResourceReceiveResponse';
@@ -853,7 +882,7 @@ export interface ResourceReceiveResponse extends Instant {
             fromServiceWorker: boolean;
             mimeType: string;
             requestId: string;
-            responseTime: MilliSeconds;
+            responseTime: Milli;
             statusCode: number;
             timing?: ResourceReceiveResponseTimingData;
             connectionId: number;
@@ -1067,7 +1096,7 @@ export interface PerformanceMeasureBegin extends PairableUserTiming {
     args: Args & {
         detail?: string;
         stackTrace?: CallFrame[];
-        callTime?: MicroSeconds;
+        callTime?: Micro;
     };
     ph: Phase.ASYNC_NESTABLE_START;
 }
@@ -1078,7 +1107,7 @@ export interface PerformanceMark extends UserTiming {
         data?: ArgsData & {
             detail?: string;
             stackTrace?: CallFrame[];
-            callTime?: MicroSeconds;
+            callTime?: Micro;
         };
     };
     ph: Phase.INSTANT | Phase.MARK | Phase.ASYNC_NESTABLE_INSTANT;
@@ -1095,13 +1124,14 @@ export interface ConsoleTimeStamp extends Event {
     name: Name.CONSOLE_TIME_STAMP;
     ph: Phase.COMPLETE;
     args: Args & {
-        data: ArgsData & {
+        data?: ArgsData & {
             name: string | number;
             start?: string | number;
             end?: string | number;
             track?: string | number;
             trackGroup?: string | number;
             color?: string | number;
+            sampleTraceId?: number;
         };
     };
 }
@@ -1212,7 +1242,7 @@ export interface SyntheticEventPair<T extends PairableAsync = PairableAsync> ext
         local?: string;
         global?: string;
     };
-    dur: MicroSeconds;
+    dur: Micro;
     args: Args & {
         data: {
             beginEvent: T & PairableAsyncBegin;
@@ -1229,13 +1259,13 @@ export type SyntheticAnimationPair = SyntheticEventPair<Animation>;
 export interface SyntheticInteractionPair extends SyntheticEventPair<EventTimingBeginOrEnd> {
     interactionId: number;
     type: string;
-    ts: MicroSeconds;
-    dur: MicroSeconds;
-    processingStart: MicroSeconds;
-    processingEnd: MicroSeconds;
-    inputDelay: MicroSeconds;
-    mainThreadHandling: MicroSeconds;
-    presentationDelay: MicroSeconds;
+    ts: Micro;
+    dur: Micro;
+    processingStart: Micro;
+    processingEnd: Micro;
+    inputDelay: Micro;
+    mainThreadHandling: Micro;
+    presentationDelay: Micro;
 }
 /**
  * A profile call created in the frontend from samples disguised as a
@@ -1281,6 +1311,7 @@ export interface SyntheticJSSample extends Event {
     name: Name.JS_SAMPLE;
     args: Args & {
         data: ArgsData & {
+            traceId?: number;
             stackTrace: Protocol.Runtime.CallFrame[];
         };
     };
@@ -1532,8 +1563,6 @@ export declare function isProcessName(event: Event): event is ProcessName;
 export declare function isTracingStartedInBrowser(event: Event): event is TracingStartedInBrowser;
 export declare function isFrameCommittedInBrowser(event: Event): event is FrameCommittedInBrowser;
 export declare function isCommitLoad(event: Event): event is CommitLoad;
-/** @deprecated You probably want `isNavigationStart` instead. */
-export declare function isNavigationStartUnreliable(event: Event): event is NavigationStartUnreliable;
 export declare function isAnimation(event: Event): event is Animation;
 export declare function isSyntheticAnimation(event: Event): event is SyntheticAnimationPair;
 export declare function isLayoutShift(event: Event): event is LayoutShift;
@@ -1896,7 +1925,7 @@ export interface SchedulePostTaskCallback extends Instant {
         data: {
             taskId: number;
             priority: 'user-blocking' | 'user-visible' | 'background';
-            delay: MilliSeconds;
+            delay: Milli;
             frame?: string;
             stackTrace?: CallFrame;
         };
@@ -1909,7 +1938,7 @@ export interface RunPostTaskCallback extends Complete {
         data: {
             taskId: number;
             priority: 'user-blocking' | 'user-visible' | 'background';
-            delay: MilliSeconds;
+            delay: Milli;
             frame?: string;
         };
     };
@@ -1934,6 +1963,11 @@ export declare function isAbortPostTaskCallback(event: Event): event is RunPostT
  */
 export declare function isJSInvocationEvent(event: Event): boolean;
 export interface ConsoleRunTask extends Event {
+    args: Args & {
+        data: ArgsData & {
+            sampleTraceId?: number;
+        };
+    };
     name: Name.V8_CONSOLE_RUN_TASK;
 }
 export declare function isConsoleRunTask(event: Event): event is ConsoleRunTask;
@@ -2113,7 +2147,8 @@ export declare const enum Name {
     DOM_LOADING = "domLoading",
     BEGIN_REMOTE_FONT_LOAD = "BeginRemoteFontLoad",
     ANIMATION_FRAME = "AnimationFrame",
-    ANIMATION_FRAME_PRESENTATION = "AnimationFrame::Presentation"
+    ANIMATION_FRAME_PRESENTATION = "AnimationFrame::Presentation",
+    SYNTHETIC_NETWORK_REQUEST = "SyntheticNetworkRequest"
 }
 export declare const Categories: {
     readonly Console: "blink.console";
@@ -2135,10 +2170,10 @@ export declare const Categories: {
  * handlers.
  */
 export interface LegacyTimelineFrame extends Event {
-    startTime: MicroSeconds;
-    startTimeOffset: MicroSeconds;
-    endTime: MicroSeconds;
-    duration: MicroSeconds;
+    startTime: Micro;
+    startTimeOffset: Micro;
+    endTime: Micro;
+    duration: Micro;
     idle: boolean;
     dropped: boolean;
     isPartial: boolean;

package/models/trace/types/TraceEvents.js

@@ -28,8 +28,14 @@ export function isAuctionWorkletRunningInProcess(event) {
 export function isAuctionWorkletDoneWithProcess(event) {
     return event.name === 'AuctionWorkletDoneWithProcess';
 }
+export function isLegacyScreenshot(event) {
+    return event.name === "Screenshot" /* Name.SCREENSHOT */ && 'id' in event;
+}
+export function isLegacySyntheticScreenshot(event) {
+    return event.name === "Screenshot" /* Name.SCREENSHOT */ && 'dataUri' in (event.args ?? {});
+}
 export function isScreenshot(event) {
-    return event.name === "Screenshot" /* Name.SCREENSHOT */;
+    return event.name === "Screenshot" /* Name.SCREENSHOT */ && 'source_id' in (event.args ?? {});
 }
 const markerTypeGuards = [
     isMarkDOMContent,
@@ -264,10 +270,6 @@ export function isFrameCommittedInBrowser(event) {
 export function isCommitLoad(event) {
     return event.name === 'CommitLoad';
 }
-/** @deprecated You probably want `isNavigationStart` instead. */
-export function isNavigationStartUnreliable(event) {
-    return event.name === 'navigationStart';
-}
 export function isAnimation(event) {
     // We've found some rare traces with an Animtation trace event from a different category: https://crbug.com/1472375#comment7
     return event.name === 'Animation' && event.cat.includes('devtools.timeline');
@@ -355,7 +357,7 @@ export function isResourceReceivedData(event) {
     return event.name === 'ResourceReceivedData';
 }
 export function isSyntheticNetworkRequest(event) {
-    return event.name === 'SyntheticNetworkRequest';
+    return event.name === "SyntheticNetworkRequest" /* Name.SYNTHETIC_NETWORK_REQUEST */;
 }
 export function isSyntheticWebSocketConnection(event) {
     return event.name === 'SyntheticWebSocketConnection';
@@ -368,7 +370,7 @@ export function isPrePaint(event) {
 }
 /** A VALID navigation start (as it has a populated documentLoaderURL) */
 export function isNavigationStart(event) {
-    return Boolean(isNavigationStartUnreliable(event) && event.args.data && event.args.data.documentLoaderURL !== '');
+    return event.name === 'navigationStart' && event.args?.data?.documentLoaderURL !== '';
 }
 export function isMainFrameViewport(event) {
     return event.name === 'PaintTimingVisualizer::Viewport';