用户计时 第 2 级

W3C 推荐标准

此版本：
https://www.w3.org/TR/2019/REC-user-timing-2-20190226/
最新发布版本：
https://www.w3.org/TR/user-timing-2/
用户计时的最新版本：
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 (微软公司) (截至 2014 年 2 月)
Zhiheng Wang (Google Inc.) (截至 2013 年 7 月)
Anderson Quach (微软公司) (截至 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.

摘要

本规范定义了一个接口，帮助 Web 开发人员通过提供高精度时间戳来衡量其应用程序的性能。

本文档状态

本节描述了本文档在发布时的状态。其他文档可能会取代此文档。当前 W3C 出版物的列表及此技术报告的最新修订版可在 W3C 技术报告索引上找到：https://www.w3.org/TR/。

用户计时第 2 级旨在取代第 1 版 [USER-TIMING]，并包括：

本文档由 Web 性能工作组 作为建议标准发布。

GitHub 问题 是讨论此规范的首选方式。 或者，您可以将评论发送到我们的邮件列表。 请发送至 public-web-perf@w3.org (存档) 并在电子邮件主题的开头添加 [UserTiming]。

请参阅工作组的 实现报告。

本文档已经经过 W3C 成员、软件开发人员以及其他 W3C 小组和相关方的审查，并已得到 W3C 总监的认可为 W3C 推荐标准。它是一个稳定的文档，可以用作参考资料或被其他文档引用。 W3C 在制定推荐标准时的作用是引起对该规范的关注并推动其广泛部署。这提高了 Web 的功能性和互操作性。

本文档由一个根据 W3C 专利政策 运营的小组制作。 W3C 维护了一个 公开的专利披露列表，该列表列出了与小组交付物相关的任何专利披露；该页面还包括披露专利的说明。任何了解包含 必要声明 的专利的个人必须根据 W3C 专利政策第 6 节 披露信息。

本文档受 2018 年 2 月 1 日 W3C 过程文档 管理。

1. 介绍

本节为非规范性内容。

Web 开发者需要评估和理解其应用程序的性能特征。尽管 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] 定义了两种用于检索记录的计量机制：getEntries() 和 getEntriesByType() 方法，以及 PerformanceObserver 接口。前者适用于在单个时间点按名称检索特定指标的情况，而后者针对希望在新指标可用时接收通知的情况进行了优化。

2. 符合性

除了标记为非规范性的部分，本规范中的所有作者指南、图表、示例和注释均为非规范性内容。 本规范中的其他所有内容都是规范性的。

关键字 MAY 和 MUST 应按照 [RFC2119] 中的说明进行解释。

一些符合性要求以对属性、方法或对象的要求形式表达。这些要求应解释为对用户代理的要求。

本规范中的IDL片段必须按照Web IDL规范中所述的方式解释为符合性IDL片段。 [WEBIDL]

3. 用户计时

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() 方法

存储带有相关名称（"mark"）的时间戳。它 必须 按照以下步骤运行：

  1. 如果 全局对象 是一个 Window 对象，并且 markName 使用的名称与 PerformanceTiming 接口中的某个 只读属性 相同， 抛出 一个 SyntaxError。
  2. 创建一个新的 PerformanceMark 对象（entry）。
  3. 将 entry 的 name 属性设置为 markName。
  4. 将 entry 的 entryType 属性设置为 DOMString "mark"。
  5. 将 entry 的 startTime 属性设置为通过 Performance 对象的 now() 方法返回的值。
  6. 将 entry 的 duration 属性设置为 0。
  7. 排队 entry。
  8. 将 entry 添加到 性能条目缓冲区。
  9. 返回 undefined。

3.1.2 clearMarks() 方法

删除带有相关名称的已存储时间戳。它 必须 按照以下步骤运行：

  1. 如果省略了 markName，则从 PerformanceMark 对象中删除所有条目，并从 性能条目缓冲区中删除。
  2. 否则，删除所有 PerformanceMark 对象，其名称与 markName 匹配，并列在 性能条目缓冲区 中。
  3. 返回 undefined。

3.1.3 measure() 方法

存储两个标记之间的 DOMHighResTimeStamp 持续时间以及相关的名称（“measure”）。它 必须 按照以下步骤运行：

  1. 令 end time 为 0。
  2. 如果省略了 endMark，则将 end time 设置为通过 Performance 对象的 now() 方法返回的值。否则：
    1. 如果 endMark 的名称与 PerformanceTiming 接口中的某个只读属性 相同，使用 endMark 的值运行 将名称转换为时间戳 算法，并将 name 设置为 endMark。
    2. 否则，将 end time 设置为在 PerformanceMark 对象的 startTime 属性中， 其名称与 endMark 的值匹配的最近一次出现的条目。如果未找到匹配的条目， 抛出 一个 SyntaxError。
  3. 如果省略了 startMark，则将 start time 设置为 0。否则：
    1. 如果 startMark 的名称与 PerformanceTiming 接口中的某个只读属性 相同，使用 startMark 的值运行 将名称转换为时间戳 算法，并将 name 设置为 startMark。
    2. 否则，将 start time 设置为在 PerformanceMark 对象的 startTime 属性中， 其名称与 startMark 的值匹配的最近一次出现的条目。如果未找到匹配的条目， 抛出 一个 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 的持续时间。所得的持续时间值 可以 为负值。
  9. 排队 entry。
  10. 将 entry 添加到 性能条目缓冲区。
  11. 返回 undefined。

