使用可擴充的 API 自訂效能資料

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

總覽

「成效」面板支援效能擴展 API，可讓您在成效時間軸中加入自訂資料。

這個 API 運用現有的 User Timings API，讓您以自訂測試群組或 Timings 測試群組，直接在成效時間軸中插入評估資料和事件。對於具有自訂檢測的架構、程式庫和複雜應用程式的開發人員，這項功能可能相當實用，有助於更全面地瞭解效能。

主要功能與特色

  • 自訂測試群組：建立專屬測試群組，以視覺化方式呈現時間資料。
  • 項目：在曲目上填入代表事件或測量結果的項目。
  • 工具和詳細資料：運用可自訂的工具提示和詳細檢視畫面，為項目提供豐富的背景資訊。
  • 標記：使用視覺標記醒目顯示時間軸中的特定時刻。

使用 User Timings API 插入資料

如要插入自訂資料，請在 performance.mark 和 performance.measure 方法的 detail 屬性中加入 devtools 物件。這個 devtools 物件的結構會決定資料在「Performance」面板中的顯示方式。

  • 使用 performance.mark 記錄時間軸中的即時事件或時間戳記。您可以標示特定作業的開始或結束位置，也可以標記沒有時間長度的搜尋點。在 detail 屬性中加入 devtools 物件後，「Performance」面板會在「Timings」軌跡中顯示自訂標記。

  • 使用 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
}

在時間軸上查看資料

如要在時間軸中查看自訂資料，請在「成效」面板中依序開啟「設定」「擷取設定」>「擴充資料」。

「成效」面板「擷取設定」中的「擴充功能資料」核取方塊。

歡迎前往這個示範頁面試用。開啟「擴充功能資料」，開始記錄表演，然後在示範頁面上點選「新增 Corgi」，然後停止記錄。追蹤記錄中會顯示自訂測試群組，其中包含含有自訂工具提示的事件，以及「摘要」分頁中的詳細資料。

程式碼範例

請參考後續各節中的程式碼範例，瞭解如何在成效時間軸中加入以下內容：

自訂測試群組與項目

建立自訂測試群組並填入項目，在自訂測試群組中以視覺化方式呈現成效資料。例如：

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

這會在 Timings 軌中產生下列標記，以及其工具提示文字和屬性：

Timings 軌跡中的自訂標記。