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

Andrés Olivares
Andrés Olivares
X GitHub
Sofia Emelianova
Sofia Emelianova
GitHub

概览

效果面板支持效果可扩展性 API，可让您将自己的自定义数据添加到效果时间轴。

此 API 利用现有的 User Timings API，可让您将衡量结果和事件直接作为自定义轨道或在时间轨道中注入到效果时间轴中。对于使用自定义插桩的框架、库和复杂应用的开发者，这可能有助于他们更全面地了解性能。

主要特性

  • 自定义轨道：创建专用轨道，以直观呈现您自己的基于时间的数据。
  • 条目：使用表示事件或测量的条目填充轨道。
  • 提示和详情：使用可自定义的提示和详细视图为条目提供丰富的背景信息。
  • 标记：使用视觉标记突出显示时间轴中的特定时刻。

使用 User Timings API 注入数据

如需注入自定义数据，请在 performance.mark 和 performance.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
}

在时间轴中查看数据

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

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

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

代码示例

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

自定义轨道和条目

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

// 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"
    }
  }
});

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

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