このページは Cloud Translation API によって翻訳されました。

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

Andrés Olivares

Sofia Emelianova

概要

[パフォーマンス] パネルはパフォーマンス拡張 API をサポートしており、パフォーマンスタイムラインにカスタムデータを追加できます。これにより、測定値とイベントをカスタムトラックとして、または [タイミング] トラックに直接パフォーマンスタイムラインに挿入できます。これは、カスタム計測機能を使用するフレームワーク、ライブラリ、複雑なアプリケーションのデベロッパーが、パフォーマンスをより包括的に把握するために役立ちます。

この API には、次の 2 つの異なるメカニズムがあります。

1. User Timings API（performance.mark と performance.measure を使用）

この API は、既存の User Timings API を利用します。また、ブラウザの内部パフォーマンスタイムラインにエントリが追加されるため、詳細な分析や他のパフォーマンスツールとの統合が可能になります。

2. console.timeStamp API（DevTools 用に拡張）

この API は、アプリケーションを計測し、タイミングデータを DevTools の [パフォーマンス] パネルにのみ表示するための高性能なメソッドを提供します。ランタイムオーバーヘッドを最小限に抑えるように設計されているため、ホットパスと本番環境ビルドの計測に適しています。ブラウザの内部パフォーマンスタイムラインにエントリが追加されることはありません。

主な機能

どちらの API も、次の機能を提供します。

カスタムトラック: カスタムトラックとトラックグループにエントリを追加します。
エントリ: イベントや測定値を表すエントリをトラックに入力します。
色のカスタマイズ: エントリを色分けして視覚的に区別します。

主な違いと各 API を使用するタイミング:

User Timings API（performance.mark、performance.measure）:
- [パフォーマンス] パネルとブラウザの内部パフォーマンスタイムラインの両方にエントリが追加されます。
- ツールチップや詳細なプロパティなど、豊富なデータを使用できます。
- マーカーを追加可能: タイムライン内の特定の瞬間を視覚的なマーカーでハイライト表示できます。
- 詳細なパフォーマンス分析や、他のパフォーマンスツールとの統合が必要な場合に適しています。
- 各エントリに追加データを保存する必要がある場合や、User Timings API をすでに使用している場合に使用します。
console.timeStamp 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
}

`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 で追加されたカスタムエントリを含むカスタムトラック。

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

概要