Performance: measure() メソッド
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2015.
measure()
メソッドは、 2 つのマーク間の時間を表す名前付き PerformanceMeasure
オブジェクトを、ブラウザーのパフォーマンスタイムラインに作成します。
2 つのマーク間を測定するときは、それぞれ開始マークと終了マークがあります。名前付きタイムスタンプは、メジャーと呼ばれます。
構文
measure(measureName)
measure(measureName, startMark)
measure(measureName, startMark, endMark)
measure(measureName, measureOptions)
measure(measureName, measureOptions, endMark)
measureName
のみが指定された場合、開始タイムスタンプはゼロに設定され、(時間を計算するために使用される)終了タイムスタンプは Performance.now()
から返される値になります。
文字列を使用して PerformanceMark
オブジェクトを開始マークと終了マークとして識別することができます。
endMark
のみ指定する場合、空の measureOptions
オブジェクトを提供して performance.measure("myMeasure", {}, "myEndMarker")
のようにする必要があります。
引数
measureName
-
文字列で、メジャーの名前を表します。
measureOptions
省略可-
メジャーのすべてのオプションを含むオブジェクトです。
detail
省略可-
マークに含める任意のメタデータです。既定値は
null
です。構造化クローン可能でなければなりません。 start
省略可-
開始時刻として使用される
DOMHighResTimeStamp
のタイムスタンプ、または開始マークに使用される文字列です。これが
PerformanceMark
に名前を付ける文字列である場合、startMark
と同じ方法で定義されます。 duration
省略可-
開始と終了のマーク時刻間の時間(ミリ秒単位)。省略した場合は既定値が
performance.now()
となり、コンテキストが作成されてから経過した時刻となります。指定された場合はstart
とend
のどちらかを指定する必要がありますが、両方を指定することはできません。 end
省略可-
終了時刻として使用される
DOMHighResTimeStamp
のタイムスタンプ、または終了時刻のPerformanceMark
に名前を付ける文字列です。 これがPerformanceMark
に名前を付ける文字列である場合、endMark
と同じように定義します。
startMark
省略可-
パフォーマンスタイムラインの
PerformanceMark
に名前を付ける文字列です。このマークのPerformanceEntry.startTime
プロパティがメジャーの計算に使用されます。 endMark
省略可-
パフォーマンスタイムラインの
PerformanceMark
に名前を付ける文字列です。このマークのPerformanceEntry.startTime
プロパティがメジャーの計算に使用されます。 この引数を渡したい場合は、startMark
または空のmeasureOptions
オブジェクトも渡す必要があります。
返値
生成された PerformanceMeasure
の項目です。
返されるメジャーには、以下のプロパティ値になります。
-
entryType
- "measure
" が設定されます。 -
name
- "name
" 引数が設定されます。 -
startTime
- 以下のように設定されます。 -
duration
-DOMHighResTimeStamp
で、終了タイムスタンプからstartTime
を引いて計算されたメジャーの時間を設定します。終了タイムスタンプは以下のいずれかになります。
measureOptions.end
で指定された場合はtimestamp
。measureOptions.end
またはendMark
で指定された場合は、終了マークのタイムスタンプ。measureOptions.start
とmeasureOptions.duration
から計算されたタイムスタンプ(measureOptions.end
が指定されていない場合)。- 終了マークが指定されていないか、他の値から特定することができない場合は、
Performance.now()
で返される値。
-
detail
-measureOptions
で渡された値に設定されます。
例外
TypeError
-
start, end, duration のいずれかが曖昧になる場合に発生します。
endMark
とmeasureOptions
の両方が指定された。measureOptions
が指定されたが、start
およびend
メンバーが指定されなかった。measureOptions
がstart
,end
,duration
のメンバーすべてある状態(そして不整合な状態)で指定された。
SyntaxError
DOMException
-
その名前のマークが存在しない場合に発生します。
endMark
またはmeasureOptions.end
のどちらかを使用してエンドマークが指定されたが、一致する名前のパフォーマンスバッファーにPerformanceMark
がない。endMark
またはmeasureOptions.end
のどちらかを使用してエンドマークが指定されたが、PerformanceTiming
インターフェイスの読み取り専用属性に変換することができない。- 開始マークが
startMark
またはmeasureOptions.start
のどちらかで指定されているが、一致する名前のパフォーマンスバッファーにPerformanceMark
がない。 - 開始マークが
startMark
またはmeasureOptions.start
のどちらかで指定されているが、PerformanceTiming
インターフェイスの読み取り専用属性に変換することができない。
DataCloneError
DOMException
-
measureOptions.detail
がnull
以外の値であり、 HTML の "StructuredSerialize" アルゴリズムでシリアライズできない場合です。 RangeError
-
measureOptions.detail
がnull
以外の値であり、 HTML の "StructuredSerialize" アルゴリズムでシリアライズする際にメモリーが割り当てられなかった場合です。
例
名前付きマーカー間の時間の測定
自分自身で 2 つのマーカー "login-started"
と "login-finished"
を指定した場合、次の例に示すように "login-duration"
という名前の時間を作成することができます。返された PerformanceMeasure
オブジェクトは duration
プロパティを提供し、2 つのマーカー間の経過時間を指示します。
const loginMeasure = performance.measure(
"login-duration",
"login-started",
"login-finished",
);
console.log(loginMeasure.duration);
独自の開始と終了の時刻で時間を測定
より高度な計測を行うには、 measureOptions
引数を渡すことができます。例えば、開始時刻には click
イベント の event.timeStamp
プロパティを使用することができます。
performance.measure("login-click", {
start: myClickEvent.timeStamp,
end: myMarker.startTime,
});
メジャーの追加の詳細を提供
details
プロパティを使用することで、任意の型の追加情報を提供することができます。例えば、どの HTML 要素がクリックされたかを記録したいかもしれません。
performance.measure("login-click", {
detail: { htmlElement: myElement.id },
start: myClickEvent.timeStamp,
end: myMarker.startTime,
});
仕様書
Specification |
---|
User Timing # dom-performance-measure |
ブラウザーの互換性
BCD tables only load in the browser