@paulirish/trace_engine 0.0.10 → 0.0.12

package/models/trace/handlers/handlers.js

@@ -1,4 +1,7 @@
-export * as ModelHandlers from "./ModelHandlers.js";
-export * as Threads from "./Threads.js";
-export * as Types from "./types.js";
-//# sourceMappingURL=handlers.js.map
+// Copyright 2022 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 * as ModelHandlers from './ModelHandlers.js';
+export * as Threads from './Threads.js';
+export * as Types from './types.js';
+//# sourceMappingURL=handlers.js.map

package/models/trace/handlers/handlers.js.map

@@ -1,7 +1 @@
-{
-  "version": 3,
-  "sources": ["../../../../../../../front_end/models/trace/handlers/handlers.ts"],
-  "sourcesContent": ["// Copyright 2022 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 * as ModelHandlers from './ModelHandlers.js';\nexport * as Threads from './Threads.js';\nexport * as Types from './types.js';\n"],
-  "mappings": "AAIA;AACA;AACA;",
-  "names": []
-}
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../../../../../../front_end/models/trace/handlers/handlers.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,yEAAyE;AACzE,6BAA6B;AAE7B,OAAO,KAAK,aAAa,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC","sourcesContent":["// Copyright 2022 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 * as ModelHandlers from './ModelHandlers.js';\nexport * as Threads from './Threads.js';\nexport * as Types from './types.js';\n"]}

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

@@ -0,0 +1,45 @@
+import type * as Types from './../types/types.js';
+import * as ModelHandlers from './ModelHandlers.js';
+export interface TraceEventHandler {
+    reset(): void;
+    initialize?(freshRecording?: boolean): void;
+    handleEvent(data: {}): void;
+    finalize?(): Promise<void>;
+    data(): unknown;
+    deps?(): TraceEventHandlerName[];
+    handleUserConfig?(config: Types.Configuration.Configuration): void;
+}
+export type TraceEventHandlerName = keyof typeof ModelHandlers;
+export type EnabledHandlerDataWithMeta<T extends {
+    [key: string]: TraceEventHandler;
+}> = {
+    Meta: Readonly<ReturnType<typeof ModelHandlers['Meta']['data']>>;
+} & {
+    [K in keyof T]: Readonly<ReturnType<T[K]['data']>>;
+};
+export type HandlersWithMeta<T extends {
+    [key: string]: TraceEventHandler;
+}> = {
+    Meta: typeof ModelHandlers.Meta;
+} & {
+    [K in keyof T]: T[K];
+};
+export type TraceParseData = Readonly<EnabledHandlerDataWithMeta<typeof ModelHandlers>>;
+/**
+ * Because you can run the trace engine with a subset of handlers enabled,
+ * there can be times when you need to confirm if the trace contains all
+ * handlers or not, because some parts of the engine expect to be given all
+ * the handlers.
+ */
+export declare function handlerDataHasAllHandlers(data: Readonly<EnabledHandlerDataWithMeta<{}>>): data is TraceParseData;
+type DeepWriteable<T> = {
+    -readonly [P in keyof T]: DeepWriteable<T[P]>;
+};
+export type TraceParseDataMutable = DeepWriteable<TraceParseData>;
+export type Handlers = typeof ModelHandlers;
+export declare const enum HandlerState {
+    UNINITIALIZED = 1,
+    INITIALIZED = 2,
+    FINALIZED = 3
+}
+export {};

package/models/trace/handlers/types.js

