W3C

User Timing — 利用者による計時

2013 年 12 月 12 日付 W3C 勧告

このバージョン
http://www.w3.org/TR/2013/REC-user-timing-20131212/
最新バージョン
http://www.w3.org/TR/user-timing/
前のバージョン
http://www.w3.org/TR/2013/PR-user-timing-20131031/
http://www.w3.org/TR/2012/WD-user-timing-20120508/
編集
Jatinder Mann, Microsoft Corp., jmann@microsoft.com
Zhiheng Wang, Google Inc. (Until July 2013)
Anderson Quach, Microsoft Corp. (Until March 2011)

公式の修正も含まれ得る,この文書の 正誤表 も参照願います。 Please refer to the errata for this document, which may include some normative corrections.

各国語の翻訳 See also translations.

Copyright © 2013 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.

要約

この仕様は、高精度タイムスタンプへのアクセスを与えることにより,ウェブ開発者による自身のアプリケーションの速度性能の測定を支援するためのインタフェースを定義する。 This specification defines an interface to help web developers measure the performance of their applications by giving them access to high precision timestamps.

この文書の位置付け

この節では、発行時点における… 【 以下、この節の内容の一部は W3C 日本語訳 共通ページ に委譲 】

この文書は Web Performance Working Group により作成された W3C 勧告 "User Timing Specification" です。 2013 年 8 月に作成された 実装報告書 も入手できます。 This is the W3C Recommendation of "User Timing Specification", produced by the Web Performance Working Group. An implementation report as of August 2013 is available.

前回の発行バージョンから変更された所はありません。 No changes were made since the previous publication.

勧告の発行にあたり、 W3C は,この仕様に指定される機能が,勧告に昇格するまでの間に Web IDL における変更からは影響されないものと予期しています。 By publishing this Recommendation, W3C expects that the functionality specified in this User Timing Recommendation will not be affected by changes to Web IDL as this specification proceed to Recommendation.

コメントがあれば、件名の先頭に [UserTiming] と記した上で public-web-perf@w3.org (archived) 宛まで送られるよう願います。 Please send comments to public-web-perf@w3.org (archived) with [UserTiming] at the start of the subject line. Please send comments to public-web-perf@w3.org (archived) with [UserTiming] at the start of the subject line by 1 November 2012.

1 序論

この節は参考である。 This section is non-normative.

ウェブ開発者は、アプリケーションの速度性能特性について,アクセスし, 理解するための機能を必要とする。 JavaScript [ECMA262] は,アプリケーションの遅延を測定する仕組み( Date.now() メソッドで現在のタイムスタンプを取得)を提供するが、このタイムスタンプの精度は UA (利用者エージェント)によってまちまちである。 Web developers need the ability to assess and understand the performance characteristics of their applications. While JavaScript [ECMA262] provides a mechanism to measure application latency (retrieving the current timestamp from the Date.now() method), the precision of this timestamp varies between user agents.

この文書は、開発者がアプリケーションの速度性能をより正確に測定できるようにする高精度のタイムスタンプを公開するために, PerformanceMarkPerformanceMeasure インタフェース,および Performance インタフェースの拡張を定義する。 This document defines the PerformanceMark and PerformanceMeasure interfaces, and extensions to the Performance interface, which expose a high precision timestamp to developers so they can better measure the performance of their applications.

次のスクリプトに,開発者がスクリプトに関わる計時データを得るために、この文書で定義されるインタフェースを利用する例を示す: The following script shows how a developer can use the interfaces defined in this document to obtain timing data related to developer scripts.

<!doctype html>
<html>
  <head>
    <title>User Timing example</title>
  </head>
  <body onload="init()">
    <script>
       function init() 
       {
            performance.mark("startTask1");
            doTask1(); // Some developer code
            performance.mark("endTask1");
            
            performance.mark("startTask2");
            doTask2(); // Some developer code
            performance.mark("endTask2");

            measurePerf();
       }

       function measurePerf() 
       {
           var perfEntries = performance.getEntriesByType("mark");
           for (var i = 0; i < perfEntries.length; i++)
           {
                 if (window.console) console.log(
                       "Name: "        + perfEntries[i].name      + 
                       " Entry Type: " + perfEntries[i].entryType +
                       " Start Time: " + perfEntries[i].startTime + 
                       " Duration: "   + perfEntries[i].duration  + "\n"
                 );
           }
       }
    </script>
  </body>
</html>

2 適合性の要件

