@paulirish/trace_engine 0.0.21 → 0.0.23

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

@@ -1,33 +1,21 @@
-export type Configuration = Readonly<{
-    settings: {};
-    experiments: {
-        /**
-         * Include V8 RCS in the timeline
-         */
-        timelineV8RuntimeCallStats: boolean;
-        /**
-         * Show all events: disable the default filtering which hides and excludes some events.
-         */
-        timelineShowAllEvents: boolean;
-    };
-    processing: {
-        /**
-         * How long the processor should pause between event chunks.
-         */
-        pauseDuration: number;
-        /**
-         * How many events should be processed before yielding to the main thread for a pause.
-         */
-        eventsPerChunk: number;
-    };
-}>;
-export declare const DEFAULT: Configuration;
+export type Configuration = {
+    /**
+     * Include V8 RCS functions in the JS stacks
+     */
+    includeRuntimeCallStats: boolean;
+    /**
+     * Show all events: disable the default filtering which hides and excludes some events.
+     */
+    showAllEvents: boolean;
+    /**
+     * Extra detail for RPP developers (eg Trace Event json in Summary, and individual JS Sample events)
+     */
+    debugMode: boolean;
+};
+export declare const defaults: () => Configuration;
 /**
  * Generates a key that can be used to represent this config in a cache. This is
  * used mainly in tests, where we want to avoid re-parsing a file if we have
- * already processed it with the same configuration. This cache key purposefully
- * does not include all settings in the configuration; the processing settings
- * do not impact the actual resulting data. Only new flags in the config that
- * alter parsing should be added to this cache key.
+ * already processed it with the same configuration.
  */
 export declare function configToCacheKey(config: Configuration): string;

package/models/trace/types/Configuration.js

@@ -1,37 +1,17 @@
 // Copyright 2023 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
-export const DEFAULT = {
-    settings: {},
-    experiments: {
-        timelineV8RuntimeCallStats: false,
-        timelineShowAllEvents: false,
-    },
-    processing: {
-        /**
-         * We want to yield regularly to maintain responsiveness. If we yield too often, we're wasting idle time.
-         * We could do this by checking `performance.now()` regularly, but it's an expensive call in such a hot loop.
-         * `eventsPerChunk` is an approximated proxy metric.
-         * But how big a chunk? We're aiming for long tasks that are no smaller than 100ms and not bigger than 200ms.
-         * It's CPU dependent, so it should be calibrated on oldish hardware.
-         * Illustration of a previous change to `eventsPerChunk`: https://imgur.com/wzp8BnR
-         */
-        eventsPerChunk: 50_000,
-        pauseDuration: 0,
-    },
-};
+export const defaults = () => ({
+    includeRuntimeCallStats: false,
+    showAllEvents: false,
+    debugMode: false,
+});
 /**
  * Generates a key that can be used to represent this config in a cache. This is
  * used mainly in tests, where we want to avoid re-parsing a file if we have
- * already processed it with the same configuration. This cache key purposefully
- * does not include all settings in the configuration; the processing settings
- * do not impact the actual resulting data. Only new flags in the config that
- * alter parsing should be added to this cache key.
+ * already processed it with the same configuration.
  */
 export function configToCacheKey(config) {
-    return [
-        `experiments.timelineShowAllEvents:${config.experiments.timelineShowAllEvents}`,
-        `experiments.timelineV8RuntimeCallStats:${config.experiments.timelineV8RuntimeCallStats}`,
-    ].join('-');
+    return JSON.stringify(config);
 }
 //# sourceMappingURL=Configuration.js.map

package/models/trace/types/Configuration.js.map

