User Timing レベル2

W3C 勧告

このバージョン：
https://www.w3.org/TR/2019/REC-user-timing-2-20190226/
最新公開バージョン：
https://www.w3.org/TR/user-timing-2/
User Timingの最新版：
https://www.w3.org/TR/user-timing/
最新編集者草稿：
https://w3c.github.io/user-timing/
以前のバージョン：
https://www.w3.org/TR/2019/PR-user-timing-2-20190110/
テストスイート：
https://wpt.fyi/results/user-timing
実装報告：
https://wpt.fyi/results/user-timing
編集者：
(Google)
以前の編集者：
Jatinder Mann (Microsoft Corp.) (2014年2月まで)
Zhiheng Wang (Google Inc.) (2013年7月まで)
Anderson Quach (Microsoft Corp.) (2011年3月まで)
参加方法：
GitHub w3c/user-timing
バグ報告
コミット履歴
プルリクエスト
実装：
Can I use User Timing?

公開後に報告されたエラーや問題については、 正誤表をご確認ください。

また、 翻訳も参照してください。

Copyright © 2019 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.

概要

この仕様は、ウェブ開発者が高精度タイムスタンプへのアクセスによってアプリケーションのパフォーマンスを計測できるようにするインターフェイスを定義します。

この文書のステータス

このセクションは公開時点の文書のステータスを示します。他の文書が本書を置き換える場合があります。現行のW3C出版物と本技術レポートの最新改訂は、W3C技術レポート索引 https://www.w3.org/TR/ でご確認いただけます。

User Timing レベル2は、[USER-TIMING] の第1版を置き換えることを意図しており、以下を含みます：

本書は Webパフォーマンス作業グループ によって 勧告として公開されました。

この仕様の議論には GitHub Issues の利用が推奨されています。 または、メーリングリストにコメントを送ることもできます。 送信先は public-web-perf@w3.org (アーカイブ) 件名の最初に [UserTiming] を記載してください 。

作業グループの 実装報告もご覧ください。

本書は W3C 会員、ソフトウェア開発者、他の W3C グループおよび関係者によってレビューされ、ディレクターにより W3C 勧告として承認されました。これは安定した文書であり、参考資料や他の文書から引用することができます。W3C の勧告化は仕様の周知と普及促進を目的としており、Webの機能性と相互運用性を高めます。

本書は W3C 特許ポリシー の下で運営されるグループにより作成されています。 W3Cは 関連する特許開示の公開リスト を管理しています。 このページには特許開示の方法も記載されています。ある人が特許の存在を知り、その内容が 必須クレーム を含むと考える場合は、 W3C特許ポリシー第6節 に従って情報を開示する必要があります。

この文書は 2018年2月1日 W3Cプロセス文書に準拠します。

1. はじめに

このセクションは規範的ではありません。

ウェブ開発者は、自身のアプリケーションのパフォーマンス特性を評価・理解する機能を必要としています。JavaScript [ECMA-262] はアプリケーションのレイテンシを計測する仕組み（Date.now()メソッドから現在のタイムスタンプを取得）を提供しますが、タイムスタンプの精度はユーザーエージェントによって異なります。

この文書では、PerformanceMark および PerformanceMeasure インターフェイス、ならびに Performance インターフェイスへの拡張を定義し、開発者がアプリケーションのパフォーマンス特性をより良く計測できるよう、高精度で単調増加するタイムスタンプを公開します。

以下のスクリプトは、開発者が本仕様で定義されるインターフェイスを使って、開発者スクリプトに関連するタイミングデータを取得する方法を示しています。

例 1 
async function run() {
  performance.mark("startTask1");
  await doTask1(); // 一部の開発者コード
  performance.mark("endTask1");

  performance.mark("startTask2");
  await doTask2(); // 一部の開発者コード
  performance.mark("endTask2");

  // ログ出力
  const entries = performance.getEntriesByType("mark");
  for (const entry of entries) {
    console.table(entry.toJSON());
  }
}
run();
注

[PERFORMANCE-TIMELINE-2] では、記録されたメトリックを取得するための2つの仕組みが定義されています：getEntries() および getEntriesByType() メソッド、そして PerformanceObserver インターフェイスです。前者は特定のメトリックを名前で単一のタイミングで取得したい場合に最適であり、後者は新しいメトリックが利用可能になった際に通知を受け取りたい場合に最適化されています。

2. 適合性

規範的でないと明記されているセクションだけでなく、この仕様書に含まれるすべての作成ガイドライン、図、例、注記も規範的ではありません。 それ以外の内容はすべて規範的です。

MAY および MUST というキーワードは [RFC2119] で説明されている通りに解釈されます。

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

