WebRTC 诊断日志 API

1. 简介

WebRTC 诊断日志 API 为 Web 应用提供了一个编程接口，用于开始、结束和取消收集由用户代理执行的 WebRTC 相关操作的内部诊断日志。 这些诊断日志绝不会暴露给应用。相反，它们由用户代理 存储在本地，并由用户控制。 用户代理还可以将诊断日志上传到由 用户代理决定的端点。 收集、存储和上传诊断日志需要用户明确 授权，并且应用永远无法知道这些操作是否 成功。诊断日志的内容也是一种实现 细节。 此 API 旨在支持以下用例：

• 应用请求收集日志，并将其存储在本地。 开发者可以使用这些日志来帮助诊断应用中的错误。 应用的用户可以将这些日志提供给 应用开发者，以帮助修复错误或以其他方式改进 应用。组织可以从其用户处收集这些日志，以 诊断错误或进行改进。

• 应用可以请求与用户代理供应商共享日志。 当应用开发者怀疑用户 代理中存在错误，并希望提供日志来帮助用户代理开发者修复 该错误时，这很有用。为了支持此用例，API 会返回一个 UUID，该 UUID 可以包含 在错误报告中，以标识已上传的诊断日志。此机制允许 用户授权向用户代理供应商公开诊断日志， 但不允许向应用公开诊断日志。

2. 安全和隐私

这些诊断日志收集有关用户代理为了实现 WebRTC 相关功能而执行的内部操作的信息。这些诊断日志 可能包含未暴露给 Web 应用的信息，因此， API 不得以任何方式向 Web 应用公开这些日志。在获得用户授权的 前提下，可以与用户代理供应商共享日志（例如，通过带外上传）， 以便使用这些日志协助修复 用户代理错误或对用户代理进行其他改进。

收集、存储和上传诊断日志需要用户明确 授权。此授权的具体机制属于 实现细节。实现授权的方式包括但不限于 专用 UI、设置、企业策略、提示或 它们的组合。授权可以仅限于特定源。 这些授权的状态绝不会暴露给应用。因此， 这些 API 不保证操作成功。

3. 对 RTCPeerConnection 接口的扩展

该 API 作为 RTCPeerConnection 接口上的一组静态方法公开。

[
  Exposed=Window,
  SecureContext
] partial interface RTCPeerConnection {
  static Promise<DOMString> startDiagnosticLogging(optional RTCStartDiagnosticLoggingOptions options = {});
  static Promise<undefined> finishDiagnosticLogging(optional RTCFinishDiagnosticLoggingOptions options = {});
  static Promise<undefined> cancelDiagnosticLogging();
};

3.1. 字典

RTCStartDiagnosticLoggingOptions 和 RTCFinishDiagnosticLoggingOptions 为日志记录会话提供 配置。

dictionary RTCDiagnosticLoggingOptions {
  record<DOMString, DOMString> metadata;
};

dictionary RTCStartDiagnosticLoggingOptions : RTCDiagnosticLoggingOptions {
  boolean allowUpload = false;
};

dictionary RTCFinishDiagnosticLoggingOptions : RTCDiagnosticLoggingOptions {
};

3.2. 内部槽

令相关全局对象具有一个 [[RTCDiagnosticLoggingSessionId]] 内部槽，并将其初始化为 null。

3.3. 方法

3.3.1. startDiagnosticLogging(options)

startDiagnosticLogging(options) 方法 必须 运行以下步骤：

1. 令 allowUpload 为 options 的 allowUpload 成员。

2. 令 metadata 为 options 的 metadata 成员。

3. 如果 metadata 的大小超过 5 个条目，或者 metadata 中的任何键或值 超过 100 个字符，则返回一个以 TypeError 拒绝的 promise。

4. 令 p 为一个新的 promise。

5. 并行地执行以下步骤：

   1. 令 uuid 为一个通用唯一 ID。

   2. 令 doc 为相关全局对象的关联文档。

   3. 如果 doc 的浏览上下文不是顶级浏览上下文，则使用 uuid 兑现 p 并中止这些 步骤。

   4. 如果 [[RTCDiagnosticLoggingSessionId]] 内部槽不为 null，则使用 uuid 兑现 p 并中止这些步骤。

   5. 将 uuid 存储在 [[DiagnosticLoggingSessionId]] 内部槽中。

   6. 使用 uuid 兑现 p。

   7. 开始一个以 uuid 标识的 WebRTC 内部活动日志记录会话

6. 返回 p。

日志记录会话开始后，在 p 兑现之后，用户代理可以记录由 doc 或 其后代文档生成的任何 WebRTC 相关活动。 日志可以包含 metadata 或从中派生的信息。 如果 allowUpload 为 true，则只要用户 已授权，并且尚未使用 cancelDiagnosticLogging 方法取消日志记录会话，就可以通过由实现定义的机制与用户代理供应商共享记录的数据。 日志记录会话由 uuid 标识，这意味着所有记录的数据都可以使用 uuid 在内部引用。

3.3.2. finishDiagnosticLogging(options)

cancelDiagnosticLogging(options) 方法必须 运行以下步骤：

1. 令 metadata 为 options 的 metadata 成员。

2. 如果 metadata 的大小超过 5 个条目，或者 metadata 中的任何键或值 超过 100 个字符，则返回一个以 TypeError 拒绝的 promise。

3. 令 p 为一个新的 promise。

4. 并行地执行以下步骤：

   1. 如果 [[RTCDiagnosticLoggingSessionId]] 内部槽为 null，则使用 undefined 兑现 p 并中止这些步骤。

   2. 停止由 [[RTCDiagnosticLoggingSessionId]] 标识的日志记录会话。

   3. 将 [[RTCDiagnosticLoggingSessionId]] 设置为 null。

   4. 使用 undefined 兑现 p。

5. 返回 p。

在 p 兑现之后，用户代理不得记录由 doc 或 其后代文档生成的任何 WebRTC 相关活动。日志可以 包含 metadata 或从中派生的信息。只要用户已授权， 并且日志记录会话初始化时将 allowUpload 设置为 true，用户代理就可以使用由实现定义的机制，通过带外方式与用户代理供应商共享 记录的数据。

3.3.3. cancelDiagnosticLogging()

cancelDiagnosticLogging() 方法必须运行以下 步骤：

1. 令 p 为一个新的 promise。

2. 并行地执行以下步骤：

   1. 令 uuid 为 [[RTCDiagnosticLoggingSessionId]] 内部槽的值。

   2. 取消由 [[RTCDiagnosticLoggingSessionId]] 标识的日志记录会话。

   3. 将 [[RTCDiagnosticLoggingSessionId]] 设置为 null。

   4. 使用 undefined 兑现 p。

3. 返回 p。

在 p 兑现后：

• 用户代理不得记录由 doc 或其后代 文档生成的任何 WebRTC 相关活动。

• 用户代理必须移除与由 uuid 标识的会话相关联的所有已记录数据。

• 用户代理不得与用户代理供应商共享任何与由 uuid 标识的日志记录会话相关联的数据。