本规范描述了一种 API，允许 Web 应用程序控制采样分析器，以 测量客户端 JavaScript 的执行时间。

定义

样本是对给定时间点 瞬时执行状态的描述。每个样本都与一个堆栈相关联。

堆栈是一个帧列表，必须按照 从最外层帧到最内层帧的顺序依次排列。

帧是堆栈上下文中的一个元素， 包含有关当前执行状态的信息。

分析会话

分析会话是样本的抽象生产者。每个会话具有：

1. 一个状态，其值为 {started, paused, stopped} 之一。
2. 一个采样间隔，定义为会话获取样本的周期。

   不要求用户代理以此频率获取样本。但是，建议 优先按照此频率进行采样，以 生成质量更高的跟踪数据。

3. 一个要分析的代理。
4. 一个要分析的领域。
5. 一个时间原点，样本的时间戳以它为 参照进行测量。
6. 一个样本缓冲区大小限制。
7. 一个存储已捕获样本的 ProfilerTrace。

应当支持同一页面上的多个分析会话。

处理模型

要在给定一个分析会话的情况下获取样本，请执行以下步骤：

1. 如果 ProfilerTrace.samples 的长度大于或等于与分析会话关联的样本缓冲区大小 限制，则向关联的 Profiler 触发一个类型为 samplebufferfull 的新事件，将状态转换为 stopped， 然后返回。
2. 令 sample 为一个新的 ProfilerSample。
3. 将 sample 的 ProfilerSample.timestamp 属性设置为相对于 分析会话的时间原点的当前高分辨率时间。
4. 令 stack 为与分析会话的代理关联的执行上下文 堆栈。
5. 将 sample 的 ProfilerSample.stackId 属性设置为对 stack 运行获取堆栈 ID算法的结果。
6. 将 sample 添加到与会话的 ProfilerTrace 关联的 ProfilerTrace.samples 中。

要在给定绑定到 stack 的执行上下文堆栈的情况下获取堆栈 ID，请执行 以下步骤：

1. 如果 stack 为空，则返回 undefined。
2. 令 head 为 stack 的顶部元素，令 tail 为从 stack 中移除其顶部元素后剩余的部分。
3. 令 parentId 为以 tail 递归调用获取堆栈 ID的结果。
4. 令 frameId 为对 head 调用获取帧 ID的结果。
5. 如果 frameId 为 undefined，则返回 parentId。
6. 令 profilerStack 为一个新的 ProfilerStack，其 ProfilerStack.frameId 等于 frameId，且 ProfilerStack.parentId 等于 parentId。
7. 返回以 profilerStack 和 ProfilerTrace.stacks 运行获取元素 ID的结果。

要在给定绑定到 context 的执行 上下文的情况下获取帧 ID，请执行以下步骤：

1. 如果与 context 关联的[= realm =]与分析会话关联的领域 不匹配，则返回 undefined。
2. 令 instance 等于与 context 关联的函数 实例。
3. 令 scriptOrModule 等于与 context 关联的 ScriptOrModule。
4. 令 |attributedScriptOrModule : ScriptOrModule| 等于运行以下 算法的结果：
   1. 如果 |scriptOrModule| 非空，则返回 |scriptOrModule|。
   2. 如果 |instance| 是内置函数对象，则返回包含 调用 |instance| 的函数的 ScriptOrModule。

      上述逻辑旨在确保无法访问的 脚本所调用的内置函数不会暴露在跟踪数据中，方法是使用调用 它们的 ScriptOrModule 进行归属。

      “包含调用 |instance| 的函数的 ScriptOrModule” 应当得到更严格的定义。我们可以利用堆栈中最顶层且 定义了 ScriptOrModule 的执行上下文来提供此信息，但这并不理想—— 理论上可能存在其他机制，将内置函数加入执行 上下文堆栈，在这种情况下归属将无效。

   3. 否则，返回 null。
