1. 序論
~INFORMATIVE~web~appの処理能~特性を正確0に計測することは、~web~appを より速くするための重要な側面である。 この仕様は、~web開発者が, ~web~appの全存続期間にわたる種々の処理能~計量[ に~accessする / を測定する / を取得する ]ことを可能化するために必要とされる `処理能時列線$の~primitiveを定義する。 ◎ Accurately measuring performance characteristics of web applications is an important aspect of making web applications faster. This specification defines the necessary Performance Timeline primitives that enable web developers to access, instrument, and retrieve various performance metrics from the full lifecycle of a web application.
[ `NAVIGATION-TIMING-2$r / `RESOURCE-TIMING-2$r / `USER-TIMING-2$r ]は、順に[ 文書の~navi / ~page上の資源 / 開発者~script ]に関係する計時~情報を定義する仕様の例である。 これらは、他の処理能~interfaceと伴に,~web~appの`処理能時列線$を述べる処理能の計量を定義する。 例えば,次の~scriptは、開発者が[ 文書の~navi / ~page上の資源 / 開発者~script ]に関係する処理能~計量を得るために `処理能時列線$に~accessする方法を示すものである: ◎ [NAVIGATION-TIMING-2], [RESOURCE-TIMING-2], and [USER-TIMING-2] are examples of specifications that define timing information related to the navigation of the document, resources on the page, and developer scripts, respectively. Together these and other performance interfaces define performance metrics that describe the Performance Timeline of a web application. For example, the following script shows how a developer can access the Performance Timeline to obtain performance metrics related to the navigation of the document, resources on the page, and developer scripts:
<!doctype html> <html> <head></head> <body onload="init()"> <img id="image0" src="https://www.w3.org/Icons/w3c_main.png" /> <script> function init() { /* `USER-TIMING-2$r を見よ ◎ see [[USER-TIMING-2]] */ performance.mark("startWork"); doWork(); /* 何らかの開発者~code ◎ Some developer code */ performance.mark("endWork"); measurePerf(); } function measurePerf() { performance .getEntries() .map(%entry => JSON.stringify(%entry, null, 2)) .forEach(%json => console.log(%json)); } </script> </body> </html>
別法として,開発者は、`処理能時列線$を観測して,新たな処理能~計量が観測される度に `PerformanceObserver$I ~interfaceを介して通知させれる。 また,任意選択で、指定した種別の, すでに~buffer済みの処理能~計量も通知させれる。 ◎ Alternatively, the developer can observe the Performance Timeline and be notified of new performance metrics and, optionally, previously buffered performance metrics of specified type, via the PerformanceObserver interface:
<!doctype html> <html> <head></head> <body> <img id="image0" src="https://www.w3.org/Icons/w3c_main.png" /> <script> const %observer = new PerformanceObserver(%list => { %list .getEntries() /* 挿入された値を取得する ◎ Get the values we are interested in */ .map(({ %name, %entryType, %startTime, %duration }) => { const %obj = { "Duration": %duration, "Entry Type": %entryType, "Name": %name, "Start Time": %startTime, }; return JSON.stringify(%obj, null, 2); }) /* それらを~consoleに表示する ◎ Display them to the console */ .forEach(console.log); /* ~eventを処理したなら~disconnectされてよい ◎ maybe disconnect after processing the events. */ %observer.disconnect(); }); /* Resource-Timing と User-Timing ~eventに対し, ~buffer済みの~eventを取得する/新たな~eventを申込む ◎ retrieve buffered events and subscribe to new events for Resource-Timing and User-Timing */ observer.observe({ entryTypes: [`resource^l, `mark^l, `measure^l], buffered: true }); </script> </body> </html>
Performance Timeline Level 2 には、 `PerformanceObserver$I ~interfaceが追加された。 これは、最初の例に示された~bufferに基づく~approachにおける制限に取組むように設計されている。 `PerformanceObserver$I を利用すれば、~appは次が可能になる: ◎ The PerformanceObserver interface was added in Performance Timeline Level 2 and is designed to address limitations of the buffer-based approach shown in the first example. By using the PerformanceObserver interface, the application can:
- 時列線を調べ続ける( polling )ことなく,新たな計量を検出できる。 ◎ Avoid polling the timeline to detect new metrics
- ~costのかかる~~重複排除~logic( deduplication )なしに,新たな計量を識別できる。 ◎ Eliminate costly deduplication logic to identify new metrics
- 他の消費者と~~競合する( race condition )ことなく,~bufferを操作できる。 ◎ Eliminate race conditions with other consumers that may want to manipulate the buffer
開発者には、可能0な所では, `PerformanceObserver$I を利用することが奨励される。 加えて,新たな処理能 API や計量は、 `PerformanceObserver$I ~interfaceを通してのみ可用にされることになる。 ◎ The developer is encouraged to use PerformanceObserver where possible. Further, new performance API's and metrics may only be available through the PerformanceObserver interface.
【この訳に固有の表記規約】
この訳の,~algoの記述に利用されている各種記号( 此れ, ~LET, ~IF, ~RET, 等々)の意味や定義の詳細は、~SYMBOL_DEF_REFを~~参照されたし。
2. 適合性
【 この節の内容は W3C 日本語訳 共通ページ に委譲 】
3. 処理能時列線
各 `~ES大域~環境$【`大域~obj$】には、次のものが結付けられる:
- `処理能~観測器~task~queue済み~flag@
- ~flag値。 【初期~時は ~OFF 】
- `処理能~観測器~list@
- `処理能~観測器$からなる~list。 初期~時は空とする。
- `処理能~観測器$は、この~list内にある間は `登録-済み^i であるともいう。
- `処理能~entry~buffer@
- `PerformanceEntry$I ~objたちを格納する(初期~時は空)。
~objに`関連する処理能~entry~buffer@ は、[ ~objに`関連する大域~obj$ ]に結付けられている`処理能~entry~buffer$を指す。 ◎ The relevant performance entry buffer is the performance entry buffer associated with the relevant global object.
3.1. `Performance^I ~interfaceに対する拡張
この節では、[ 処理能に関係する各種~属性, および[ `処理能時列線$からの処理能~計量~dataを取得する ]ために利用される 各種~method ]を~hostするように, `HR-TIME-2$r の `Performance$I ~interfaceを拡張する。 ◎ This extends the Performance interface [HR-TIME-2] and hosts performance related attributes and methods used to retrieve the performance metric data from the Performance Timeline.
partial interface `Performance$I { `PerformanceEntryList$I `getEntries$m(); `PerformanceEntryList$I `getEntriesByType$m(`DOMString$ %type); `PerformanceEntryList$I `getEntriesByName$m(`DOMString$ %name, optional `DOMString$ %type); }; typedef `sequence$<`PerformanceEntry$I> `PerformanceEntryList$I;
`PerformanceEntryList@I は、 `PerformanceEntry$I の連列を表現する — それは、開発者に~JS配列の便利~methodすべてを供する。 ◎ The PerformanceEntryList represents a sequence of PerformanceEntry, providing developers with all the convenience methods found on JavaScript arrays.
- `getEntries()@m
- 被呼出時には、此れに`関連する処理能~entry~buffer$を ( ~NULL, ~NULL ) で`絞込んだ$結果を返さ~MUST。 ◎ 3.1.1 getEntries() method ◎ Returns a PerformanceEntryList object returned by 4.2 Filter buffer by name and type algorithm with buffer set to relevant performance entry buffer, and name and type set to null.
- `getEntriesByType(type)@m
- 被呼出時には、此れに`関連する処理能~entry~buffer$を ( ~NULL, %type ) で`絞込んだ$結果を返さ~MUST。 ◎ 3.1.2 getEntriesByType() method ◎ Returns a PerformanceEntryList object returned by 4.2 Filter buffer by name and type algorithm with buffer set to relevant performance entry buffer, name set to null, and type set to type.
- `getEntriesByName(name, type)@m
- 被呼出時には、此れに`関連する処理能~entry~buffer$を ( %name, %type (省略時は ~NULL) ) で`絞込んだ$結果を返さ~MUST。 ◎ 3.1.3 getEntriesByName() method ◎ Returns a PerformanceEntryList object returned by 4.2 Filter buffer by name and type algorithm with buffer set to relevant performance entry buffer, name set to name, and type set to null if optional entryType is omitted, and type set to type otherwise.
3.2. `PerformanceEntry^I ~interface
`PerformanceEntry$I ~interfaceは、種々の計量による処理能~dataを~hostする。 ◎ The PerformanceEntry interface hosts the performance data of various metrics.
[`Exposed$=(Window,Worker)] interface `PerformanceEntry@I { readonly attribute `DOMString$ `name$m; readonly attribute `DOMString$ `entryType$m; readonly attribute `DOMHighResTimeStamp$I `startTime$m; readonly attribute `DOMHighResTimeStamp$I `duration$m; [`Default$] `object$ `toJSON$m(); };
- `name@m
- 取得子は、此れの識別子を返さ~MUST。 この識別子は、一意になる必要はない。 ◎ This attribute MUST return an identifier for this PerformanceEntry object. This identifier does not have to be unique.
- `entryType@m
- 取得子は、此れで表現される ~interface型 を述べる `DOMString^I を返さ~MUST。 ◎ This attribute MUST return the type of the interface represented by this PerformanceEntry object.
-
他の仕様で定義される `entryType^m 値の例には、次が挙げられる:
- `mark^l, `measure^l `USER-TIMING-2$r
- `navigation^l `NAVIGATION-TIMING-2$r
- `resource^l `RESOURCE-TIMING-2$r
- `longtask^l 【仕様は不明 — `paint^l `PAINT-TIMING$r ?】
- `startTime@m
- 取得子は、[ 此れの処理能~計量にて最初に記録された時刻印 ]を~~表現する `DOMHighResTimeStamp$I 値を返さ~MUST。 処理能~計量に開始-時刻の概念は適用されない場合、 0 を返すことにしても~MAY。 ◎ This attribute MUST return the time value of the first recorded timestamp of this performance metric. If the startTime concept doesn't apply, a performance metric may choose to return a startTime of 0.
- `duration@m
- 取得子は、[ 此れに記録される~event全体の所要時間 ]を~~表現する `DOMHighResTimeStamp$I 値を返さ~MUST。 これは概して,此れに[ 最初に記録された時刻印 ]から[ 最後に記録された時刻印 ]までの時間~差になる。 処理能~計量に所要時間の概念が適用されない場合、 0 を返すことにしても~MAY。 ◎ This attribute MUST return the time value of the duration of the entire event being recorded by this PerformanceEntry. Typically, this would be the time difference between the last recorded timestamp and the first recorded timestamp of this PerformanceEntry. If the duration concept doesn't apply, a performance metric may choose to return a duration of 0.
- `toJSON()@m
- ~call時には、 `WebIDL$r による`既定の~toJSON演算$を走らす。 ◎ When toJSON is called, run [WebIDL]'s default toJSON operation.
3.3. `PerformanceObserver^I ~interface
`PerformanceObserver$I ~interfaceを利用すれば、`処理能時列線$を観測して,新たな処理能~計量( `PerformanceEntry$I ~obj)が記録される度に通知させれる。 また,任意選択で、すでに~buffer済みの処理能~計量も通知させれる。 ◎ The PerformanceObserver interface can be used to observe the Performance Timeline to be notified of new performance metrics as they are recorded, and optionally buffered performance metrics.
`PerformanceObserver$I ~objは、単に `処理能~観測器@ とも称される。 各 `処理能~観測器$には、次のものが結付けられる: ◎ Each PerformanceObserver has these associated concepts:
- `~callback@
- 作成-時に設定される, `PerformanceObserverCallback$I ~callback。 ◎ A PerformanceObserverCallback set on creation.
- `観測器~buffer@
- `PerformanceEntryList$I ~obj。 初期~時は空とする。 ◎ A PerformanceEntryList object called the observer buffer that is initially empty.
- `~options@
- `PerformanceObserverInit$I 辞書, または ε (なし)。 初期~時は ε とする。 `登録-済み$である間は非 ε になる。 ◎ ↓↓
`PerformanceObserver(callback)@m 構築子の被呼出時には、次を走らせ~MUST:
- %観測器 ~LET 新たな `PerformanceObserver$I ~obj
- %観測器 の`~callback$ ~SET %callback
- ~RET %観測器
callback `PerformanceObserverCallback@I = void ( `PerformanceObserverEntryList$I %entries, `PerformanceObserver$I %observer ); [`Constructor$(`PerformanceObserverCallback$I %callback), `Exposed$=(Window,Worker)] interface `PerformanceObserver@I { void `observe$m(`PerformanceObserverInit$I %options); void `disconnect$m(); `PerformanceEntryList$I `takeRecords$m(); };
注記: 処理能~overheadを最小限に保つためには、~appは,関心のある~event種別のみを申込んで、処理能~dataを観測する必要がなくなったなら,観測器を `disconnect()$m するべきである。 名前( `name$m )による絞込みは~supportされない — それは,暗黙的にすべての~event種別を申込むことになり、可能0ではあるが,大量の~eventを生成することになるので。 ◎ Note ◎ To keep the performance overhead to minimum the application should only subscribe to event types that it is interested in, and disconnect the observer once it no longer needs to observe the performance data. Filtering by name is not supported, as it would implicitly require a subscription for all event types — this is possible, but discouraged, as it will generate a significant volume of events.
3.3.1. `observe(options)@m ~method
この~methodは、此れが`登録-済み$であれば 此れを更新し,そうでなければ此れを `登録-済み$にする。 ◎ The observe() method instructs the user agent to register the observer and\
被呼出時には、次を走らせ~MUST: ◎ must run these steps:
- %~entry種別~list ~LET %options の `entryTypes$d 連列 ◎ Let entry types be options entryTypes sequence.
- %~entry種別~list から~supportされない `entryType$m 名はすべて除去する ⇒ ~UAは、何かが除去された場合は,開発者に通知するべきである — 例えば、除去された種別を~console警告に挙げるのが適切になるであろう。 ◎ Remove all unsupported types from entry types. The user agent SHOULD notify developers if entry types is modified. For example, a console warning listing removed types might be appropriate.
- ~IF[ %~entry種別~list は空である ] ⇒ ~RET ⇒ ~UAは、この手続きが中止されたことを開発者に通知するべきである — 例えば、~console警告が適切になるであろう。 ◎ If the resulting entry types sequence is an empty sequence, abort these steps. The user agent SHOULD notify developers when the steps are aborted to notify that registration has been aborted. For example, a console warning might be appropriate.
- %観測器~list ~LET 此れに`関連する大域~obj$の`処理能~観測器~list$ ◎ ↓
- ~IF[ 此れ ~NIN %観測器~list ] ⇒ %観測器~list に此れを付加する ◎ If the list of registered performance observer objects of relevant global object contains a registered performance observer whose observer is the context object, replace its options, with options. ◎ Otherwise, append a new registered performance observer object to the list of registered performance observer objects of relevant global object, with the context object as observer and options as the options.
- 此れの`~options$ ~SET %options ◎ ↑
- ~IF[ %options の `buffered$d ~member ~NEQ ~T ] ⇒ ~RET ◎ ↓
- %~entry種別~list 内の~EACH( %種別 ) に対し ⇒ 此れに`関連する処理能~entry~buffer$を ( ~NULL, %種別 ) で`絞込んだ$結果 内の ~EACH( %~entry ) に対し ⇒ 此れの`観測器~buffer$に %~entry を付加する ◎ If options' buffered flag is set, for each entry type in entry types sequence: ◎ • Let entries be the PerformanceEntryList object returned by the 4.2 Filter buffer by name and type algorithm with buffer set to relevant performance entry buffer, name set to null and type set to entry type. ◎ • Append entries to the context object's observer buffer.
3.3.1.1. `PerformanceObserverInit^I 辞書
dictionary `PerformanceObserverInit@I { required `sequence$<`DOMString$> `entryTypes$d; `boolean$ `buffered$d = false; };
- `entryTypes@d
- 観測されることになる一連の~entry種別からなる~list。 この~listは、空であっては~MUST_NOT。 ~UAは、この~list内の種別のうち,自身が認識しないものは無視し~MUST。 ◎ A list of entry types to be observed. The list MUST NOT be empty and types not recognized by the user agent MUST be ignored.
- `buffered@d
- ~buffer済み~entryたちも`観測器~buffer$に~queueするべきかどうかを指示する。 ◎ A flag to indicate whether buffered entries should be queued into observer's buffer.
3.3.1.2. `PerformanceObserverEntryList^I ~interface
[`Exposed$=(Window,Worker)] interface `PerformanceObserverEntryList@I { `PerformanceEntryList$I `getEntries$mO(); `PerformanceEntryList$I `getEntriesByType$mO(`DOMString$ %type); `PerformanceEntryList$I `getEntriesByName$mO(`DOMString$ %name, optional `DOMString$ %type); };
- `getEntries()@mO
- 被呼出時には、此れが表現する`観測器~buffer$を ( ~NULL, ~NULL ) で`絞込んだ$結果を返さ~MUST。 ◎ 3.3.3.1 getEntries() method ◎ Returns a PerformanceEntryList object returned by 4.2 Filter buffer by name and type algorithm with buffer set to observer buffer, and name and type set to null.
- `getEntriesByType(type)@mO
- 被呼出時には、此れが表現する`観測器~buffer$を ( ~NULL, %type ) で`絞込んだ$結果を返さ~MUST。 ◎ 3.3.3.2 getEntriesByType() method ◎ Returns a PerformanceEntryList object returned by 4.2 Filter buffer by name and type algorithm with buffer set to observer buffer, name set to null, and type set to type.
- `getEntriesByName(name, type)@mO
- 被呼出時には、此れが表現する`観測器~buffer$を ( %name, %type (省略時は ~NULL) ) で`絞込んだ$結果を返さ~MUST。 ◎ 3.3.3.3 getEntriesByName() method ◎ Returns a PerformanceEntryList object returned by 4.2 Filter buffer by name and type algorithm with buffer set to observer buffer, name set to name, and type set to null if optional entryType is omitted, and type set to type otherwise.
3.3.2. `takeRecords()@m ~method
被呼出時には、次を走らせ~MUST:
- %複製 ~LET 此れの`観測器~buffer$の複製
- 此れの`観測器~buffer$を空にする
- ~RET %複製
3.3.3. `disconnect()@m ~method
被呼出時には、次を走らせ~MUST:
- 此れに`関連する大域~obj$の`処理能~観測器~list$から,此れを除去する
- 此れの`~options$ ~LET ε
- 此れの`観測器~buffer$を空にする
4. 処理
4.1. `PerformanceEntry^I を~queueする
`処理能~entryを~queueする@ ときは、所与の ⇒# %新たな~entry ( `PerformanceEntry$I ~obj), %処理能~entry~bufferに追加する~flag(省略時は ~OFF ) ◎終 に対し,次を走らす:
◎ To queue a PerformanceEntry (new entry) with an optional add to performance entry buffer flag, which is unset by default, run these steps:- %大域~obj ~LET `関連する大域~obj$ 【どの~objに`関連する大域~obj$かは、この~algoを呼出した文脈に依存する。】 ◎ ↓
- %大域~obj の`処理能~観測器~list$内の ~EACH ( `処理能~観測器$ %観測器 ) に対し ⇒ ~IF[ %新たな~entry の `entryType$m 値 ~IN %観測器 の`~options$の `entryTypes^m ] ⇒ %観測器 の`観測器~buffer$に %新たな~entry を付加する ◎ Let interested observers be an initially empty set of PerformanceObserver objects. ◎ For each registered performance observer (observer): ◎ • If observer's PerformanceObserverInit entryTypes includes new entry’s entryType value, append observer to interested observers. ◎ For each observer in interested observers: ◎ • Append new entry to observer buffer.
- ~IF[ %処理能~entry~bufferに追加する~flag ~EQ ~ON ] ⇒ %新たな~entry を %大域~obj の`処理能~entry~buffer$に追加する ◎ If the add to performance entry buffer flag is set, add new entry to the performance entry buffer.
- ~IF[ %大域~obj の`処理能~観測器~task~queue済み~flag$ ~EQ ~ON ] ⇒ ~RET ◎ If the performance observer task queued flag is set, terminate these steps.
- %大域~obj の`処理能~観測器~task~queue済み~flag$ ~SET ~ON ◎ Set performance observer task queued flag.
-
次の下位手続きを走らす`~taskを~queueする$ — この~task用の`~task源$は、 `処理能~時列線~task源@ とする: ◎ Queue a task that consists of running the following substeps. The task source for the queued task is the performance timeline task source.
- %大域~obj の`処理能~観測器~task~queue済み~flag$ ~SET ~OFF ◎ Unset performance observer task queued flag.
- %通知-~list ~LET [ %大域~obj の`処理能~観測器~list$ ]の複製 ◎ Let notify list be a copy of relevant global object's list of registered performance observer objects.
-
%通知-~list 内の~EACH ( `処理能~観測器$ %観測器 ) に対し: ◎ For each PerformanceObserver object po in notify list, run these steps:
- ~IF[ %観測器 の`観測器~buffer$は空である ] ⇒ ~CONTINUE ◎ ↓
- %~entryたち ~LET %観測器 の`観測器~buffer$の複製 ◎ Let entries be a copy of po’s observer buffer.
- %観測器 の`観測器~buffer$を空にする ◎ Empty po’s observer buffer.
-
次を渡して %観測器 の`~callback$を~callする ⇒# 引数~list « %~entryたち, %観測器 », `~callback this 値$ %観測器
この段にて例外が投出された場合は、その`例外を報告する$。
◎ If entries is non-empty, call po’s callback with entries as first argument and po as the second argument and callback this value. If this throws an exception, report the exception.
`処理能~時列線~task源$用の`~task~queue$は、低優先度の~queueである — ~UAは、処理能~監視~codeの影響0を最小限に抑えるため,可能0なら遊休中に処理するべきである。 ◎ The performance timeline task queue is a low priority queue that, if possible, should be processed by the user agent during idle periods to minimize impact of performance monitoring code.
4.2. ~bufferを ( %名前, %種別 ) で絞込む
この~algoは、所与の:
- %~buffer ( `PerformanceEntry$I ~objの~list)
- %名前 (文字列, 省略時は ~NULL)
- %種別 (文字列, 省略時は ~NULL)
に対し,次を走らせた結果の `PerformanceEntryList$I ~objを返す:
- %~list ~LET 下に与える下位手続きを走らせた結果
- `~entry~obj~list@V ~LET %~list を その各~objの `startTime$m の時系列順に整列した結果の~list — `startTime$m が同じ~objどうしの順序は指定されない
- ~RET %~list を包含する新たな `PerformanceEntryList$I ~obj
上で利用される下位手続きは、次を走らす:
◎ Given a buffer and optional name and type string values this algorithm returns a PerformanceEntryList object that contains a list of PerformanceEntry objects sorted in chronological order with respect to startTime; objects with the same startTime have unspecified ordering.- %~list ~LET 空~list ◎ Let the list of entry objects be the empty PerformanceEntryList.
-
%~buffer 内の ~EACH ( `PerformanceEntry$I ~obj `~entry~obj@V ) に対し: ◎ For each PerformanceEntry object (entryObject) in the buffer, in chronological order with respect to startTime:
- ~IF[ %名前 ~NIN { ~NULL, `~entry~obj$V の `name$m 属性~値 ) ] ⇒ ~CONTINUE ◎ If name is not null and entryObject's name attribute does not match name in a case-sensitive manner, go to next entryObject.
- ~IF[ %種別 ~NEQ { ~NULL, `~entry~obj$V の `entryType$m 属性~値 } ] ⇒ ~CONTINUE ◎ If type is not null and entryObject's type attribute does not match type in a case-sensitive manner, go to next entryObject.
- %~list に `~entry~obj$V を追加する ◎ Add entryObject to the list of entry objects.
- ~RET %~list ◎ Return the list of entry objects.
5. 依存関係
【 他の仕様にて定義される用語。 以下、この節の内容は省略する。 】 ◎ This specification depends on the following interfaces, attributes, concepts, and terms which are defined in their linked specifications.
5. ~privacyと保安
この仕様は、 `HR-TIME-2$r に定義された `Performance$I ~interfaceを拡張し,`処理能時列線$[ に~entryを~queueする/から~entryを取得する ]ための~methodを供する。 高分解能の計時~情報を公開することによる[ ~privacy/保安 ]上の考慮点については、 `HR-TIME-2$r を参照されたし。 ◎ This specification extends the Performance interface defined by [HR-TIME-2] and provides methods to queue and retrieve entries from the performance timeline. Please refer to [HR-TIME-2] for privacy and security considerations of exposing high-resoluting timing information.