Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

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

Andrés Olivares

Sofia Emelianova

概览

您是否希望深入了解应用在浏览器内置指标之外的性能？现在，借助性能面板，您可以将自己的性能数据直接引入时间轴。无论您是需要直观呈现内部流程的框架作者、跟踪代码影响的库开发者，还是使用自定义插桩构建复杂应用，性能可扩展性 API 都能提供相关工具，帮助您全面了解幕后发生的情况。

通过注入自定义测量和事件，您可以在熟悉的性能面板中创建量身定制的可视化图表。您可以将框架的组件生命周期事件与标准浏览器效果指标一起查看，也可以跟踪自定义呈现引擎的执行流程，使其与浏览器的渲染流水线完美同步。

此 API 提供两种方法来实现此目的：

1. console.timeStamp API（针对 DevTools 进行了扩展）

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

**2. 用户计时 API（使用performance.mark 和 performance.measure）

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

“性能”面板中自定义轨道的外观示例。

主要优势

这两个 API 均提供以下功能：

自定义轨道：添加专用轨道和轨道组，以表示代码的独特性能方面。
条目：使用条目填充这些轨道，以清晰标记重要事件或特定操作的时长。
颜色自定义：使用颜色编码，以便一目了然地区分不同类型的事件或测量。

根据您的需求选择合适的 API：

console.timeStamp API：
- 插桩的性能影响是主要考虑因素，尤其是在生产 build 中。
- 您需要一种快速高效的方法来标记时长或事件，而无需额外的元数据。
- 您只需要在“性能”面板中直观呈现数据。
用户计时 API（performance.mark、performance.measure）：
- 当您需要为每个条目存储额外数据，并且您已在使用用户计时 API 时，请使用此 API。
- 您需要将多媒体数据（工具提示、详细属性）与性能条目相关联。
- 您想要添加视觉标记来突出显示特定时刻。
- 您不仅需要在 DevTools 中提供数据，还需要在浏览器的内部性能时间轴中提供数据，以便进行更广泛的分析或其他工具。
- 您已经熟悉或正在使用 User Timings API。

使用 `console.timeStamp` 注入数据

console.timeStamp API 经过扩展，允许在性能面板中创建自定义计时条目，且开销极小，尤其是在 DevTools 未记录跟踪记录时。

console.timeStamp(label: string, start?: string|number, end?: string|number, trackName?: string, trackGroup?: string, color?: DevToolsColor);

label：

计时条目的标签。
start（可选）：
- 如果定义为字符串：先前记录的时间戳的名称（使用 console.timeStamp(timeStampName)）。
- 如果定义为数字：相对于 Performance.timeOrigin 的时间戳（以毫秒为单位）（例如，使用 performance.now() 获取），表示计时条目的开始时间。
- 如果未定义，则使用当前时间作为开始时间。
end：
- 如果定义为字符串：先前记录的时间戳的名称。
- 如果定义为数字：相对于 Performance.timeOrigin 的时间戳（以毫秒为单位）（例如，使用 performance.now() 获取），表示计时条目的结束时间。
- 如果未定义，则使用当前时间作为结束时间。
trackName：

自定义轨道的名称。
trackGroup：

轨道组的名称。
color：

条目的颜色。

使用 User Timings API 注入数据

如需注入自定义数据，请在 detail 属性中添加 devtools 对象，该属性属于 performance.mark 和 performance.measure 方法。此 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
}

在时间轴中查看数据

如需在时间轴中查看自定义数据，请在性能面板中确保该设置已开启： Capture settings > Show custom tracks。

“性能”面板的“捕获设置”中的“显示自定义轨道”复选框。

请在此演示页上试用。开始性能记录，点击演示页上的 Add new Corgi ，然后停止记录。您会在跟踪记录中看到一个自定义轨道，其中包含带有自定义工具提示的事件、摘要标签页中的详细信息以及跟踪记录摘要中的自定义轨道组摘要。

代码示例

以下是一些示例，展示了如何使用 API 通过每种可用机制将自己的数据添加到性能面板。

`console.timeStamp` API 示例：

// Take a start timestamp
const start = performance.now();

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

// Take an end timestamp
const end = performance.now();

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

这会在性能时间轴中生成以下自定义轨道条目：

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

用户计时 API 示例：

在接下来的部分中，您将看到一些代码示例，这些示例展示了如何将以下内容添加到性能时间轴：

时间轴的自定义轨道和条目
计时轨道的标记

自定义轨道和条目

创建自定义轨道并使用条目填充这些轨道，以便在自定义轨道中直观呈现性能数据。例如：

// Mark used to represent the start of the image processing task
// The start time is defaulted to now
const imageProcessinTimeStart = performance.now();

// ... 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: imageProcessinTimeStart,
  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"
    }
  }
});

这会在计时轨道中生成以下标记，以及其工具提示文本和属性：

“Timings”轨道中的自定义标记。

利用可扩展性 API 自定义性能数据 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

概览