User Timing

概要

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

この文書のステータス

この節は、公開時点におけるこの文書のステータスを説明するものです。現在の W3C 公開物と、この技術報告書の最新リビジョンの一覧は、 W3C 標準および草案インデックスで確認できます。

この User Timing 仕様は、[USER-TIMING-2] を置き換えることを意図しており、以下を含みます:

任意のタイムスタンプにわたってマークと測定を実行する機能。

マークと測定とともに任意のメタデータを報告するためのサポート。

この文書は、Web Performance Working Group により、 Recommendation track を用いた Candidate Recommendation Draft として公開されました。

Candidate Recommendation としての公開は、 W3C およびそのメンバーによる承認を意味するものではありません。Candidate Recommendation Draft は、ワーキンググループが後続の Candidate Recommendation Snapshot に含めることを意図している、以前の Candidate Recommendation からの変更を統合します。

これは草案文書であり、いつでも他の文書によって更新、置換、または廃止される可能性があります。作業中の文書以外のものとしてこの文書を引用することは不適切です。

この文書は、 W3C Patent Policy の下で運営されているグループによって作成されました。 W3C は、そのグループの成果物に関連して行われた特許開示の公開一覧を維持しています。そのページには、特許を開示するための手順も含まれています。ある個人が、 Essential Claim(s) を含むとその個人が考える特許について実際の知識を有している場合、その情報を W3C Patent Policy の第 6 節に従って開示しなければなりません。

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();

element.addEventListener("click", e => { const component = getComponent(element); fetch(component.url).then(() => { element.textContent = "Updated"; const updateMark = performance.mark("update_component", { detail: {component: component.name}, }); performance.measure("click_to_update_component", { detail: {component: component.name}, start: e.timeStamp, end: updateMark.startTime, }); }); });

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

存储带有关联名称的时间戳（一个“mark”）。它 MUST 运行这些步骤：

运行 PerformanceMark 构造器，并令 entry 为新创建的对象。
排队 entry。
将 entry 添加到 performance entry buffer。
返回 entry。

detail: 要包含在标记中的元数据。
startTime: 要用作标记时间的时间戳。

移除带有关联名称的已存储时间戳。它 MUST 运行这些步骤：

如果省略了 markName，则从 PerformanceMark 对象中移除所有位于 performance entry buffer 中的对象。
否则，移除 PerformanceMark 对象中列在 performance entry buffer 中且其 name 是 markName 的所有对象。
返回 undefined。

存储两个标记之间的 DOMHighResTimeStamp 持续时间，并附带关联名称（一个“measure”）。它 MUST 运行这些步骤：

如果 startOrMeasureOptions 是一个 PerformanceMeasureOptions 对象，并且 start、end、duration 和 detail 中至少有一个存在，则运行以下检查：
1. 如果给定了 endMark，则抛出一个 TypeError。
2. 如果 startOrMeasureOptions 的 start 和 end 成员都被省略，则抛出一个 TypeError。
3. 如果 startOrMeasureOptions 的 start、duration 和 end 成员全部存在，则抛出一个 TypeError。
按如下方式计算 end time：
1. 如果给定了 endMark，则令 end time 为传入 endMark 运行 convert a mark to a timestamp 算法所返回的值。
2. 否则，如果 startOrMeasureOptions 是一个 PerformanceMeasureOptions 对象，并且如果其 end 成员存在，则令 end time 为传入 startOrMeasureOptions 的 end 运行 convert a mark to a timestamp 算法所返回的值。
3. 否则，如果 startOrMeasureOptions 是一个 PerformanceMeasureOptions 对象，并且如果其 start 和 duration 成员都存在：
  1. 令 start 为传入 start 运行 convert a mark to a timestamp 算法所返回的值。
  2. 令 duration 为传入 duration 运行 convert a mark to a timestamp 算法所返回的值。
  3. 令 end time 为 start 加上 duration。
4. 否则，令 end time 为 Performance 对象的 now() 方法将会返回的值。
按如下方式计算 start time：
1. 如果 startOrMeasureOptions 是一个 PerformanceMeasureOptions 对象，并且如果其 start 成员存在，则令 start time 为传入 startOrMeasureOptions 的 start 运行 convert a mark to a timestamp 算法所返回的值。
2. 否则，如果 startOrMeasureOptions 是一个 PerformanceMeasureOptions 对象，并且如果其 duration 和 end 成员都存在：
  1. 令 duration 为传入 duration 运行 convert a mark to a timestamp 算法所返回的值。
  2. 令 end 为传入 end 运行 convert a mark to a timestamp 算法所返回的值。
  3. 令 start time 为 end 减去 duration。
3. 否则，如果 startOrMeasureOptions 是一个 DOMString，则令 start time 为传入 startOrMeasureOptions 运行 convert a mark to a timestamp 算法所返回的值。
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 的持续时间。所得持续时间值 MAY 为负数。
按如下方式设置 entry 的 detail 属性：
1. 如果 startOrMeasureOptions 是一个 PerformanceMeasureOptions 对象，并且 startOrMeasureOptions 的 detail 成员存在：
  1. 令 record 为对 startOrMeasureOptions 的 detail 调用 StructuredSerialize 算法的结果。
  2. 将 entry 的 detail 设置为以 record 和当前 realm 调用 StructuredDeserialize 算法的结果。
2. 否则，将其设置为 null。
排队 entry。
将 entry 添加到 performance entry buffer。
返回 entry。

detail: 要包含在度量中的元数据。
start: 要用作开始时间的时间戳，或要用作开始标记的字符串。
duration: 开始时间与结束时间之间的持续时间。
end: 要用作结束时间的时间戳，或要用作结束标记的字符串。

移除带有关联名称的已存储时间戳。它 MUST 运行这些步骤：

如果省略了 measureName，则移除 PerformanceMeasure 对象中位于 performance entry buffer 中的所有对象。
否则，移除 PerformanceMeasure 对象中列在 performance entry buffer 中且其 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 字典复制而来的）。

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

User Timing

概要

この文書のステータス

1. 简介

2. 一致性

3. User Timing

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. User Timing

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`