performance.measure()

measure() メソッドは、マーク間、ナビゲーション開始時刻、または現在時刻の間に、ブラウザーのパフォーマンスエントリーバッファーに名前付き timestamp を作成します。

2 つのマーク間を測定するときは、それぞれ開始マーク終了マークがあります。名前付きタイムスタンプは、メジャーと呼ばれます。

measure は、Performance インターフェイスのうち、 (getEntries(), getEntriesByName(), getEntriesByType()) のいずれかを使用して取得できます。

注: この機能は Web Worker 内で利用可能です

構文

js

measure(measureName);
measure(measureName, MeasureOptions);
measure(measureName, startMark);
measure(measureName, startMark, endMark);

measureName のみが指定された場合、開始タイムスタンプはゼロに設定され、(時間を計算するために使用される)終了タイムスタンプは Performance.now() から返される値になります。

引数

measureName

DOMString で、メジャーの名前を表します。

MeasureOptions 省略可

メジャーのすべてのオプションを含むオブジェクトです(startMarkendMark はこのオブジェクト内で指定することも、独自の引数で指定することもできます)。

detail

メジャーに含める任意のメタデータです。

start

開始時刻として使用される DOMHighResTimeStamp のタイムスタンプ、または開始マークとして使用される DOMString です。 これが開始マークの名前を表す場合は、 startMark の場合と同じように定義します(すなわち、既存のマークまたは PerformanceTiming プロパティの名前でなければなりません)。

duration

開始マークと終了マークのそれぞれの時刻 (DOMHighResTimeStamp) 間の時間.

end

終了時刻として使用される DOMHighResTimeStamp のタイムスタンプ、または終了マークとして使用される DOMString です。 これが終了マークの名前を表す場合は、 endMark の場合と同じように定義します(すなわち、既存のマークまたは PerformanceTiming プロパティの名前でなければなりません)。

startMark 省略可

DOMString で、このメジャーの開始マークの名前を表します。 PerformanceTiming プロパティの名前にすることもできます。 既存の PerformanceMark または PerformanceTiming を表していない名前を指定すると SyntaxErrorDOMException が発生します。

endMark 省略可

DOMString で、このメジャーの終了マークの名前を表します。 PerformanceTiming プロパティの名前にすることもできます。 既存の PerformanceMark または PerformanceTiming を表していない名前を指定すると SyntaxErrorDOMException が発生します。

返値

生成された PerformanceMeasure のエントリーです。

返されるメジャーには、以下のプロパティ値になります。

  • entryType - "measure" が設定されます。
  • name - "name" 引数が設定されます。
  • startTime - 以下のように設定されます。
    • MeasureOptions.start で指定された場合は timestamp
    • MeasureOptions.start または startMark で指定された場合は、開始マークのタイムスタンプ
    • MeasureOptions.endMeasureOptions.duration から計算されたタイムスタンプ(MeasureOptions.start が指定されていない場合)。
    • 指定されておらず、他の値から特定することができない場合は 0。
  • duration - DOMHighResTimeStamp で、終了タイムスタンプから startTime を引いて計算されたメジャーの時間を設定します。 終了タイムスタンプは以下のいずれかになります。
    • MeasureOptions.end で指定された場合は timestamp
    • MeasureOptions.end または endMark で指定された場合は、終了マークのタイムスタンプ
    • MeasureOptions.startMeasureOptions.duration から計算されたタイムスタンプ(MeasureOptions.end が指定されていない場合)。
    • 終了マークが指定されていないか、他の値から特定することができない場合は、 Performance.now() で返される値。
  • detail - MeasureOptions で渡された値に設定されます。

例外

TypeError DOMException

start, end, duration の何れかが曖昧になる場合に発生します。

  • endMarkMeasureOptions の両方が指定された。
  • MeasureOptions が指定されたが、 start および end メンバーが指定されなかった。
  • MeasureOptionsstart, end, duration のメンバーすべてある状態(そして不整合な状態)で指定された。
SyntaxError DOMException

その名前のマークが存在しない場合に発生します。

  • endMark または MeasureOptions.end のどちらかを使用してエンドマークが指定されたが、一致する名前のパフォーマンスバッファーに PerformanceMarkがない。
  • endMark または MeasureOptions.end のどちらかを使用してエンドマークが指定されたが、 PerformanceTiming インターフェイスの読み取り専用属性に変換することができない。
  • 開始マークが startMark または MeasureOptions.start のどちらかで指定されているが、一致する名前のパフォーマンスバッファーに PerformanceMarkがない。
  • 開始マークが startMark または MeasureOptions.start のどちらかで指定されているが、 PerformanceTiming インターフェイスの読み取り専用属性に変換することができない。
DataCloneError DOMException

MeasureOptions.detailnull 以外の値であり、 HTML の "StructuredSerialize" アルゴリズムでシリアライズできない場合です。

RangeError

MeasureOptions.detailnull 以外の値であり、 HTML の "StructuredSerialize" アルゴリズムでシリアライズする際にメモリーが割り当てられなかった場合です。

次の例は、ブラウザーのパフォーマンスエントリーバッファーに measure() を使用して新しいメジャーパフォーマンスエントリーを作成する方法を示しています。

js

const markerNameA = "example-marker-a"
const markerNameB = "example-marker-b"

// いくつかのネストしたタイムアウトを実行し、それぞれに対して PerformanceMark を作成します。
performance.mark(markerNameA);
setTimeout(function() {
  performance.mark(markerNameB);
  setTimeout(function() {

    // さまざまな測定値を作成します。
    performance.measure("measure a to b", markerNameA, markerNameB);
    performance.measure("measure a to now", markerNameA);
    performance.measure("measure from navigation start to b", undefined, markerNameB);
    performance.measure("measure from the start of navigation to now");

    // すべての測定値を引き出します。
    console.log(performance.getEntriesByType("measure"));

    // 最後に、エントリ-
    を整理します。
    performance.clearMarks();
    performance.clearMeasures();
  }, 1000);
}, 1000);

仕様書

Specification
User Timing
# dom-performance-measure

ブラウザーの互換性

BCD tables only load in the browser