【 この節の内容は W3C 日本語訳 共通ページ に委譲 】

3 語法

【 この節の内容の一部は W3C 日本語訳 共通ページ に委譲 】

この仕様を通して、時刻は 文書のナビゲーションの開始を起点としてミリ秒単位で計測されるものとする。 例えば,文書のナビゲーションの開始は、時刻 0 で生じる。 語 “〜の時刻” は、文書のナビゲーションの開始から その時点までに経過した,ミリ秒数による時刻を指す。 この,時刻の定義は、 High Resolution Time 仕様 [High Resolution Time] に基づくものであり、 1970 年 1 月 1 日 0 時 0 分 0 秒 (UTC) を起点としていた, Navigation Timing 仕様 [Navigation Timing] による定義とは異なる。 Throughout this work, all time values are measured in milliseconds since the start of navigation of the document. For example, the start of navigation of the document occurs at time 0. The term current time refers to the number of milliseconds since the start of navigation of the document until the current moment in time. This definition of time is based on the High Resolution Time specification [High Resolution Time] and is different from the definition of time used in the Navigation Timing specification [Navigation Timing], where time is measured in milliseconds since midnight of January 1, 1970 (UTC).

4 User Timing — 利用者による計時

4.1 概要

この節は参考である。 This section is non-normative

PerformanceMarkPerformanceMeasure インタフェース, および Performance インタフェースの拡張は、高精度かつ単調増加するタイムスタンプへのアクセスを提供し、ウェブ開発者がアプリケーションの速度性能をより正確に測定できるようにする。 The PerformanceMark and PerformanceMeasure interfaces, and extensions to the Performance interface, give web developers access to a high precision, monotonically increasing timestamp so they can better measure the performance characteristics of their applications.

4.2 Performance インタフェースに対する拡張

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);
};
mark method

このメソッドは、名前が結び付けられたタイムスタンプ( “マーク” と称される)を記録する。 This method stores a timestamp with the associated name (a "mark").

引数
DOMString markName

タイムスタンプに結び付けられる名前( “マーク名” )。 The name associated with the timestamp.

マーク名は同じ文書内で再利用できる。 mark() メソッドの各呼び出しは、指定されたマーク名の下に新たなタイムスタンプを記録する。 Mark names may be re-used within the same document. Each call to the mark() method stores a new timestamp under the specified mark name.

マーク名は、 PerformanceTiming インタフェース [Navigation Timing] 内のどの属性とも同じ名前になれない。 The mark name cannot be the same name as any of the attributes in the PerformanceTiming interface [Navigation Timing].

推奨マーク名 ( Recommended Mark Names ) Recommended Mark Names

共通して生じ得る動作に対するマーク名には,次の推奨マーク名の利用が開発者に奨励される。 UA は、指定されたマーク名の下に,新たなタイムスタンプを記録する責を負う。 UA は、推奨マーク名の利用が適切であるか, あるいはその説明に整合しているかどうかについては,私的に指定されたマーク名と同様に,検証しない。 Developers are encouraged to use the following Recommended Mark Names to mark common interactions. The user agent is responsible for storing a new timestamp under the specified mark name for Recommended Mark Names, just like any user specified mark name. The user agent does not validate that the usage of the Recommended Mark Name is appropriate or consistent with its description.

"mark_fully_loaded"
(開発者の)アプリケーションにおいて、ページが完全に読み込まれたものと 開発者により見なされ,マークされた時刻。 The time when the page is considered fully loaded as marked by the developer in their application.
"mark_fully_visible"
アプリケーションにおいて、ページが末端利用者から完全に見えるようになったものと 開発者により見なされ,マークされる時刻。 The time when the page is considered completely visible to an end-user as marked by the developer in their application.
"mark_above_the_fold"
アプリケーションにおいて、可視の表示域内の内容が末端利用者に表示されたものと 開発者により見なされ,マークされる時刻。 The time when all of the content in the visible viewport has been presented to the end-user as marked by the developer in their application.
"mark_time_to_user_action"
アプリケーションにおいて、ナビゲーションの間, またはその後に、スクロールやクリックなど,ページと末端利用者との対話が最初に生じたものと 開発者により見なされ,マークされる時刻。 The time of the first user interaction with the page during or after a navigation, such as scroll or click, as marked by the developer in their application.
返り値なし
例外
markName 引数が PerformanceTiming インタフェース内の属性と同じ名前を持つ場合、 SYNTAX_ERR 例外が投出される。 Throws a SYNTAX_ERR exception if the markName argument is the same name as an attribute in the PerformanceTiming interface.
clearMarks method