本仕様書のIDL断片は、Web IDL仕様書 [WEBIDL] で説明されている通り、適合するIDL断片には MUST として解釈されます。

3. User Timing

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

Performance インターフェイスは [HR-TIME-2] で定義されています。

partial interface Performance {
    void mark(DOMString markName);
    void clearMarks(optional DOMString markName);
    void measure(DOMString measureName, optional DOMString startMark, optional DOMString endMark);
    void clearMeasures(optional DOMString measureName);
};

3.1.1 mark() メソッド

関連付けられた名前（「マーク」）と共にタイムスタンプを保存します。以下の手順を MUST で実行します：

  1. global object が Window オブジェクトで、markName が PerformanceTiming インターフェイスの read only attribute と同じ名前の場合、throw SyntaxError を投げます。
  2. 新しい PerformanceMark オブジェクト（entry）を作成します。
  3. entry の name 属性に markName を設定します。
  4. entry の entryType 属性に DOMString "mark" を設定します。
  5. entry の startTime 属性に Performance オブジェクトの now() メソッドが返す値を設定します。
  6. entry の duration 属性に 0 を設定します。
  7. Queue entry を行います。
  8. entry を performance entry buffer に追加します。
  9. undefined を返します。

3.1.2 clearMarks() メソッド

関連付けられた名前のタイムスタンプを削除します。以下の手順を MUST で実行します：

  1. markName が省略された場合、PerformanceMark オブジェクトを performance entry buffer からすべて削除します。
  2. それ以外の場合、PerformanceMark オブジェクトで name が markName に一致するものを performance entry buffer からすべて削除します。
  3. undefined を返します。

3.1.3 measure() メソッド

2つのマーク間の DOMHighResTimeStamp の duration を、関連付けられた名前（「メジャー」）と共に保存します。以下の手順を MUST で実行します：

  1. end time を 0 とする。
  2. endMark が省略された場合、end time に Performance オブジェクトの now() メソッドの値を設定する。そうでなければ：
    1. endMark が PerformanceTiming インターフェイスの read only attribute と同じ名前の場合、convert a name to a timestamp アルゴリズムに name を endMark として渡した値を end time に設定する。
    2. それ以外の場合、PerformanceMark オブジェクトのうち name が endMark に一致するものの最新の startTime 属性の値を end time に設定する。該当エントリがなければ、throw SyntaxError を投げる。
  3. startMark が省略された場合、start time を 0 とする。そうでなければ：
    1. startMark が PerformanceTiming インターフェイスの read only attribute と同じ名前の場合、convert a name to a timestamp アルゴリズムに name を startMark として渡した値を start time に設定する。
    2. それ以外の場合、PerformanceMark オブジェクトのうち name が startMark に一致するものの最新の startTime 属性の値を start time に設定する。該当エントリがなければ、throw SyntaxError を投げる。
  4. 新しい PerformanceMeasure オブジェクト（entry）を作成する。
  5. entry の name 属性に measureName を設定する。
  6. entry の entryType 属性に DOMString "measure" を設定する。
  7. entry の startTime 属性に start time を設定する。
  8. entry の duration 属性に start time から end time までの継続時間を設定する。結果の duration 値は MAY マイナス値であっても良い。
  9. Queue entry を行う。
  10. entry を performance entry buffer に追加する。
  11. undefined を返す。

3.1.4 clearMeasures() メソッド

関連付けられた名前のタイムスタンプを削除します。以下の手順を MUST で実行します：

  1. measureName が省略された場合、PerformanceMeasure オブジェクトを performance entry buffer からすべて削除する。
  2. それ以外の場合、PerformanceMeasure オブジェクトで name が measureName に一致するものを performance entry buffer からすべて削除する。
  3. undefined を返す。

3.2 PerformanceMark インターフェイス

PerformanceMark インターフェイスは、performance.mark メソッドで作成されたマークも Performance Timeline へ公開します。 

[Exposed=(Window,Worker)]
interface PerformanceMark : PerformanceEntry {
};

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

name 属性はマーク名を返します。

entryType 属性は DOMString の "mark" を返します。

startTime 属性は、そのマークの時刻値を持つ DOMHighResTimeStamp を返します。

duration 属性は値 0 の DOMHighResTimeStamp を返します。

3.3 PerformanceMeasure インターフェイス

PerformanceMeasure インターフェイスは、performance.measure メソッドで作成されたメジャーも Performance Timeline へ公開します。 

[Exposed=(Window,Worker)]
interface PerformanceMeasure : PerformanceEntry {
};

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

name 属性はメジャー名を返します。

