1.4 调试工具链与日志系统

1.4 调试工具链与日志系统

工程环境一节的最后一块拼图：当代码能编译、能运行，怎么看清它在运行时干了什么。本节讲的日志与事件记录，是后续每一章排错案例的基础工具，相当于给这座总局装上值班电话录音与交接班记录。

日志系统的分级与出口

引擎内置的日志设施按严重程度分级：从最详细的追踪级，到信息级、警告级、错误级。每条日志都自带线程标签与时间戳，打点遍布各个模块——建连的每个阶段、协商的每个决定、码率的每次调整，都有现成的观测点。对调试者来说，多数问题的第一手证据就是日志，多数所谓"灵异现象"，把日志级别开到追踪级再看一遍就有了答案。

日志默认打到标准错误，生产环境这样用不现实。引擎提供自定义出口机制：注册一个日志接收器，所有日志会额外投递给你，你可以决定写入文件、上传服务端或按线程过滤。下面是注册自定义出口的最小骨架。

class FileLogSink : public rtc::LogSink {
 public:
  void OnLogMessage(const std::string& message) override {
    fwrite(message.data(), 1, message.size(), fp_);
  }
  void OnLogMessage(const std::string& message,
                    rtc::LoggingSeverity severity,
                    const std::string& tag) override {
    fprintf(fp_, "[%d] %s %s", (int)severity, tag.c_str(), message.c_str());
  }
 private:
  FILE* fp_ = fopen("engine.log", "ab");
};

rtc::LogMessage::AddLogToStream(new FileLogSink, rtc::LS_INFO);
​

用的时候有三个经验值值得记录。级别选信息级而不是追踪级：追踪级在长通话里每秒能产出上千行，磁盘与解析成本都很高，只有追细节问题时才临时打开。要多载一份带严重度参数的回调版本，否则拿不到级别标签，事后过滤会很痛苦。注册时机要赶在创建工厂之前，否则启动阶段的日志已经漏掉了——而恰恰是启动阶段最容易出配置类错误。

事件记录：专给质量分析用的黑匣子

日志面向开发者排障，事件记录则面向质量分析：引擎把带宽估计变化、丢包事件、码率调整、抖动估计这类带数值的关键事件，按结构化格式写进二进制文件，导出后可以离线回放整场通话的行为曲线。它和日志的关系，好比行车记录仪与驾驶日志——前者记录数值与时刻，后者记录人看到了什么。浏览器端的面板数据，本质上也是同一套事件的在线视图。

这个设施由生成参数里的序列化开关控制，裁剪定制版时务必保留。离线分析工具有官方脚本可以把二进制转成文本再画图，团队内部通常把它做成流水线：通话结束、自动上传、解析入库、指标落表，第七章的排错案例会完整演示一次。

案例：用事件记录定位一次偶发卡顿

背景。内部演示会上，浏览器端的通话每隔几十秒出现短暂卡顿，现场日志没报错，复现概率低，问题挂了三天没人接。

操作。我们先在演示页打开事件记录开关，指定输出文件并设上只记最近若干秒的环形策略，然后重现问题。拿到事件文件后，用官方脚本转文本，重点看三类事件的时刻对齐：丢包事件、带宽估计变化、码率重配置。把卡顿时刻与事件时间轴对上之后，发现每次卡顿前一秒左右，带宽估计都出现一次断崖式下调，随后编码目标码率跟着下调，卡顿与画质下降同时发生。

结果。顺着带宽下调往回查，发现下调前总有一小簇上报丢包，而那段时间本机正在进行大文件局域网同步，WiFi 信道被占满。限速同步进程后，卡顿消失。

解读。这个案例演示了事件记录的正确用法：不是逐条读事件，而是把多个通道的事件按时刻对齐，找因果链——丢包是因，带宽下调是果，码率下调再是果，卡顿是末端表现。日志告诉你"系统觉得出事了"，事件记录告诉你"系统为什么这么觉得"。两者对齐，问题就从玄学变成了时间轴上的三个点。

变式。如果事件里丢包与带宽下调都对不上卡顿时刻，那问题多半不在传输而在采集或渲染侧，此时把对齐对象换成采集帧间隔与渲染时刻即可。同一套方法换个对齐维度，就能覆盖另一大类问题——这就是为什么本节把事件记录放在第一章讲：它是贯穿全书的诊断底座。

日志分析的实战技巧

有了出口之后，真正拉开效率差距的是分析手法。分享三条在实践中沉淀的技巧。第一，按线程标签切流：引擎日志自带线程标识，把日志按线程拆成几股分别读，交叉噪音立刻减半——信令线上的协商过程、网络线上的传输事件、工作线上的编解码动作各有各的叙事，混读只会晕。第二，锚定关键事件再向前后各取一段：全量日志是流水的账本，先定位你关心的事件（建连开始、关键帧请求、码率调整），只取事件前后的片段细读。第三，时间戳对齐多源证据：把日志、事件记录、抓包三份材料的时间轴对到同一把尺上，任何"机制之间对不上"的疑点都会现形。

日志里最常见的几类行文模式也值得熟悉，读懂模式等于自带翻译器。

:: 状态推进类：对象名加跃迁前后状态，排查建连先看这类
PeerConnection :: SetRemoteDescription 从 稳定 到 有远端提议
:: 决策类：主体加判断依据加结论，带宽与编码决策都是这个形状
SendSideBandwidthEstimate :: 丢包率超阈值 下调估计至 850 kbps
:: 断言与告警类：出现即代表纪律被破坏，优先级最高
Wrong thread on dtls. Expected network
​

遇到问题时，第一遍读日志只找这三类行：状态推进到哪一步停了、哪个决策用了什么依据、有没有纪律告警。三遍读完还没有头绪，再把级别开到追踪级复现一次——多数问题到不了这一步就已经现形。

断点调试的线程纪律

引擎是多线程系统，第二章会专门讲线程模型，这里只给断点调试的纪律预告：在错误的线程上断住并长时间停留，可能导致整个通话超时崩溃，现象与业务 bug 极像。正确姿势是在断点条件里限定线程或时刻，观察完立刻放行；需要长时间分析时，优先用日志与事件记录，断点只做最后的现场确认。另外，浏览器端调试还有一个免编译的窗口：浏览器内置的内部面板，能看到候选对、码率曲线、丢包计数，与引擎内部指标一一对应，把它当成"不编译就能看的观测台"，能省掉大量编译等待。

本节要点：日志分级与自定义出口是排障第一抓手；事件记录是质量分析的黑匣子，分析方法核心是多通道事件对齐时刻；断点调试要守线程纪律，长观察交给日志与事件。至此第一章的装备全部备齐，下一章我们进入这座总局的核心架构图。