利用可扩展性 API 自定义性能数据

Andrés Olivares
Andrés Olivares
Sofia Emelianova
Sofia Emelianova

概览

效果面板支持效果可扩展性 API,可将自定义数据添加到“效果”时间轴。这样,您就可以将测量结果和事件直接作为自定义轨道或时间轨道注入到性能时间轴中。对于使用自定义插桩的框架、库和复杂应用的开发者,这可能有助于他们更全面地了解性能。

此 API 提供两种不同的机制:

1. User Timings API(使用 performance.markperformance.measure

此 API 利用现有的 User Timings API。它还会向浏览器的内部性能时间轴添加条目,以便进行进一步分析并与其他性能工具集成。

2. console.timeStamp API(针对 DevTools 扩展)

此 API 提供了一种高性能方法,可用于插桩应用并将时间数据专门显示在 DevTools 的性能面板中。该插桩工具旨在最大限度地减少运行时开销,因此适用于插桩热路径和生产 build。它不会向浏览器的内部性能时间轴添加条目。

主要特性

这两个 API 都提供以下功能:

  • 自定义轨道:向自定义轨道和轨道组添加条目。
  • 条目:使用表示事件或测量的条目填充轨道。
  • 颜色自定义:为条目添加颜色代码,以便进行视觉区分。

主要区别以及何时使用每种 API

  • User Timings API (performance.markperformance.measure)
    • 性能面板浏览器的内部性能时间轴添加条目。
    • 允许使用丰富的数据,包括提示和详细属性。
    • 允许添加标记:使用视觉标记突出显示时间轴中的特定时刻。
    • 适用于详细性能分析,以及需要与其他性能工具集成的情况。
    • 当您需要为每个条目存储额外数据且已经在使用 User Timings API 时,请使用此方法。
  • console.timeStamp API
    • 效果面板添加条目。
    • 性能显著提升,尤其是在生产环境中。
    • 非常适合插桩热路径和对性能至关重要的代码进行插桩。
    • 无法添加提示或属性等额外数据。
    • 当性能开销是主要问题且您需要快速插桩代码时,请使用此方法。

使用 User Timings API 注入数据

如需注入自定义数据,请在 performance.markperformance.measure 方法的 detail 属性中添加 devtools 对象。此 devtools 对象的结构决定了数据在效果面板中的显示方式。

  • 使用 performance.mark 在时间轴中记录即时事件或时间戳。您可以标记特定操作的开始或结束时间,或标记没有时长的任何感兴趣的时间点。当您在 detail 属性中添加 devtools 对象时,效果面板会在时间轨道中显示自定义标记。

  • 使用 performance.measure 测量任务或进程的时长。当您在 detail 属性中添加 devtools 对象时,效果面板会在自定义轨道的时间轴中显示自定义衡量条目。如果您使用 performance.mark 作为参考点来创建 performance.measure,则无需在 performance.mark 调用中添加 devtools 对象。

devtools 对象

以下类型定义了不同扩展功能的 devtools 对象的结构:

type DevToolsColor =
  "primary" | "primary-light" | "primary-dark" |
  "secondary" | "secondary-light" | "secondary-dark" |
  "tertiary" | "tertiary-light" | "tertiary-dark" |
  "error";

interface ExtensionTrackEntryPayload {
  dataType?: "track-entry"; // Defaults to "track-entry"
  color?: DevToolsColor;    // Defaults to "primary"
  track: string;            // Required: Name of the custom track
  trackGroup?: string;      // Optional: Group for organizing tracks
  properties?: [string, string][]; // Key-value pairs for detailed view
  tooltipText?: string;     // Short description for tooltip
}

interface ExtensionMarkerPayload {
  dataType: "marker";       // Required: Identifies as a marker
  color?: DevToolsColor;    // Defaults to "primary"
  properties?: [string, string][]; // Key-value pairs for detailed view
  tooltipText?: string;     // Short description for tooltip
}

使用 console.timeStamp 注入数据

扩展了 console.timeStamp API,以便在性能面板中创建自定义时间记录条目,同时尽可能减少开销。

console.timeStamp(label: string, start?: string, end?: string, trackName?: string, trackGroup?: string, color?: DevToolsColor);
  • label:时间条目对应的标签。
  • start:之前记录的时间戳(使用 console.timeStamp(timeStampName))的名称。如果未定义,则使用当前时间。
  • end:之前记录的时间戳的名称。如果未定义,则使用当前时间。
  • trackName:自定义轨道的名称。
  • trackGroup:轨道组的名称。
  • color:条目的颜色。

在时间轴中查看数据

如需在时间轴中查看自定义数据,请在效果面板中,依次开启 捕获设置 > 扩展程序数据

性能面板的“捕获设置”中的“扩展程序数据”复选框。

您可以在此演示页面上试用此功能。开启扩展程序数据,开始录制效果数据,点击演示页面上的添加新柯基犬,然后停止录制。您会在轨迹中看到一个自定义轨道,其中包含带有自定义提示和详细信息的事件(详见摘要标签页)。

代码示例

以下示例展示了如何使用 API 通过每种可用机制将您自己的数据添加到效果面板。

User Timings API 示例:

在下一部分中,查看代码示例,了解如何将以下内容添加到性能时间轴:

自定义轨道和条目

创建自定义轨道并为其填充条目,以便在自定义轨道中直观呈现效果数据。例如:

// Mark used to represent the start of the image processing task
// The start time is defaulted to now
performance.mark("Image Processing Start");

// ... later in your code

// Track entry representing the completion of image processing
// with additional details and a tooltip
// The start time is a marker from earlier
// The end time is defaulted to now
performance.measure("Image Processing Complete", {
  start: "Image Processing Start",
  detail: {
    devtools: {
      dataType: "track-entry",
      track: "Image Processing Tasks",
      trackGroup: "My Tracks", // Group related tracks together
      color: "tertiary-dark",
      properties: [
        ["Filter Type", "Gaussian Blur"],
        ["Resize Dimensions", "500x300"]
      ],
      tooltipText: "Image processed successfully"
    }
  }
});

这会在效果时间轴中生成以下自定义轨道条目及其提示文本和属性:

效果时间轴中的自定义轨道。

标记

使用跨所有轨道的自定义标记,直观地突出显示时间轴中的特定感兴趣的内容。例如:

// Marker indicating when the processed image was uploaded
performance.mark("Image Upload", {
  detail: {
    devtools: {
      dataType: "marker",
      color: "secondary",
      properties: [
        ["Image Size", "2.5MB"],
        ["Upload Destination", "Cloud Storage"]
      ],
      tooltipText: "Processed image uploaded"
    }
  }
});

这会在时间轨道中生成以下标记及其提示文字和属性:

时间轨道中的自定义标记。

console.timeStamp API 示例:

// Record a start timestamp
console.timeStamp("start");

// Measure duration from start to now
console.timeStamp("measure 1", "start", undefined, "My Track", "My Group", "primary-light");

// Record an end timestamp
console.timeStamp("end");

// Measure duration from start to end
console.timeStamp("measure 2", "start", "end", "My Track", "My Group", "secondary-dark");

这会在效果时间轴中生成以下自定义轨道条目:

使用 console.timeStamp API 添加自定义条目的自定义轨道。