entryType 属性は DOMString の "measure" を返します。

startTime 属性は、メジャーの開始マークを持つ DOMHighResTimeStamp を返します。

duration 属性はメジャーの継続時間を持つ DOMHighResTimeStamp を返します。

4. 処理

User Timing APIを実装するユーザーエージェントは、以下の手順を実行しなければなりません：

  1. register a performance entry typeアルゴリズムを、入力として"mark"を指定して実行する。
  2. register a performance entry typeアルゴリズムを、入力として"measure"を指定して実行する。

4.1 name を timestamp に変換

timestampへのnameの変換を、nameが PerformanceTimingインターフェイスのread only attributeである場合、以下の手順を実行します：

  1. global objectがWindowオブジェクトでない場合、throw SyntaxErrorを投げる。
  2. nameがnavigationStartなら0を返す。
  3. startTimeをPerformanceTimingインターフェイスのnavigationStartの値とする。
  4. endTimeをPerformanceTimingインターフェイスのnameの値とする。
  5. endTimeが0の場合、throw InvalidAccessErrorを投げる。
  6. startTimeをendTimeから減算した結果を返す。
注

PerformanceTiming インターフェイスは [NAVIGATION-TIMING] で定義されましたが、現在は廃止扱いです。 PerformanceTimingインターフェイスの名前の利用は後方互換性のためにサポートされていますが、今後PerformanceNavigationTimingインターフェイス([NAVIGATION-TIMING-2]で定義)や他インターフェイスでこの機能を拡張する計画はありません。

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

このセクションは規範的ではありません。

この仕様で定義されるインターフェイスは、ページの特定JavaScriptアクティビティについて機微なタイミング情報を公開します。 高精度タイミング情報の公開に関するプライバシーとセキュリティの考慮事項については [HR-TIME-2] を参照してください。

ウェブプラットフォームは、ページに含まれる任意のスクリプトが、そのページに含まれる他のスクリプトと同じアクセス権を持つという不変性のもと設計されています。したがって、この仕様で定義されるインターフェイスは、タイミング情報の記録・取得に関して制限を設けていません。すなわち、ページ上の任意のスクリプトで記録されたユーザータイミングのマークやメジャーは、同じページ上で動作する他の任意のスクリプトから（オリジンに関係なく）取得可能です。

A. 謝辞

James Simonsen、 Jason Weber、 Nic Jansma、 Philippe Le Hegaret、 Karen Anderson、 Steve Souders、 Sigbjorn Vik、 Todd Reifsteck、 Tony Gentilcore 各氏に本仕様への貢献を感謝します。

B. 参考文献

B.1 規範的参考文献

[HR-TIME-2]
高精度時間 レベル2．Ilya Grigorik；James Simonsen；Jatinder Mann．W3C．2018年3月1日．W3C候補勧告．URL: https://www.w3.org/TR/hr-time-2/
[HTML51]
HTML 5.1 第2版．Steve Faulkner；Arron Eicholz；Travis Leithead；Alex Danilo．W3C．2017年10月3日．W3C勧告．URL: https://www.w3.org/TR/html51/
[NAVIGATION-TIMING]
Navigation Timing．Zhiheng Wang．W3C．2012年12月17日．W3C勧告．URL: https://www.w3.org/TR/navigation-timing/
[PERFORMANCE-TIMELINE-2]
Performance Timeline レベル2．Ilya Grigorik．W3C．2019年1月10日．W3C作業草案．URL: https://www.w3.org/TR/performance-timeline-2/
[RFC2119]
RFCで要求レベルを示すためのキーワード．S. Bradner．IETF．1997年3月．Best Current Practice．URL: https://tools.ietf.org/html/rfc2119
[WEBIDL]
Web IDL．Cameron McCormack；Boris Zbarsky；Tobie Langel．W3C．2016年12月15日．W3C編集者草稿．URL: https://heycam.github.io/webidl/
[WORKERS]
Web Workers．Ian Hickson．W3C．2015年9月24日．W3C作業草案．URL: https://www.w3.org/TR/workers/

B.2 参考情報

[ECMA-262]
ECMAScript言語仕様．Ecma International．URL: https://tc39.github.io/ecma262/
[NAVIGATION-TIMING-2]
Navigation Timing レベル2．Ilya Grigorik；Tobin Titus；Jatinder Mann；Arvind Jain．W3C．2018年11月30日．W3C作業草案．URL: https://www.w3.org/TR/navigation-timing-2/
[USER-TIMING]
User Timing．Jatinder Mann；Zhiheng Wang；Anderson Quach．W3C．2013年12月12日．W3C勧告．URL: https://www.w3.org/TR/user-timing/