User Timing

非規範的と明示された節に加え、この仕様におけるすべての作成者向けガイドライン、図、例、および注記は非規範的です。この仕様のそれ以外のすべては規範的です。

この文書におけるキーワード MAY および MUST は、ここに示すようにすべて大文字で現れる場合に限り、 BCP 14 [RFC2119] [RFC8174] に記述されているように解釈されます。

一部の適合要件は、属性、メソッド、またはオブジェクトに対する要件として表現されています。そのような要件は、ユーザーエージェントに対する要件として解釈されます。

この仕様の IDL 断片は、Web IDL 仕様で説明される適合する IDL 断片に必要なものとして解釈されなければなりません。 [WEBIDL]

Performance インターフェイスおよび DOMHighResTimeStamp は [HR-TIME-2] で定義されています。 PerformanceEntry インターフェイスは [PERFORMANCE-TIMELINE-2] で定義されています。

WebIDLdictionary PerformanceMarkOptions {
    any detail;
    DOMHighResTimeStamp startTime;
};

dictionary PerformanceMeasureOptions {
    any detail;
    (DOMString or DOMHighResTimeStamp) start;
    DOMHighResTimeStamp duration;
    (DOMString or DOMHighResTimeStamp) end;
};

partial interface Performance {
    PerformanceMark mark(DOMString markName, optional PerformanceMarkOptions markOptions = {});
    undefined clearMarks(optional DOMString markName);
    PerformanceMeasure measure(DOMString measureName, optional (DOMString or PerformanceMeasureOptions) startOrMeasureOptions = {}, optional DOMString endMark);
    undefined clearMeasures(optional DOMString measureName);
};

関連付けられた名前を持つタイムスタンプ（「マーク」）を格納します。これは次の手順を実行しなければなりません。

PerformanceMark コンストラクターを実行し、 entry を新しく作成されたオブジェクトとします。
entry をキューに入れます。
entry をパフォーマンスエントリーバッファーに追加します。
entry を返します。

detail: マークに含めるメタデータ。
startTime: マーク時刻として使用するタイムスタンプ。

関連付けられた名前を持つ格納済みタイムスタンプを削除します。これは次の手順を実行しなければなりません。

markName が省略されている場合、すべての PerformanceMark オブジェクトをパフォーマンスエントリーバッファーから削除します。
そうでない場合、パフォーマンスエントリーバッファーに列挙されている PerformanceMark オブジェクトのうち、 name が markName であるものをすべて削除します。
undefined を返します。

2 つのマーク間の DOMHighResTimeStamp 期間を、関連付けられた名前（「メジャー」）とともに格納します。これは次の手順を実行しなければなりません。

startOrMeasureOptions が PerformanceMeasureOptions オブジェクトであり、start、end、duration、および detail の少なくとも 1 つが存在する場合、次のチェックを実行します。
1. endMark が指定されている場合、TypeError をスローします。
2. startOrMeasureOptions の start および end メンバーがどちらも省略されている場合、TypeError をスローします。
3. startOrMeasureOptions の start、duration、および end メンバーがすべて存在する場合、TypeError をスローします。
end time を次のように計算します。
1. endMark が指定されている場合、end time を、 endMark を渡してマークをタイムスタンプに変換するアルゴリズムを実行して返される値とします。
2. そうでなく、startOrMeasureOptions が PerformanceMeasureOptions オブジェクトであり、その end メンバーが存在する場合、 end time を、startOrMeasureOptions の end を渡してマークをタイムスタンプに変換するアルゴリズムを実行して返される値とします。
3. そうでなく、startOrMeasureOptions が PerformanceMeasureOptions オブジェクトであり、その start および duration メンバーがどちらも存在する場合:
  1. start を、start を渡してマークをタイムスタンプに変換するアルゴリズムを実行して返される値とします。
  2. duration を、duration を渡してマークをタイムスタンプに変換するアルゴリズムを実行して返される値とします。
  3. end time を start と duration の和とします。
4. そうでない場合、end time を Performance オブジェクトの now() メソッドによって返される値とします。
start time を次のように計算します。
1. startOrMeasureOptions が PerformanceMeasureOptions オブジェクトであり、その start メンバーが存在する場合、 start time を、startOrMeasureOptions の start を渡してマークをタイムスタンプに変換するアルゴリズムを実行して返される値とします。
2. そうでなく、startOrMeasureOptions が PerformanceMeasureOptions オブジェクトであり、その duration および end メンバーがどちらも存在する場合:
  1. duration を、duration を渡してマークをタイムスタンプに変換するアルゴリズムを実行して返される値とします。
  2. end を、end を渡してマークをタイムスタンプに変換するアルゴリズムを実行して返される値とします。
  3. start time を end から duration を引いた値とします。