markName 引数が指定されなかった場合、このメソッドは,すべてのマークとそれに結び付けられた DOMHighResTimeStamp 時刻値を取り除く。 If the markName argument is not specified, this method removes all marks and their associated DOMHighResTimeStamp time values.

markName 引数が指定された場合、このメソッドは,与えられたマーク名を持つ,すべての DOMHighResTimeStamp 時刻値を取り除く。 If the markName argument is specified, this method removes all DOMHighResTimeStamp time values for the given mark name.

markName 引数は指定されたが、指定された markName が存在しなかった場合、このメソッドは何もしない。 If the markName argument is specified but the specified markName does not exist, this method will do nothing.

引数
optional DOMString markName
クリア対象の DOMHighResTimeStamp 時刻値を指定する,マーク名。 指定されなかった場合、すべてのマークがクリアされる。 [optional] The name of the mark whose DOMHighResTimeStamp time values should be cleared. If not specified, all marks will be cleared.
返り値なし
例外は投出されない
measure method

このメソッドは、2つのマーク間の DOMHighResTimeStamp による時間長( duration )に名前を付けて( “測定” ( “measure” )と称される)記録する。 This method stores the DOMHighResTimeStamp duration between two marks along with the associated name (a "measure").

このメソッドのふるまいは指定された引数に依存する: The behavior of this method depends on which arguments are specified:

  • startMark 引数も endMark 引数も指定されなかった場合、 measure() は, navigationStart から現在の時刻までの時間長を DOMHighResTimeStamp として記録する。 If neither the startMark nor the endMark argument is specified, measure() will store the duration as a DOMHighResTimeStamp from navigationStart to the current time.

  • startMark 引数は指定されたが,endMark 引数は指定されなかった場合、 measure() は, 直近の開始マークから現在の時刻までの時間長を DOMHighResTimeStamp として記録する。 【開始マーク( start mark ): startMark 引数の値を名前に持つマークを指す(以下同様)。同様に、“終了マーク” は endMark 引数の値を名前に持つマークを指す。】 【直近の:時間軸上で最も近くに(最後に mark() メソッドで)記録された】 If the startMark argument is specified, but the endMark argument is not specified, measure() will store the duration as a DOMHighResTimeStamp from the most recent occurrence of the start mark to the current time.

  • startMark 引数と endMark 引数がいずれも指定された場合、 measure() は,直近の開始マークから直近の終了マークまでの時間長を DOMHighResTimeStamp として記録する。 If both the startMark and endMark arguments are specified, measure() will store the duration as a DOMHighResTimeStamp from the most recent occurrence of the start mark to the most recent occurrence of the end mark.

startMark 引数と endMark 引数は PerformanceTiming インタフェース [Navigation Timing] 内の属性の名前でもよい。 この場合、その属性の値が DOMHighResTimeStamp 時刻値として利用される。 The startMark and endMark arguments may be the name of one of the attributes in the PerformanceTiming interface [Navigation Timing]. In this case, the value of that attribute is used as the DOMHighResTimeStamp time value.

引数
DOMString name

この測定に付けられる名前(以下,“測定名” )。 The name associated with the measure.

測定名は同じ文書内で再利用できる。 measure() メソッドの各呼び出しは、指定された測定名の下に新たな時間長を記録する。 Measure names may be re-used within the same document. Each call to the measure() method stores a new duration under the specified measure name.

測定名とマーク名は別々に扱われる。 Measure names live independently from mark names.

optional DOMString startMark

開始マークの名前 [optional] The name of the start mark.

指定された場合、直近の開始マークの DOMHighResTimeStamp 時刻値が利用される。 If specified, the most recent DOMHighResTimeStamp time value of the start mark is used.

指定されなかった場合、 navigationStart が利用される。 If not specified, navigationStart is used.

PerformanceTiming インタフェース [Navigation Timing] 内の属性の名前でもよい。 この場合、その属性の値が開始 DOMHighResTimeStamp 時刻値として利用される。 May be the name of one of the attributes in the PerformanceTiming interface [Navigation Timing]. In this case, the value of that attribute is used as the start DOMHighResTimeStamp time value.

optional DOMString endMark

終了マークの名前。 [optional] The name of the end mark.

指定された場合、直近の終了マークの DOMHighResTimeStamp 時刻値が利用される。 If specified, the most recent DOMHighResTimeStamp time value of the end mark is used.