5. 如果 |attributedScriptOrModule| 为 null，则返回 undefined。
6. 令 |attributedScript : Script| 为从 |attributedScriptOrModule|.[[\HostDefined]] 获取的[= script =]。
7. 如果 |attributedScript| 是[= classic script =]，并且其静默 错误布尔值等于 true，则返回 undefined。

   此检查确保我们不会包含通过 CORS 跨源响应提供的跨源脚本中的堆栈帧。我们可能需要考虑重命名静默错误，以便更好地反映 此用例。

8. 令 frame 为一个新的 ProfilerFrame。
9. 将 frame 的 ProfilerFrame.name 设置为与 |instance| 关联的函数实例名称。
10. 如果 |scriptOrModule| 非空：
    1. 令 script 为从 scriptOrModule.[[\HostDefined]] 获取的脚本。
    2. 令 resourceString 等于 script 的基 URL。
    3. 将 ProfilerFrame.resourceId 设置为以 resourceString 和 ProfilerTrace.resources 运行获取元素 ID的结果。
    4. 将 frame 的 ProfilerFrame.line 设置为 |script| 中定义 instance 的行的从 1 开始的索引。
    5. 将 frame 的 ProfilerFrame.column 设置为 |script| 中定义 instance 的列的从 1 开始的索引。
11. 返回以 frame 和 ProfilerTrace.frames 运行获取元素 ID的结果。

要为 list 中的 item 获取元素 ID，请执行以下步骤：

1. 如果 list 中存在与 item 按分量相等的元素，则返回其索引。
2. 否则，将 item 追加到 list 的末尾，并返回其索引。

Profiler 接口

      [Exposed=(Window, Worker)]
      interface Profiler : EventTarget {
        readonly attribute DOMHighResTimeStamp sampleInterval;
        readonly attribute boolean stopped;

        constructor(ProfilerInitOptions options);
        Promise<ProfilerTrace> stop();
      };
      

每个 Profiler 必须恰好与一个分析会话关联。

sampleInterval 属性必须反映关联的分析会话的采样间隔，并以 DOMHighResTimeStamp 表示。

当且仅当分析会话的状态为 stopped 时，stopped 属性必须为 true。

ProfilerTrace 字典

      typedef DOMString ProfilerResource;

      dictionary ProfilerTrace {
        required sequence<ProfilerResource> resources;
        required sequence<ProfilerFrame> frames;
        required sequence<ProfilerStack> stacks;
        required sequence<ProfilerSample> samples;
      };
      

resources 属性必须返回由获取 样本算法设置的 ProfilerResource 列表。

frames 属性必须返回由获取样本 算法设置的 ProfilerFrame 列表。

stacks 属性必须返回由获取样本 算法设置的 ProfilerStack 列表。

samples 属性必须返回由获取样本 算法设置的 ProfilerSample 列表。

受 V8 跟踪 事件格式 和 Gecko 分析格式的启发， 此表示形式旨在易于并能够高效地序列化。

        dictionary ProfilerSample {
          required DOMHighResTimeStamp timestamp;
          unsigned long long stackId;
        };
        

        dictionary ProfilerStack {
          unsigned long long parentId;
          required unsigned long long frameId;
        };
        

        dictionary ProfilerFrame {
          required DOMString name;
          unsigned long long resourceId;
          unsigned long long line;
          unsigned long long column;
        };
        

ProfilerInitOptions 字典

      dictionary ProfilerInitOptions {
        required DOMHighResTimeStamp sampleInterval;
        required unsigned long maxBufferSize;
      };
      

ProfilerInitOptions 必须支持以下字段：

• sampleInterval 是应用程序期望的采样间隔。此值必须 大于或等于零。
• maxBufferSize 是期望的样本缓冲区大小限制，以样本数表示。

文档策略

本规范在文档 策略中定义了配置 点，用于控制分析能力和初始化行为。

自动化

为了实现用户代理自动化和应用程序测试，本文档定义了以下 [[WebDriver]] 扩展命令。