3. そうでなく、startOrMeasureOptions が DOMString である場合、 start time を、startOrMeasureOptions を渡してマークをタイムスタンプに変換するアルゴリズムを実行して返される値とします。
4. そうでない場合、start time を 0 とします。
this の関連する Realmを使用して、新しい PerformanceMeasure オブジェクト（entry）を作成します。
entry の name 属性を measureName に設定します。
entry の entryType 属性を DOMString "measure" に設定します。
entry の startTime 属性を start time に設定します。
entry の duration 属性を start time から end time までの期間に設定します。結果の期間値は負であってもかまいません。
entry の detail 属性を次のように設定します。
1. startOrMeasureOptions が PerformanceMeasureOptions オブジェクトであり、startOrMeasureOptions の detail メンバーが存在する場合:
  1. record を、startOrMeasureOptions の detail に対して StructuredSerialize アルゴリズムを呼び出した結果とします。
  2. entry の detail を、 record および現在の Realmに対して StructuredDeserialize アルゴリズムを呼び出した結果に設定します。
2. そうでない場合、null に設定します。
entry をキューに入れます。
entry をパフォーマンスエントリーバッファーに追加します。
entry を返します。

detail: メジャーに含めるメタデータ。
start: 開始時刻として使用するタイムスタンプ、または開始マークとして使用する文字列。
duration: 開始時刻と終了時刻の間の期間。
end: 終了時刻として使用するタイムスタンプ、または終了マークとして使用する文字列。

関連付けられた名前を持つ格納済みタイムスタンプを削除します。これは次の手順を実行しなければなりません。

measureName が省略されている場合、パフォーマンスエントリーバッファー内のすべての PerformanceMeasure オブジェクトを削除します。
そうでない場合、パフォーマンスエントリーバッファーに列挙されている PerformanceMeasure オブジェクトのうち、 name が measureName であるものをすべて削除します。
undefined を返します。

PerformanceMark インターフェイスは、Performance インターフェイスの mark() メソッドによって作成されたマークも Performance Timeline に公開します。

WebIDL[Exposed=(Window,Worker)]
interface PerformanceMark : PerformanceEntry {
  constructor(DOMString markName, optional PerformanceMarkOptions markOptions = {});
  readonly attribute any detail;
};

PerformanceMark インターフェイスは、PerformanceEntry インターフェイスの次の属性を拡張します。

name 属性はマークの名前を返さなければなりません。

entryType 属性は DOMString "mark" を返さなければなりません。

startTime 属性は、マークの時刻値を持つ DOMHighResTimeStamp を返さなければなりません。

duration 属性は、値 0 の DOMHighResTimeStamp を返さなければなりません。

PerformanceMark インターフェイスには、次の追加属性があります。

detail 属性は設定された値を返さなければなりません（これは PerformanceMarkOptions 辞書からコピーされます）。

PerformanceMark コンストラクターは、次の手順を実行しなければなりません。

現在のグローバルオブジェクトが Window オブジェクトであり、markName が PerformanceTiming インターフェイスの読み取り専用属性と同じ名前を使用している場合、SyntaxError をスローします。
現在のグローバルオブジェクトの Realmを使用して、新しい PerformanceMark オブジェクト（entry）を作成します。
entry の name 属性を markName に設定します。
entry の entryType 属性を DOMString "mark" に設定します。
entry の startTime 属性を次のように設定します。
1. markOptions の startTime メンバーが存在する場合:
  1. markOptions の startTime が負の場合、TypeError をスローします。
  2. そうでない場合、entry の startTime を markOptions の startTime の値に設定します。
2. そうでない場合、Performance オブジェクトの now() メソッドによって返される値に設定します。
entry の duration 属性を 0 に設定します。
markOptions の detail が null の場合、 entry の detail を null に設定します。
そうでない場合:
1. record を、markOptions の detail に対して StructuredSerialize アルゴリズムを呼び出した結果とします。
2. entry の detail を、 record および現在の Realmに対して StructuredDeserialize アルゴリズムを呼び出した結果に設定します。

PerformanceMeasure インターフェイスは、 Performance インターフェイスの measure() メソッドによって作成されたメジャーも Performance Timeline に公開します。

WebIDL[Exposed=(Window,Worker)]
interface PerformanceMeasure : PerformanceEntry {
  readonly attribute any detail;
};

PerformanceMeasure インターフェイスは、 PerformanceEntry インターフェイスの次の属性を拡張します。

name 属性はメジャーの名前を返さなければなりません。

entryType 属性は DOMString "measure" を返さなければなりません。

