视频会议用户说今天卡了但你查不到根因——Chrome 156 给 RTCPeerConnection 加了诊断日志 API，隐私数据终于不用靠用户手动导 webrtc-internals

视频会议用户报障说”今天下午 3 点卡成 PPT”，你翻遍代码、查了媒体服务器、日志全是 200——然后呢？没有数据，根本不知道那一帧是怎么丢的。

WebRTC 的内部状态（ICE 候选路径、网络抖动、SRTP 加密延迟）从来不暴露给应用层。Chrome 长期只有 chrome://webrtc-internals 内部页，用户自己导出才能看，团队想在 SaaS 里做生产排错？门都没有。Chrome 156 正式稳定的 WebRTC Web Diagnostic Logging API，把这件事推进了一大步。

核心 API：三行代码开启诊断

API 挂在 RTCPeerConnection 上，三个方法覆盖完整生命周期：

// 会话开始前：开启诊断日志记录
// 返回唯一 ID，关联本次记录会话
const logId = pc.startDiagnosticLogging({
  metadata: { app: "video-meeting", room: "room-8841" }
});

// 通话结束（或用户报告问题时）：停止记录，日志写入本地磁盘
pc.finishDiagnosticLogging();

// 放弃本次记录：日志直接丢弃，不留任何文件
// pc.cancelLogging();

安全护栏（刻意设计的限制）：

• metadata 最多 5 个 key-value 对，每个 key 和 value 均不超过 100 字符
• 日志文件写入本地，由浏览器决定存储位置，不暴露路径给应用
• 应用本身永远读不到日志内容——数据不流向 JavaScript

你能触发记录、附加上下文、等待用户授权后上报，但没有后门偷看日志。隐私锁死在浏览器层。

企业策略：谁来决定能不能用

这不是随便哪个网站都能调用的 API。Chrome 通过企业策略白名单控制开关：

策略名： WebRtcDiagnosticLogCollectionAllowedForOrigins

配置示例（接受 URL pattern 列表，精确到 origin，忽略路径，支持子域通配）：

https://video.yourcompany.com
*.internal.yourcompany.com

这是企业 IT 管控的诊断基础设施，不是给个人博客用的。视频会议平台、远程医疗、在线教育等强 WebRTC 依赖场景可直接落地。

实际集成路径：生产环境三步走

第一步：灰度开启诊断

async function startLoggingIfAllowed(pc) {
  try {
    const id = pc.startDiagnosticLogging({
      metadata: {
        app: "video-conf",
        version: BUILD_VERSION,
        region: USER_REGION
      }
    });
    sessionStorage.setItem("webrtc_log_id", id);
  } catch (e) {
    // NotAllowedError — 域名不在企业策略白名单中
    console.debug("[WebRTC Diagnostics] Logging not allowed:", e.message);
  }
}

第二步：用户报障时触发日志固化

document.getElementById("report-btn").addEventListener("click", () => {
  // finishDiagnosticLogging 写盘后，浏览器弹出授权框让用户确认是否上报
  pc.finishDiagnosticLogging();
  showDialog("日志已保存，感谢您的反馈。");
});

第三步：用户上报给开发团队

浏览器写好的本地日志如何到开发者手里？需要用户主动操作——规范刻意把”如何分享”的决定权留给浏览器和用户，不给应用留后门。Chrome 可能会提供下载入口，或通过用户授权的渠道上传。

它不是什么：明确边界

规范里四个非目标（Non-Goals），划清了能力边界：

• ❌ 不暴露日志内容给 JavaScript — 应用拿到的只有 logId，日志数据在浏览器侧
• ❌ 不规定日志格式 — 不同浏览器可实现不同的内部记录方式
• ❌ 不规定上报机制 — 分享需要用户授权，具体路径由实现决定
• ❌ 不规定用户授权 UI — 可以是弹窗、企业策略、或系统级设置

跨厂商信号：不是 Chrome 独奏

规范托管在 W3C webrtc-extensions，Intent to Ship 在 Blink-Dev 上无异议通过。

对比：之前怎么做的

下一步

• 确认你的域名已在企业策略中配置了白名单
• 在测试环境用 chrome://webrtc-internals 对比新 API 的日志内容，看覆盖范围是否满足排错需求
• 关注 chromestatus.com/feature/5171428642299904 跟进 Android/WebView 落地时间线