@@ -1 +1 @@
-{"version":3,"file":"Configuration.js","sourceRoot":"","sources":["../../../../../../../front_end/models/trace/types/Configuration.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,yEAAyE;AACzE,6BAA6B;AA4B7B,MAAM,CAAC,MAAM,OAAO,GAAkB;IACpC,QAAQ,EAAE,EAAE;IACZ,WAAW,EAAE;QACX,0BAA0B,EAAE,KAAK;QACjC,qBAAqB,EAAE,KAAK;KAC7B;IACD,UAAU,EAAE;QAEV;;;;;;;WAOG;QACH,cAAc,EAAE,MAAM;QACtB,aAAa,EAAE,CAAC;KACjB;CACF,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAqB;IACpD,OAAO;QACL,qCAAqC,MAAM,CAAC,WAAW,CAAC,qBAAqB,EAAE;QAC/E,0CAA0C,MAAM,CAAC,WAAW,CAAC,0BAA0B,EAAE;KAC1F,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC","sourcesContent":["// Copyright 2023 The Chromium Authors. All rights reserved.\n// Use of this source code is governed by a BSD-style license that can be\n// found in the LICENSE file.\n\nexport type Configuration = Readonly<{\n  settings: {\n      // Currently empty but defining here as we will migrate more settings into this.\n  },\n  experiments: {\n    /**\n     * Include V8 RCS in the timeline\n     */\n    timelineV8RuntimeCallStats: boolean,\n    /**\n     * Show all events: disable the default filtering which hides and excludes some events.\n     */\n    timelineShowAllEvents: boolean,\n  },\n  processing: {\n    /**\n     * How long the processor should pause between event chunks.\n     */\n    pauseDuration: number,\n    /**\n     * How many events should be processed before yielding to the main thread for a pause.\n     */\n    eventsPerChunk: number,\n  },\n}>;\n\nexport const DEFAULT: Configuration = {\n  settings: {},\n  experiments: {\n    timelineV8RuntimeCallStats: false,\n    timelineShowAllEvents: false,\n  },\n  processing: {\n\n    /**\n     * We want to yield regularly to maintain responsiveness. If we yield too often, we're wasting idle time.\n     * We could do this by checking `performance.now()` regularly, but it's an expensive call in such a hot loop.\n     * `eventsPerChunk` is an approximated proxy metric.\n     * But how big a chunk? We're aiming for long tasks that are no smaller than 100ms and not bigger than 200ms.\n     * It's CPU dependent, so it should be calibrated on oldish hardware.\n     * Illustration of a previous change to `eventsPerChunk`: https://imgur.com/wzp8BnR\n     */\n    eventsPerChunk: 50_000,\n    pauseDuration: 0,\n  },\n};\n\n/**\n * Generates a key that can be used to represent this config in a cache. This is\n * used mainly in tests, where we want to avoid re-parsing a file if we have\n * already processed it with the same configuration. This cache key purposefully\n * does not include all settings in the configuration; the processing settings\n * do not impact the actual resulting data. Only new flags in the config that\n * alter parsing should be added to this cache key.\n */\nexport function configToCacheKey(config: Configuration): string {\n  return [\n    `experiments.timelineShowAllEvents:${config.experiments.timelineShowAllEvents}`,\n    `experiments.timelineV8RuntimeCallStats:${config.experiments.timelineV8RuntimeCallStats}`,\n  ].join('-');\n}\n"]}
+{"version":3,"file":"Configuration.js","sourceRoot":"","sources":["../../../../../../../front_end/models/trace/types/Configuration.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,yEAAyE;AACzE,6BAA6B;AAiB7B,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAkB,EAAE,CAAC,CAAC;IAC5C,uBAAuB,EAAE,KAAK;IAC9B,aAAa,EAAE,KAAK;IACpB,SAAS,EAAE,KAAK;CACjB,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAqB;IACpD,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AAChC,CAAC","sourcesContent":["// Copyright 2023 The Chromium Authors. All rights reserved.\n// Use of this source code is governed by a BSD-style license that can be\n// found in the LICENSE file.\n\nexport type Configuration = {\n  /**\n   * Include V8 RCS functions in the JS stacks\n   */\n  includeRuntimeCallStats: boolean,\n  /**\n   * Show all events: disable the default filtering which hides and excludes some events.\n   */\n  showAllEvents: boolean,\n  /**\n   * Extra detail for RPP developers (eg Trace Event json in Summary, and individual JS Sample events)\n   */\n  debugMode: boolean,\n};\n\nexport const defaults = (): Configuration => ({\n  includeRuntimeCallStats: false,\n  showAllEvents: false,\n  debugMode: false,\n});\n\n/**\n * Generates a key that can be used to represent this config in a cache. This is\n * used mainly in tests, where we want to avoid re-parsing a file if we have\n * already processed it with the same configuration.\n */\nexport function configToCacheKey(config: Configuration): string {\n  return JSON.stringify(config);\n}\n"]}

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

@@ -63,6 +63,7 @@ export interface TraceEventCallFrame {
     lineNumber: number;
     url: string;
 }
+export declare function objectIsTraceEventCallFrame(object: {}): object is TraceEventCallFrame;
 export interface TraceFrame {
     frame: string;
     name: string;
@@ -78,7 +79,7 @@ export interface TraceEventSample extends TraceEventData {
  * A fake trace event created to support CDP.Profiler.Profiles in the
  * trace engine.
  */
-export interface SyntheticCpuProfile extends TraceEventInstant {
+export interface SyntheticCpuProfile extends TraceEventInstant, SyntheticEvent<Phase.INSTANT> {
     name: 'CpuProfile';
     args: TraceEventArgs & {
         data: TraceEventArgsData & {
@@ -119,6 +120,10 @@ export interface TraceEventComplete extends TraceEventData {
     ph: Phase.COMPLETE;
     dur: MicroSeconds;
 }
+export interface TraceEventRunTask extends TraceEventComplete {
+    name: KnownEventName.RunTask;
+}
+export declare function isTraceEventRunTask(event: TraceEventData): event is TraceEventRunTask;
 export interface TraceEventFireIdleCallback extends TraceEventComplete {
     name: KnownEventName.FireIdleCallback;
     args: TraceEventArgs & {
@@ -242,7 +247,8 @@ interface SyntheticArgsData {
     totalTime: MicroSeconds;
     waiting: MicroSeconds;
 }
-export interface SyntheticNetworkRequest extends TraceEventComplete {
+export interface SyntheticNetworkRequest extends TraceEventComplete, SyntheticEvent<Phase.COMPLETE> {
+    rawSourceEvent: TraceEventData;
     args: TraceEventArgs & {
         data: TraceEventArgsData & {
             syntheticData: SyntheticArgsData;
@@ -251,12 +257,16 @@ export interface SyntheticNetworkRequest extends TraceEventComplete {
             frame: string;
             fromServiceWorker: boolean;
             isLinkPreload: boolean;
-            host: string;
             mimeType: string;
-            pathname: string;
-            search: string;
             priority: Protocol.Network.ResourcePriority;
             initialPriority: Protocol.Network.ResourcePriority;
+            /**
+             * This is the protocol used to resolve the request.
+             *
+             * Note, this is not the same as URL.protocol.
+             *
+             * Example values (not exhaustive): http/0.9, http/1.0, http/1.1, http, h2, h3-Q050, data, blob
+             */
             protocol: string;
             redirects: SyntheticNetworkRedirect[];
             renderBlocking: RenderBlocking;
@@ -296,7 +306,8 @@ export declare const enum AuctionWorkletType {
     SELLER = "seller",
     UNKNOWN = "unknown"
 }
-export interface SyntheticAuctionWorkletEvent extends TraceEventInstant {
+export interface SyntheticAuctionWorkletEvent extends TraceEventInstant, SyntheticEvent<Phase.INSTANT> {
+    rawSourceEvent: TraceEventData;
     name: 'SyntheticAuctionWorkletEvent';
     pid: ProcessID;
     host: string;
@@ -359,7 +370,8 @@ export interface TraceEventScreenshot extends TraceEventData {
     ph: Phase.OBJECT_SNAPSHOT;
 }
 export declare function isTraceEventScreenshot(event: TraceEventData): event is TraceEventScreenshot;
-export interface SyntheticScreenshot extends TraceEventData {
+export interface SyntheticScreenshot extends TraceEventData, SyntheticEvent {
+    rawSourceEvent: TraceEventScreenshot;
     /** This is the correct presentation timestamp. */
     ts: MicroSeconds;
     args: TraceEventArgs & {
@@ -371,19 +383,22 @@ export interface SyntheticScreenshot extends TraceEventData {
 }
 export interface TraceEventAnimation extends TraceEventData {
     args: TraceEventArgs & {
-        id?: string;
-        name?: string;
-        nodeId?: number;
-        nodeName?: string;
-        state?: string;
-        compositeFailed?: number;
-        unsupportedProperties?: string[];
+        data: TraceEventArgsData & {
+            nodeName?: string;
+            nodeId?: number;
+            displayName?: string;
+            id?: string;
+            name?: string;
+            state?: string;
+            compositeFailed?: number;
+            unsupportedProperties?: string[];
+        };
     };
     name: 'Animation';
     id2?: {
         local?: string;
     };
-    ph: Phase.ASYNC_NESTABLE_START | Phase.ASYNC_NESTABLE_END;
+    ph: Phase.ASYNC_NESTABLE_START | Phase.ASYNC_NESTABLE_END | Phase.ASYNC_NESTABLE_INSTANT;
 }
 export interface TraceEventMetadata extends TraceEventData {
     ph: Phase.METADATA;
@@ -613,7 +628,9 @@ export interface LayoutShiftParsedData {
     cumulativeWeightedScoreInWindow: number;
     sessionWindowData: LayoutShiftSessionWindowData;
 }
-export interface SyntheticLayoutShift extends TraceEventLayoutShift {
+export interface SyntheticLayoutShift extends TraceEventLayoutShift, SyntheticEvent<Phase.INSTANT> {
+    name: 'LayoutShift';
+    rawSourceEvent: TraceEventLayoutShift;
     args: TraceEventArgs & {
         frame: string;
         data?: LayoutShiftData & {
@@ -709,6 +726,14 @@ export interface TraceEventResourceReceiveResponse extends TraceEventInstant {
     name: 'ResourceReceiveResponse';
     args: TraceEventArgs & {
         data: TraceEventArgsData & {
+            /**
+             * This is the protocol used to resolve the request.
+             *
+             * Note, this is not the same as URL.protocol.
+             *
+             * Example values (not exhaustive): http/0.9, http/1.0, http/1.1, http, h2, h3-Q050, data, blob
+             */
+            protocol: string;
             encodedDataLength: number;
             frame: string;
             fromCache: boolean;
@@ -831,7 +856,7 @@ export interface TraceEventPrePaint extends TraceEventComplete {
     name: 'PrePaint';
 }
 export interface TraceEventPairableAsync extends TraceEventData {
-    ph: Phase.ASYNC_NESTABLE_START | Phase.ASYNC_NESTABLE_END;
+    ph: Phase.ASYNC_NESTABLE_START | Phase.ASYNC_NESTABLE_END | Phase.ASYNC_NESTABLE_INSTANT;
     id2?: {
         local?: string;
         global?: string;
@@ -841,6 +866,9 @@ export interface TraceEventPairableAsync extends TraceEventData {
 export interface TraceEventPairableAsyncBegin extends TraceEventPairableAsync {
     ph: Phase.ASYNC_NESTABLE_START;
 }
+export interface TraceEventPairableAsyncInstant extends TraceEventPairableAsync {
+    ph: Phase.ASYNC_NESTABLE_INSTANT;
+}
 export interface TraceEventPairableAsyncEnd extends TraceEventPairableAsync {
     ph: Phase.ASYNC_NESTABLE_END;
 }
@@ -976,7 +1004,13 @@ export interface TraceEventPipelineReporter extends TraceEventData {
     };
 }
 export declare function isTraceEventPipelineReporter(event: TraceEventData): event is TraceEventPipelineReporter;
-export interface SyntheticEventPair<T extends TraceEventPairableAsync = TraceEventPairableAsync> extends TraceEventData {
+interface SyntheticEvent<Ph extends Phase = Phase> extends TraceEventData {
+    ph: Ph;
+    rawSourceEvent: TraceEventData;
+}
+export declare function isSyntheticEvent(event: TraceEventData): event is SyntheticEvent;
+export interface SyntheticEventPair<T extends TraceEventPairableAsync = TraceEventPairableAsync> extends SyntheticEvent {
+    rawSourceEvent: TraceEventData;
     name: T['name'];
     cat: T['cat'];
     id?: string;
@@ -989,6 +1023,7 @@ export interface SyntheticEventPair<T extends TraceEventPairableAsync = TraceEve
         data: {
             beginEvent: T & TraceEventPairableAsyncBegin;
             endEvent: T & TraceEventPairableAsyncEnd;
+            instantEvents?: Array<T & TraceEventPairableAsyncInstant>;
         };
     };
 }
@@ -1017,10 +1052,32 @@ export interface SyntheticTraceEntry extends TraceEventData {
 /**
  * A profile call created in the frontend from samples disguised as a
  * trace event.
+ *
+ * We store the sampleIndex, profileId and nodeId so that we can easily link
+ * back a Synthetic Trace Entry to an indivdual Sample trace event within a
+ * Profile.
+ *
+ * Because a sample contains a set of call frames representing the stack at the
+ * point in time that the sample was created, we also have to store the ID of
+ * the Node that points to the function call that this profile call represents.
  */
 export interface SyntheticProfileCall extends SyntheticTraceEntry {
     callFrame: Protocol.Runtime.CallFrame;
     nodeId: Protocol.integer;
+    sampleIndex: number;
+    profileId: ProfileID;
+}
+/**
+ * A JS Sample reflects a single sample from the V8 CPU Profile
+ */
+export interface SyntheticJSSample extends SyntheticTraceEntry {
+    name: KnownEventName.JSSample;
+    args: TraceEventArgs & {
+        data: TraceEventArgsData & {
+            stackTrace: Protocol.Runtime.CallFrame[];
+        };
+    };
+    ph: Phase.INSTANT;
 }
 /**
  * A trace event augmented synthetically in the frontend to contain
@@ -1528,6 +1585,9 @@ export interface TraceEventV8Compile extends TraceEventComplete {
         data?: {
             url?: string;
             columnNumber?: number;
+            consumedCacheSize?: number;
+            cacheRejected?: boolean;
+            cacheKind?: 'full' | 'normal';
             lineNumber?: number;
             notStreamedReason?: string;
             streamed?: boolean;
@@ -1620,7 +1680,6 @@ export declare const enum KnownEventName {
     GCCollectGarbage = "BlinkGC.AtomicPhase",
     CPPGCSweep = "CppGC.IncrementalSweep",
     ScheduleStyleRecalculation = "ScheduleStyleRecalculation",
-    RecalculateStyles = "RecalculateStyles",
     Layout = "Layout",
     UpdateLayoutTree = "UpdateLayoutTree",
     InvalidateLayout = "InvalidateLayout",
@@ -1696,6 +1755,7 @@ export declare const enum KnownEventName {
     StartProfiling = "CpuProfiler::StartProfiling",
     ProfileChunk = "ProfileChunk",
     UpdateCounters = "UpdateCounters",
+    JSSample = "JSSample",
     Animation = "Animation",
     ParseAuthorStyleSheet = "ParseAuthorStyleSheet",
     EmbedderCallback = "EmbedderCallback",
@@ -1713,4 +1773,9 @@ export declare const enum KnownEventName {
     SchedulePostMessage = "SchedulePostMessage",
     HandlePostMessage = "HandlePostMessage"
 }
+export declare const Categories: {
+    readonly Console: "blink.console";
+    readonly UserTiming: "blink.user_timing";
+    readonly Loading: "loading";
+};
 export {};

package/models/trace/types/TraceEvents.js

@@ -12,6 +12,16 @@ export function isAsyncPhase(phase) {
 export function isFlowPhase(phase) {
     return phase === "s" /* Phase.FLOW_START */ || phase === "t" /* Phase.FLOW_STEP */ || phase === "f" /* Phase.FLOW_END */;
 }
+export function objectIsTraceEventCallFrame(object) {
+    return ('functionName' in object && typeof object.functionName === 'string') &&
+        ('scriptId' in object && (typeof object.scriptId === 'string' || typeof object.scriptId === 'number')) &&
+        ('columnNumber' in object && typeof object.columnNumber === 'number') &&
+        ('lineNumber' in object && typeof object.lineNumber === 'number') &&
+        ('url' in object && typeof object.url === 'string');
+}
+export function isTraceEventRunTask(event) {
+    return event.name === "RunTask" /* KnownEventName.RunTask */;
+}
 export function isTraceEventAuctionWorkletRunningInProcess(event) {
     return event.name === 'AuctionWorkletRunningInProcess';
 }
@@ -61,6 +71,9 @@ export function isTraceEventScheduleStyleRecalculation(event) {
 export function isTraceEventPipelineReporter(event) {
     return event.name === "PipelineReporter" /* KnownEventName.PipelineReporter */;
 }
+export function isSyntheticEvent(event) {
+    return 'rawSourceEvent' in event;
+}
 export function isSyntheticInteractionEvent(event) {
     return Boolean('interactionId' in event && event.args?.data && 'beginEvent' in event.args.data && 'endEvent' in event.args.data);
 }
@@ -212,7 +225,8 @@ export function isTraceEventNavigationStart(traceEventData) {
     return traceEventData.name === 'navigationStart';
 }
 export function isTraceEventAnimation(traceEventData) {
-    return traceEventData.name === 'Animation';
+    // We've found some rare traces with an Animtation trace event from a different category: https://crbug.com/1472375#comment7
+    return traceEventData.name === 'Animation' && traceEventData.cat.includes('devtools.timeline');
 }
 export function isTraceEventLayoutShift(traceEventData) {
     return traceEventData.name === 'LayoutShift';
@@ -434,4 +448,11 @@ export function isJSInvocationEvent(event) {
     }
     return false;
 }
+// NOT AN EXHAUSTIVE LIST: just some categories we use and refer
+// to in multiple places.
+export const Categories = {
+    Console: 'blink.console',
+    UserTiming: 'blink.user_timing',
+    Loading: 'loading',
+};
 //# sourceMappingURL=TraceEvents.js.map