startTime 属性は、メジャーの開始マークを持つ DOMHighResTimeStamp を返さなければなりません。

duration 属性は、メジャーの期間を持つ DOMHighResTimeStamp を返さなければなりません。

PerformanceMeasure インターフェイスには、次の追加属性があります。

detail 属性は設定された値を返さなければなりません（これは PerformanceMeasureOptions 辞書からコピーされます）。

注記

User Timing API を実装するユーザーエージェントは、"mark" および "measure" を supportedEntryTypes に含める必要があります。これにより、開発者は User Timing のサポートを検出できます。

DOMString または DOMHighResTimeStamp である mark が与えられたとき、マークをタイムスタンプに変換するには、次の手順を実行します。

mark が DOMString であり、 PerformanceTiming インターフェイスの読み取り専用属性と同じ名前を持つ場合、 end time を、name を mark の値に設定して名前をタイムスタンプに変換するアルゴリズムを実行して返される値とします。
そうでなく、mark が DOMString である場合、end time を、パフォーマンスエントリーバッファー内の PerformanceMark オブジェクトのうち、 name が mark であるものの最新の出現から取得した startTime 属性の値とします。一致するエントリーが見つからない場合、SyntaxError をスローします。
そうでなく、mark が DOMHighResTimeStamp である場合:
1. mark が負の場合、TypeError をスローします。
2. そうでない場合、end time を mark とします。

PerformanceTiming インターフェイスの読み取り専用属性である name が与えられたとき、名前をタイムスタンプに変換するには、次の手順を実行します。

グローバルオブジェクトが Window オブジェクトでない場合、TypeError をスローします。
name が navigationStart の場合、0 を返します。
startTime を、 PerformanceTiming インターフェイス内の navigationStart の値とします。
endTime を、 PerformanceTiming インターフェイス内の name の値とします。
endTime が 0 の場合、InvalidAccessError をスローします。
endTime から startTime を引いた結果を返します。

注記

PerformanceTiming インターフェイスは [NAVIGATION-TIMING] で定義され、現在では廃止されたものと見なされています。PerformanceTiming インターフェイスの名前の使用は後方互換性を維持するためにサポートされていますが、将来、この機能を [NAVIGATION-TIMING-2] で定義される PerformanceNavigationTiming インターフェイス（またはその他のインターフェイス）の名前へ拡張する予定はありません。

開発者には、一般的なタイミングをマークするために次の推奨マーク名を使用することが推奨されます。ユーザーエージェントは、これらの名前の使用が適切であるか、またはその説明と整合しているかを検証しません。

注記

このような推奨マーク名を追加すると、パフォーマンスツールがサイトに合わせてガイダンスを調整するのに役立ちます。これらのマーク名は、リアルユーザーモニタリングプロバイダーやユーザーエージェントが、大規模にアプリケーションのパフォーマンスに関するウェブ開発者のシグナルを収集し、サイト固有の作業を必要とせずにこの情報を開発者へ提示するのにも役立ちます。

"mark_fully_loaded"

開発者がアプリケーション内でマークした、ページが完全に読み込まれたと見なされる時刻。

注記

この例では、ページは読み込み時にチャットウィジェット、検索ボックス、ニュースフィードを非同期に初期化します。完了すると、「mark_fully_loaded」マーク名により、ラボツールおよび分析プロバイダーがタイミングを自動的に表示できるようになります。

例 3

window.addEventListener("load", (event) => {
  Promise.all([
    loadChatWidget(),
    initializeSearchAutocomplete(),
    initializeNewsfeed()]).then(() => {
      performance.mark('mark_fully_loaded');
  });
});

"mark_fully_visible"

開発者がアプリケーション内でマークした、ページがエンドユーザーに完全に表示されたと見なされる時刻。

"mark_interactive"

開発者がアプリケーション内でマークした、ページがエンドユーザーにとって操作可能と見なされる時刻。

"mark_feature_usage"

ツールおよび分析が考慮できるように、パフォーマンスへ影響する可能性がある機能の使用をマークします。detail メタデータには、その機能に関する有用な情報を含めることができ、次のものを含みます。

feature: 使用された機能の名前。
framework: 該当する場合、その機能が対象とする基盤フレームワーク。たとえば JavaScript フレームワーク、コンテンツ管理システム、または e コマースプラットフォーム。

注記

この例では、FancyJavaScriptFramework の ImageOptimizationComponent を使用して、最適なパフォーマンスになるよう画像のサイズを設定します。コードはこの機能の使用を記録し、ラボツールおよび分析が、パフォーマンス改善に役立ったかどうかを測定できるようにします。

例 4