指定されなかった場合、現在の時刻が DOMHighResTimeStamp に利用される。 If not specified, the current time as a DOMHighResTimeStamp is used.

PerformanceTiming インタフェース [Navigation Timing] 内の属性の名前でもよい。 この場合、その属性の値が終了 DOMHighResTimeStamp 時刻値として利用される。 May be the name of one of the attributes in the PerformanceTiming interface [Navigation Timing]. In this case, the value of that attribute is used as the end DOMHighResTimeStamp time value.

返り値なし
例外

開始マークや終了マークが存在しなかった場合、 SYNTAX_ERR 例外が投出される。 Throws a SYNTAX_ERR exception if the start mark or end mark does not exist.

startMark または endMark 引数, あるいはその両者が 時刻値 0 の PerformanceTiming 属性と同じ名前を持つ場合、 INVALID_ACCESS_ERR 例外が投出される。 Throws an INVALID_ACCESS_ERR exception if either startMark or endMark argument, or both, have the same name as a PerformanceTiming attribute with a time value of 0.

clearMeasures method

measureName 引数が指定されなかった場合、このメソッドは,すべての測定とそれらに結び付けられた DOMHighResTimeStamp 時間長を取り除く。 If the measureName argument is not specified, this method removes all measures and their associated DOMHighResTimeStamp durations.

measureName 引数が指定された場合、このメソッドは,与えられた測定名に対するすべての DOMHighResTimeStamp 時間長を取り除く。 If the measureName argument is specified, this method removes all DOMHighResTimeStamp durations for the given measure name.

measureName 引数は指定されたが,指定された measureName が存在しなかった場合、このメソッドは何もしない。 If the measureName argument is specified but the specified measureName does not exist, this method will do nothing.

引数
optional DOMString measureName

クリア対象の DOMHighResTimeStamp 時間長を指定する,測定名。 指定されなかった場合、すべての測定がクリアされる。 [optional] The name of the measure whose DOMHighResTimeStamp durations should be cleared. If not specified, all measures will be cleared.

返り値なし
例外は投出されない

4.3 PerformanceMark インタフェース

interface PerformanceMark : PerformanceEntry {
};

PerformanceMark インタフェースは mark() メソッドにより作成されたマークも Performance Timeline [Performance Timeline] に公開する。 PerformanceMark インタフェースは PerformanceEntry インタフェースの次の属性を拡張する: The PerformanceMark interface also exposes marks created via the mark() method to the Performance Timeline [Performance Timeline]. The PerformanceMark interface extends the following attributes of the PerformanceEntry interface:

name 属性は、マーク名を返す。 The name attribute will return the mark's name.

entryType 属性は、 DOMString mark を返す。 The entryType attribute will return the DOMString mark.

startTime 属性は、 DOMHighResTimeStamp [High Resolution Time] による,マークの時刻値を返す。 The startTime attribute will return a DOMHighResTimeStamp with the mark's time value [High Resolution Time].

duration 属性は、 DOMHighResTimeStamp 値 0 を返す。 The duration attribute will return a DOMHighResTimeStamp of value 0.

4.4 PerformanceMeasure インタフェース

interface PerformanceMeasure : PerformanceEntry {
};

PerformanceMeasure インタフェースは measure() メソッドにより作成された測定も Performance Timeline [Performance Timeline] に公開する。 PerformanceMeasure インタフェースは PerformanceEntry インタフェースの次の属性を拡張する: The PerformanceMeasure interface also exposes measures created via the measure() method to the Performance Timeline [Performance Timeline]. The PerformanceMeasure interface extends the following attributes of the PerformanceEntry interface:

name 属性は、測定名を返す。 The name attribute will return the measure's name.

entryType 属性は、 DOMString measure を返す。 The entryType attribute will return the DOMString measure.

startTime 属性は、 DOMHighResTimeStamp [High Resolution Time] による,測定の開始マークを返す。 The startTime attribute will return a DOMHighResTimeStamp with the measure's start mark [High Resolution Time].

duration 属性は、 DOMHighResTimeStamp による,測定の時間長を返す。 The duration attribute will return a DOMHighResTimeStamp with the duration of the measure.

4.5 ベンダ接頭辞

ベンダ固有のプロプライエタリ UA 拡張は推奨されない。 例えば,試験的な目的でその種の拡張が必要になった場合、ベンダは次の拡張の仕組みを利用しなければならない: Vendor-specific proprietary user agent extensions are discouraged. If such extensions are needed, e.g. for experimental purposes, vendors must use the following extension mechanisms:

Standard Mark Name ( “標準マーク名” )として,拡張を追加する場合、その標準マーク名は次の命名規約に従わなければならない: If the extension to be added is a Standard Mark Name, the Standard Mark Name must:

  • [VENDORPREFIX]_[STANDARD_MARK_NAME]

    ここで、 [VENDORPREFIX] はベンダを識別する名前, [STANDARD_MARK_NAME] は標準マークに付けられる名前とする。 Follow this naming convention: [VENDORPREFIX]_[STANDARD_MARK_NAME], where [VENDORPREFIX] is a name that identifies the vendor and [STANDARD_MARK_NAME] is the name given to the Standard Mark.

5 単調増加クロック

インタフェース内に記録される時刻値は、システムクロックの調整に影響されないように,単調増加でなければならない。 時系列順に記録されたどの2つの時刻値の差分も,非負でなければならない。 UA は、ナビゲーション開始時のシステムクロックを記録し、後続の時刻値を,単調増加のクロックにより測定されるナビゲーション開始からの経過時間として,定義しなければならない The time values stored within the interface must monotonically increase to ensure they are not affected by adjustments to the system clock. The difference between any two chronologically recorded time values must never be negative. The user agent must record the system clock at the beginning of the navigation and define subsequent time values in terms of a monotonic clock measuring time elapsed from the beginning of the navigation.

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

この節は参考である。 This section is non-normative.

この仕様に定義されるインタフェースは、ページ上の特定の JavaScript 動作において sensitive になり得る計時情報を公開する。 しかしながら, Performance Timeline 上に定義される他のインタフェースとは異なり、この仕様に定義されるインタフェースには、スクリプトを通じた計時情報の共有に課される制約はない。 その理由は、ウェブプラットフォームが、スクリプトの生成元( origin )に関わらず,ページ上に含まれるどのスクリプトも,同じページ上に含まれる他のスクリプトと同じアクセスを持つものとして、設計されているためである。 The interfaces defined in this specification expose potentially sensitive timing information on specific JavaScript activity of a page. However, unlike other interfaces defined in the Performance Timeline, the interfaces defined in this specification do not have any restrictions on sharing timing information through script. This is because the web platform has been designed with the invariant that any script included on a page has the same access as any other script included on that page regardless of the origin of the script.

謝辞

この仕様の進行にあたって有用なコメントを寄せられ,この仕事に寄与された次の方々に感謝する: Thanks to Karen Anderson, Tony Gentilcore, Nic Jansma, James Simonsen, Steve Souders, Sigbjorn Vik, and Jason Weber for their useful comments that led to changes to this specification and their contributions to this work.

参照文献

[RFC 2119]
Key words for use in RFCs to Indicate Requirement Levels, Scott Bradner, Author. Internet Engineering Task Force, March 1997. Available at http://www.ietf.org/rfc/rfc2119.txt.
[ECMA-262]
ECMAScript Language Specification, 5.1 Edition. ECMA International, Standard ECMA-262, June 2011. This version of the ECMAScript Language is available from http://www.ecma-international.org/publications/standards/Ecma-262.htm.
Navigation Timing, Zhiheng Wang, Editor. World Wide Web Consortium, December 2012. This version of the Navigation Timing specification is available from http://www.w3.org/TR/2012/REC-navigation-timing-20121217/. The latest version of Navigation Timing is available at http://www.w3.org/TR/navigation-timing/.
[Performance Timeline]
Performance Timeline, Jatinder Mann, et al, Editors. W3C Recommendation, World Wide Web Consortium, December 2013. This version of the Performance Timeline Recommendation is available from http://www.w3.org/TR/2013/REC-performance-timeline-20131212/. The latest version of Performance Timeline is available at http://www.w3.org/TR/performance-timeline/.
[High Resolution Time]
High Resolution Time, Jatinder Mann, Editor. W3C Recommendation, World Wide Web Consortium, December 2012. This version of the High Resolution Time specification is available from http://www.w3.org/TR/2012/REC-hr-time-20121217/. The latest version of High Resolution Time is available at http://www.w3.org/TR/hr-time/.
[Web IDL]
Web IDL, Cameron McCormack, Editor. World Wide Web Consortium, April 2012. This version of the Web IDL specification is available from http://www.w3.org/TR/2012/CR-WebIDL-20120419/. The latest version of Web IDL is available at http://www.w3.org/TR/WebIDL/.