extensibility API を使用してパフォーマンス データをカスタマイズする

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

概要

[パフォーマンス] パネルは、パフォーマンス拡張 API をサポートしています。この API を使用すると、独自のカスタムデータをパフォーマンス タイムラインに追加できます。

この API では、既存の User Timings API を利用して、測定結果とイベントをカスタム トラックとして、またはタイミング トラックとして掲載結果のタイムラインに直接挿入できます。フレームワーク、ライブラリ、カスタムの計測手法を使用する複雑なアプリケーションの開発者がパフォーマンスをより包括的に理解する場合に便利です。

主な機能

  • カスタム トラック: 専用のトラックを作成して、独自の時間ベースのデータを可視化します。
  • エントリ: イベントや測定を表すエントリをトラックに入力します。
  • ツールチップと詳細: カスタマイズ可能なツールチップと詳細ビューを使用して、エントリに豊富なコンテキストを提供します。
  • マーカー: タイムライン内の特定の時点を視覚的なマーカーでハイライト表示します。

User Timings API を使用してデータを挿入する

カスタムデータを挿入するには、performance.mark メソッドと performance.measure メソッドの detail プロパティ内に devtools オブジェクトを含めます。この devtools オブジェクトの構造によって、[パフォーマンス] パネルにデータが表示される仕組みが決まります。

  • performance.mark を使用して、タイムラインにインスタント イベントまたはタイムスタンプを記録します。特定のオペレーションの開始または終了、または所要時間のない任意のスポットの開始または終了をマークできます。detail プロパティ内に devtools オブジェクトを含めると、[Performance] パネルのタイムラインにカスタム マーカーが表示されます。

  • performance.measure を使用して、タスクまたはプロセスの所要時間を測定します。detail プロパティ内に devtools オブジェクトを含めると、[パフォーマンス] パネルのタイムラインにカスタム測定エントリが表示されます。performance.markperformance.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 an image processing task
performance.mark("Image Processing Start");

// ... later in your code

// Track entry representing the completion of image processing
// with additional details and a tooltip
performance.measure("Image Processing Complete", "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"
    }
  }
});

これにより、タイミング トラックに次のマーカーと、ツールチップのテキストおよびプロパティが表示されます。

タイミング トラックのカスタム マーカー。