performance.mark('mark_feature_usage', {
  'detail': {
    'feature': 'ImageOptimizationComponent',
    'framework': 'FancyJavaScriptFramework'
  }
})

[HR-TIME-2]: High Resolution Time Level 2。Ilya Grigorik。W3C。2019 年 11 月 21 日。W3C 勧告。URL: https://www.w3.org/TR/hr-time-2/
[HTML]: HTML Standard。Anne van Kesteren; Domenic Denicola; Dominic Farolino; Ian Hickson; Philip Jägenstedt; Simon Pieters。WHATWG。現行標準。URL: https://html.spec.whatwg.org/multipage/
[infra]: Infra Standard。Anne van Kesteren; Domenic Denicola。WHATWG。現行標準。URL: https://infra.spec.whatwg.org/
[NAVIGATION-TIMING]: Navigation Timing。Zhiheng Wang。 W3C。2012 年 12 月 17 日。W3C 勧告。URL: https://www.w3.org/TR/navigation-timing/
[PERFORMANCE-TIMELINE-2]: Performance Timeline。Nicolas Pena Moreno。W3C。2025 年 5 月 21 日。CRD。URL: https://www.w3.org/TR/performance-timeline/
[RFC2119]: 要件レベルを示すために RFC で使用するキーワード。S. Bradner。IETF。1997 年 3 月。現在のベストプラクティス。URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC8174]: RFC 2119 のキーワードにおける大文字と小文字の曖昧さ。B. Leiba。IETF。2017 年 5 月。現在のベストプラクティス。URL: https://www.rfc-editor.org/rfc/rfc8174
[WEBIDL]: Web IDL Standard。Edgar Chen; Timothy Gu。 WHATWG。現行標準。URL: https://webidl.spec.whatwg.org/

[ECMA-262]: ECMAScript 言語仕様。 Ecma International。URL: https://tc39.es/ecma262/multipage/
[NAVIGATION-TIMING-2]: Navigation Timing Level 2。 Yoav Weiss; Noam Rosenthal。W3C。2026 年 2 月 25 日。W3C 作業草案。URL: https://www.w3.org/TR/navigation-timing-2/
[USER-TIMING-2]: User Timing Level 2。Ilya Grigorik。 W3C。2019 年 2 月 26 日。W3C 勧告。URL: https://www.w3.org/TR/user-timing-2/

User Timing

概要

この文書のステータス

1. はじめに

2. 適合性

3. ユーザータイミング

3.1 `Performance` インターフェイスの拡張

3.1.1 `mark()` メソッド

3.1.1.1 `PerformanceMarkOptions` 辞書

3.1.2 `clearMarks()` メソッド

3.1.3 `measure()` メソッド

3.1.3.1 `PerformanceMeasureOptions` 辞書

3.1.4 `clearMeasures()` メソッド

3.2 `PerformanceMark` インターフェイス

3.2.1 `PerformanceMark` コンストラクター

3.3 `PerformanceMeasure` インターフェイス

4. 処理

4.1 `mark` を `timestamp` に変換する

4.2 `name` を `timestamp` に変換する

5. 推奨されるマーク名

6. プライバシーとセキュリティ

A. 謝辞

B. 参考文献

B.1 規範的参考文献

B.2 参考文献

User Timing

概要

この文書のステータス

1. はじめに

2. 適合性

3. ユーザータイミング

3.1 Performance インターフェイスの拡張

3.1.1 mark() メソッド

3.1.1.1 PerformanceMarkOptions 辞書

3.1.2 clearMarks() メソッド

3.1.3 measure() メソッド

3.1.3.1 PerformanceMeasureOptions 辞書

3.1.4 clearMeasures() メソッド

3.2 PerformanceMark インターフェイス

3.2.1 PerformanceMark コンストラクター

3.3 PerformanceMeasure インターフェイス

4. 処理

4.1 mark を timestamp に変換する

4.2 name を timestamp に変換する

5. 推奨されるマーク名

6. プライバシーとセキュリティ

A. 謝辞

B. 参考文献

B.1 規範的参考文献

B.2 参考文献

3.1 `Performance` インターフェイスの拡張

3.1.1 `mark()` メソッド

3.1.1.1 `PerformanceMarkOptions` 辞書

3.1.2 `clearMarks()` メソッド

3.1.3 `measure()` メソッド

3.1.3.1 `PerformanceMeasureOptions` 辞書

3.1.4 `clearMeasures()` メソッド

3.2 `PerformanceMark` インターフェイス

3.2.1 `PerformanceMark` コンストラクター

3.3 `PerformanceMeasure` インターフェイス

4.1 `mark` を `timestamp` に変換する

4.2 `name` を `timestamp` に変換する