@@ -1,18 +1,18 @@
-import * as ModelHandlers from "./ModelHandlers.js";
+import * as ModelHandlers from './ModelHandlers.js';
+/**
+ * Because you can run the trace engine with a subset of handlers enabled,
+ * there can be times when you need to confirm if the trace contains all
+ * handlers or not, because some parts of the engine expect to be given all
+ * the handlers.
+ */
 export function handlerDataHasAllHandlers(data) {
-  let isMissingHandler = false;
-  for (const handlerName of Object.keys(ModelHandlers)) {
-    if (handlerName in data === false) {
-      isMissingHandler = true;
-      break;
+    let isMissingHandler = false;
+    for (const handlerName of Object.keys(ModelHandlers)) {
+        if (handlerName in data === false) {
+            isMissingHandler = true;
+            break;
+        }
     }
-  }
-  return !isMissingHandler;
+    return !isMissingHandler;
 }
-export var HandlerState = /* @__PURE__ */ ((HandlerState2) => {
-  HandlerState2[HandlerState2["UNINITIALIZED"] = 1] = "UNINITIALIZED";
-  HandlerState2[HandlerState2["INITIALIZED"] = 2] = "INITIALIZED";
-  HandlerState2[HandlerState2["FINALIZED"] = 3] = "FINALIZED";
-  return HandlerState2;
-})(HandlerState || {});
-//# sourceMappingURL=types.js.map
+//# sourceMappingURL=types.js.map

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

@@ -1,7 +1 @@
-{
-  "version": 3,
-  "sources": ["../../../../../../../front_end/models/trace/handlers/types.ts"],
-  "sourcesContent": ["\n// Copyright 2022 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.\nimport type * as Types from './../types/types.js';\nimport * as ModelHandlers from './ModelHandlers.js';\n\nexport interface TraceEventHandler {\n  reset(): void;\n  initialize?(freshRecording?: boolean): void;\n  handleEvent(data: {}): void;\n  finalize?(): Promise<void>;\n  data(): unknown;\n  deps?(): TraceEventHandlerName[];\n  handleUserConfig?(config: Types.Configuration.Configuration): void;\n}\nexport type TraceEventHandlerName = keyof typeof ModelHandlers;\n\n// This type maps TraceEventHandler names to the return type of their data\n// function. So, for example, if we are given an object with a key of 'foo'\n// and a value which is a TraceHandler containing a data() function that\n// returns a string, this type will be { foo: string }.\n//\n// This allows us to model the behavior of the TraceProcessor in the model,\n// which takes an object with TraceEventHandlers as part of its config, and\n// which ultimately returns an object keyed off the names of the\n// TraceEventHandlers, and with values that are derived from each\n// TraceEventHandler's data function.\n//\n// So, concretely, we provide a TraceEventHandler for calculating the #time\n// bounds of a trace called TraceBounds, whose data() function returns a\n// TraceWindow. The HandlerData, therefore, would determine that the\n// TraceProcessor would contain a key called 'TraceBounds' whose value is\n// a TraceWindow.\nexport type EnabledHandlerDataWithMeta<T extends {[key: string]: TraceEventHandler}> = {\n  // We allow the user to configure which handlers are created by passing them\n  // in when constructing a model instance. However, we then ensure that the\n  // Meta handler is added to that, as the Model relies on some of the data\n  // from the Meta handler when creating the file. Therefore, this type\n  // explicitly defines that the Meta data is present, before then extending it\n  // with the index type to represent all the other handlers.\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  Meta: Readonly<ReturnType<typeof ModelHandlers['Meta']['data']>>,\n}&{\n  // For every key in the object, look up the TraceEventHandler's data function\n  // and use its return type as the value for the object.\n  [K in keyof T]: Readonly<ReturnType<T[K]['data']>>;\n};\n\nexport type HandlersWithMeta<T extends {[key: string]: TraceEventHandler}> = {\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  Meta: typeof ModelHandlers.Meta,\n}&{\n  [K in keyof T]: T[K];\n};\n\n// Represents the final parsed data from all of the handlers. Note that because\n// we are currently in the middle of the migration of data engines, not all the\n// handlers are enabled. Therefore for now you should use the type defined in\n// models/trace/handlers/Migration.ts, `PartialTraceData`, which\n// represents the final parsed data for only the enabled handlers.\nexport type TraceParseData = Readonly<EnabledHandlerDataWithMeta<typeof ModelHandlers>>;\n\n/**\n * Because you can run the trace engine with a subset of handlers enabled,\n * there can be times when you need to confirm if the trace contains all\n * handlers or not, because some parts of the engine expect to be given all\n * the handlers.\n */\nexport function handlerDataHasAllHandlers(data: Readonly<EnabledHandlerDataWithMeta<{}>>): data is TraceParseData {\n  let isMissingHandler = false;\n  for (const handlerName of Object.keys(ModelHandlers)) {\n    if (handlerName in data === false) {\n      isMissingHandler = true;\n      break;\n    }\n  }\n  return !isMissingHandler;\n}\n\ntype DeepWriteable<T> = {\n  -readonly[P in keyof T]: DeepWriteable<T[P]>\n};\nexport type TraceParseDataMutable = DeepWriteable<TraceParseData>;\n\nexport type Handlers = typeof ModelHandlers;\n\nexport const enum HandlerState {\n  UNINITIALIZED = 1,\n  INITIALIZED = 2,\n  FINALIZED = 3,\n}\n"],
-  "mappings": "AAKA;AAgEO,0CAAmC,MAAwE;AAChH,MAAI,mBAAmB;AACvB,aAAW,eAAe,OAAO,KAAK,gBAAgB;AACpD,QAAI,eAAe,SAAS,OAAO;AACjC,yBAAmB;AACnB;AAAA;AAAA;AAGJ,SAAO,CAAC;AAAA;AAUH,WAAW,eAAX,kBAAW,kBAAX;AACL,iDAAgB,KAAhB;AACA,+CAAc,KAAd;AACA,6CAAY,KAAZ;AAHgB;AAAA;",
-  "names": []
-}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../../front_end/models/trace/handlers/types.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,aAAa,MAAM,oBAAoB,CAAC;AA0DpD;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAA8C;IACtF,IAAI,gBAAgB,GAAG,KAAK,CAAC;IAC7B,KAAK,MAAM,WAAW,IAAI,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE;QACpD,IAAI,WAAW,IAAI,IAAI,KAAK,KAAK,EAAE;YACjC,gBAAgB,GAAG,IAAI,CAAC;YACxB,MAAM;SACP;KACF;IACD,OAAO,CAAC,gBAAgB,CAAC;AAC3B,CAAC","sourcesContent":["\n// Copyright 2022 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.\nimport type * as Types from './../types/types.js';\nimport * as ModelHandlers from './ModelHandlers.js';\n\nexport interface TraceEventHandler {\n  reset(): void;\n  initialize?(freshRecording?: boolean): void;\n  handleEvent(data: {}): void;\n  finalize?(): Promise<void>;\n  data(): unknown;\n  deps?(): TraceEventHandlerName[];\n  handleUserConfig?(config: Types.Configuration.Configuration): void;\n}\nexport type TraceEventHandlerName = keyof typeof ModelHandlers;\n\n// This type maps TraceEventHandler names to the return type of their data\n// function. So, for example, if we are given an object with a key of 'foo'\n// and a value which is a TraceHandler containing a data() function that\n// returns a string, this type will be { foo: string }.\n//\n// This allows us to model the behavior of the TraceProcessor in the model,\n// which takes an object with TraceEventHandlers as part of its config, and\n// which ultimately returns an object keyed off the names of the\n// TraceEventHandlers, and with values that are derived from each\n// TraceEventHandler's data function.\n//\n// So, concretely, we provide a TraceEventHandler for calculating the #time\n// bounds of a trace called TraceBounds, whose data() function returns a\n// TraceWindow. The HandlerData, therefore, would determine that the\n// TraceProcessor would contain a key called 'TraceBounds' whose value is\n// a TraceWindow.\nexport type EnabledHandlerDataWithMeta<T extends {[key: string]: TraceEventHandler}> = {\n  // We allow the user to configure which handlers are created by passing them\n  // in when constructing a model instance. However, we then ensure that the\n  // Meta handler is added to that, as the Model relies on some of the data\n  // from the Meta handler when creating the file. Therefore, this type\n  // explicitly defines that the Meta data is present, before then extending it\n  // with the index type to represent all the other handlers.\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  Meta: Readonly<ReturnType<typeof ModelHandlers['Meta']['data']>>,\n}&{\n  // For every key in the object, look up the TraceEventHandler's data function\n  // and use its return type as the value for the object.\n  [K in keyof T]: Readonly<ReturnType<T[K]['data']>>;\n};\n\nexport type HandlersWithMeta<T extends {[key: string]: TraceEventHandler}> = {\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  Meta: typeof ModelHandlers.Meta,\n}&{\n  [K in keyof T]: T[K];\n};\n\n// Represents the final parsed data from all of the handlers. Note that because\n// we are currently in the middle of the migration of data engines, not all the\n// handlers are enabled. Therefore for now you should use the type defined in\n// models/trace/handlers/Migration.ts, `PartialTraceData`, which\n// represents the final parsed data for only the enabled handlers.\nexport type TraceParseData = Readonly<EnabledHandlerDataWithMeta<typeof ModelHandlers>>;\n\n/**\n * Because you can run the trace engine with a subset of handlers enabled,\n * there can be times when you need to confirm if the trace contains all\n * handlers or not, because some parts of the engine expect to be given all\n * the handlers.\n */\nexport function handlerDataHasAllHandlers(data: Readonly<EnabledHandlerDataWithMeta<{}>>): data is TraceParseData {\n  let isMissingHandler = false;\n  for (const handlerName of Object.keys(ModelHandlers)) {\n    if (handlerName in data === false) {\n      isMissingHandler = true;\n      break;\n    }\n  }\n  return !isMissingHandler;\n}\n\ntype DeepWriteable<T> = {\n  -readonly[P in keyof T]: DeepWriteable<T[P]>\n};\nexport type TraceParseDataMutable = DeepWriteable<TraceParseData>;\n\nexport type Handlers = typeof ModelHandlers;\n\nexport const enum HandlerState {\n  UNINITIALIZED = 1,\n  INITIALIZED = 2,\n  FINALIZED = 3,\n}\n"]}

package/models/trace/helpers/SamplesIntegrator.d.ts

@@ -0,0 +1,49 @@
+import type * as Protocol from '../../../generated/protocol.js';
+import type * as CPUProfile from '../../cpu_profile/cpu_profile.js';
+import * as Types from '../types/types.js';
+/**
+ * This is a helper that integrates CPU profiling data coming in the
+ * shape of samples, with trace events. Samples indicate what the JS
+ * stack trace looked at a given point in time, but they don't have
+ * duration. The SamplesIntegrator task is to make an approximation
+ * of what the duration of each JS call was, given the sample data and
+ * given the trace events profiled during that time. At the end of its
+ * execution, the SamplesIntegrator returns an array of ProfileCalls
+ * (under SamplesIntegrator::buildProfileCalls()), which
+ * represent JS calls, with a call frame and duration. These calls have
+ * the shape of a complete trace events and can be treated as flame
+ * chart entries in the timeline.
+ *
+ * The approach to build the profile calls consists in tracking the
+ * current stack as the following events happen (in order):
+ * 1. A sample was done.
+ * 2. A trace event started.
+ * 3. A trace event ended.
+ * Depending on the event and on the data that's coming with it the
+ * stack is updated by adding or removing JS calls to it and updating
+ * the duration of the calls in the tracking stack.
+ *
+ * note: Although this approach has been implemented since long ago, and
+ * is relatively efficent (adds a complexity over the trace parsing of
+ * O(n) where n is the number of samples) it has proven to be faulty.
+ * It might be worthwhile experimenting with improvements or with a
+ * completely different approach. Improving the approach is tracked in
+ * crbug.com/1417439
+ */
+export declare class SamplesIntegrator {
+    #private;
+    constructor(profileModel: CPUProfile.CPUProfileDataModel.CPUProfileDataModel, pid: Types.TraceEvents.ProcessID, tid: Types.TraceEvents.ThreadID, configuration?: Types.Configuration.Configuration);
+    buildProfileCalls(traceEvents: Types.TraceEvents.TraceEventData[]): Types.TraceEvents.SyntheticProfileCall[];
+    /**
+     * Builds the initial calls with no duration from samples. Their
+     * purpose is to be merged with the trace event array being parsed so
+     * that they can be traversed in order with them and their duration
+     * can be updated as the SampleIntegrator callbacks are invoked.
+     */
+    callsFromProfileSamples(): Types.TraceEvents.SyntheticProfileCall[];
+    static framesAreEqual(frame1: Protocol.Runtime.CallFrame, frame2: Protocol.Runtime.CallFrame): boolean;
+    static showNativeName(name: string, runtimeCallStatsEnabled: boolean): boolean;
+    static nativeGroup(nativeName: string): 'Parse' | 'Compile' | null;
+    static isNativeRuntimeFrame(frame: Protocol.Runtime.CallFrame): boolean;
+    static filterStackFrames(stack: Types.TraceEvents.SyntheticProfileCall[], engineConfig: Types.Configuration.Configuration): void;
+}