WebRTC 诊断日志 API

1. 简介

WebRTC 诊断日志 API 为 Web 应用程序提供了一个编程接口，用于开始、完成和丢弃用户代理执行的 WebRTC 相关操作的内部诊断 日志收集。 这些诊断日志绝不会暴露给应用程序。相反，它们会 存储在由用户控制的位置，并且可以与 用户代理供应商共享。 诊断日志的收集和存储需要用户明确 授权，并且应用程序永远不会知道诊断日志记录 操作是成功还是失败。诊断日志的内容也是 实现细节。 此 API 旨在支持的用例如下：

• 应用程序请求收集日志。这些日志可由 开发者用于帮助诊断应用程序中的错误。应用程序的 用户可以将这些日志提供给应用程序开发者，以便 帮助修复错误或以其他方式改进应用程序。组织可以 从其用户处收集这些日志，以诊断错误或改进 内部 WebRTC 部署。

• 用户可以将日志配置为与用户代理供应商共享。这在 应用程序开发者怀疑用户代理中存在错误 并希望提供日志以帮助用户代理开发者修复该 错误时非常有用。为了支持此用例，API 会返回一个 UUID，可用于 标识诊断日志记录会话（例如，在错误报告中）。此 机制不允许将诊断日志暴露给应用程序。

2. 安全与隐私

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

诊断日志的收集、存储和上传需要用户明确 授权。此授权的具体机制 由实现定义。实现授权的一些选项 包括但 不限于专用 UI、配置文件、企业策略、 提示，或这些方式的组合。授权可以仅限于特定 源。这些授权的状态绝不会暴露给应用程序。 因此，这些 API 不对成功作出任何保证。

3. 对 RTCPeerConnection 接口的扩展

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

[
  Exposed=Window
] partial interface RTCPeerConnection {
  static DOMString startDiagnosticLogging(optional RTCDiagnosticLoggingOptions options = {});
  static undefined stopDiagnosticLogging();
  static undefined cancelDiagnosticLogging();
};

3.1. 字典

RTCDiagnosticLoggingOptions 为日志记录 会话提供配置。

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

3.2. 内部槽

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

3.3. 方法

3.3.1. startDiagnosticLogging(options)

startDiagnosticLogging(options) 方法 尝试启动一个诊断日志记录会话。

调用此方法时，用户代理必须运行以下步骤：

1. 令 options 为此方法的第一个参数。

2. 令 metadata 为 options 的 metadata 成员。

3. 如果 metadata 的 大小 大于 5，或者如果任意 条目 key → value 在 metadata 中的 长度 大于 100， 则返回一个 拒绝 原因为 TypeError 的期约。

4. 如果 [[RTCDiagnosticLoggingSessionId]] 内部 槽不为 null，则 抛出 一个 "InvalidStateError" DOMException。

5. 令 sesssionId 为随机生成的 UUID [rfc4122]。为避免 指纹识别，实现应该在生成 UUID 时使用 RFC 4122 第 4.4 节中的形式。

6. 将 [[RTCDiagnosticLoggingSessionId]] 设置为 sessionId。

7. 并行地，启动一个记录内部 WebRTC 活动的日志记录会话， 使用 metadata 作为上下文。使用 sessionId 标识该日志记录会话。

8. 返回 sessionId。

一旦日志记录会话启动，用户代理 可以记录任何与 WebRTC 相关的 活动。该日志记录会话由 sessionId 标识，该标识符可用于 引用日志（例如，在缺陷报告中）。

3.3.2. stopDiagnosticLogging()

stopDiagnosticLogging() 方法结束 一个正在进行的诊断日志记录会话。

调用此方法时，用户代理 必须运行以下步骤：

1. 如果 [[RTCDiagnosticLoggingSessionId]] 内部 槽为 null，则 抛出 一个 "InvalidStateError" DOMException。

2. 令 sessionId 为 [[RTCDiagnosticLoggingSessionId]]。

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

4. 并行地，停止由以下值标识的日志记录会话： [[RTCDiagnosticLoggingSessionId]]。

一旦日志记录会话停止，用户代理不得记录任何与 WebRTC 相关的 活动。

3.3.3. discardDiagnosticLogging()

discardDiagnosticLogging() 方法取消一个 正在进行的诊断日志记录会话，并删除与该会话关联的 所有已记录数据。

调用此方法时，用户代理 必须运行以下步骤：

1. 如果 [[RTCDiagnosticLoggingSessionId]] 内部 槽为 null，则 抛出 一个 "InvalidStateError" DOMException。

2. 令 sessionId 为 [[RTCDiagnosticLoggingSessionId]]。

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

4. 并行地，取消由以下值标识的日志记录会话： [[RTCDiagnosticLoggingSessionId]]。

一旦日志记录会话被取消，用户代理 不得 记录任何与 WebRTC 相关的活动，并且 用户代理 必须已经 删除与被取消的日志记录会话关联的 所有已记录数据。