3.1.4 clearMeasures() 方法

删除带有相关名称的已存储时间戳。它 必须 按照以下步骤运行：

  1. 如果省略了 measureName，则从 PerformanceMeasure 对象中删除所有条目，并从 性能条目缓冲区中删除。
  2. 否则，删除所有 PerformanceMeasure 对象，其名称与 measureName 匹配，并列在 性能条目缓冲区 中。
  3. 返回 undefined。

3.2 PerformanceMark 接口

PerformanceMark 接口还通过 performance.mark 方法将创建的标记暴露给 性能时间轴。 

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

PerformanceMark 接口扩展了 PerformanceEntry 接口的以下属性：

name 属性必须返回标记的名称。

entryType 属性必须返回 DOMString "mark"。

startTime 属性必须返回带有标记时间值的 DOMHighResTimeStamp。

duration 属性必须返回值为 0 的 DOMHighResTimeStamp。

3.3 PerformanceMeasure 接口

PerformanceMeasure 接口还通过 performance.measure 方法将创建的测量暴露给 性能时间轴。 

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

PerformanceMeasure 接口扩展了 PerformanceEntry 接口的以下属性：

name 属性必须返回测量的名称。

entryType 属性必须返回 DOMString "measure"。

startTime 属性必须返回带有测量起始标记的 DOMHighResTimeStamp。

duration 属性必须返回测量的持续时间的 DOMHighResTimeStamp。

4. 处理

实现用户计时API的用户代理必须执行以下步骤：

  1. 运行 注册性能条目类型 算法，输入为 "mark"。
  2. 运行 注册性能条目类型 算法，输入为 "measure"。

4.1 将 name 转换为 timestamp

要将 一个名称转换为 时间戳，假设 name 是 只读属性，位于 PerformanceTiming 接口中，请按照以下步骤操作：

  1. 如果 全局对象 不是 Window 对象，抛出 SyntaxError。
  2. 如果 name 是 navigationStart，返回 0。
  3. 将 startTime 设置为 navigationStart 在 PerformanceTiming 接口中的值。
  4. 将 endTime 设置为 name 在 PerformanceTiming 接口中的值。
  5. 如果 endTime 是 0，抛出 InvalidAccessError。
  6. 返回 endTime 减去 startTime 的结果。
注意

PerformanceTiming 接口在 [NAVIGATION-TIMING] 中定义，现在被视为过时。支持使用 PerformanceTiming 接口中的名称以保持向后兼容，但没有计划在未来将此功能扩展到 [NAVIGATION-TIMING-2] 中定义的 PerformanceNavigationTiming 接口（或其他接口）中的名称。

5. 隐私与安全

本节为非规范性。

本规范中定义的接口暴露了页面上特定JavaScript活动的潜在敏感计时信息。 有关暴露高分辨率计时信息的隐私和安全考虑，请参阅 [HR-TIME-2]。

由于Web平台的设计原则是，页面上包含的任何脚本与同一页面上包含的任何其他脚本拥有相同的访问权限， 无论这些脚本的来源如何，本规范定义的接口不对记录或检索已记录的计时信息施加任何限制 - 即页面上包含的任何脚本记录的用户计时标记或测量可以被同一页面上运行的任何其他脚本读取，无论其来源如何。

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]
High Resolution Time Level 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 第二版。Steve Faulkner；Arron Eicholz；Travis Leithead；Alex Danilo。W3C。2017年10月3日。W3C推荐标准。URL: https://www.w3.org/TR/html51/
[NAVIGATION-TIMING]
导航计时。Zhiheng Wang。 W3C。2012年12月17日。W3C推荐标准。URL: https://www.w3.org/TR/navigation-timing/
[PERFORMANCE-TIMELINE-2]
性能时间线 第2级。Ilya Grigorik。W3C。2019年1月10日。W3C工作草案。URL: https://www.w3.org/TR/performance-timeline-2/
[RFC2119]
用于在RFC中指示需求级别的关键字。S. Bradner。IETF。1997年3月。当前最佳实践。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国际。URL: https://tc39.github.io/ecma262/
[NAVIGATION-TIMING-2]
导航计时 第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]
用户计时。Jatinder Mann；Zhiheng Wang；Anderson Quach。W3C。2013年12月12日。W3C推荐标准。URL: https://www.w3.org/TR/user-timing/