8.1 调试工具箱演练：分级日志与管线快照

8.1 调试工具箱演练：分级日志与管线快照

本节摘要：GStreamer 的排障武器库四件套——分级日志（按严重度控量）、类别过滤（按子系统聚焦）、管线状态快照（把运行中的对象树画成图）、统计追踪器（把性能变成数字）。本节按排障场景演练用法，重点讲"什么时候用哪件"，是 8.2 排错实录的工具预备。

分级日志：从洪水到溪流

框架自带一套日志体系，用一个环境变量驱动。默认它安静如鸡；一旦设置，日志按严重度分九级，从致命错误到最细的逐对象追踪。新手的第一反应往往是开到最大级——日志每秒几千行刷屏，目标信息反而被淹没。正确手感是从三级起步：三级足以看到错误与警告的完整线索；需要看协商细节时把协商类别单独调到五六级，其余保持三级。量级参考：三级是溪流，全类六级是洪水，全局九级是海啸——海啸只在深度追踪特定对象时短暂使用。

日志分级与用量手感

# 起步档：全局三级 够看错误全貌
GST_DEBUG=3 gst-launch-1.0 filesrc location=a.mp4 ! decodebin ! fakesink
# 精准打击：协商类别六级 其余三级 输出同时落盘
GST_DEBUG=3,caps:6,negotiation:6 GST_DEBUG_FILE=run.log gst-launch-1.0 ...
# 现场染色：错误行红 警告行黄 终端直接可读
gst-launch-1.0 --gst-debug-color-mode=always ...
​

类别过滤是控量的关键。框架按子系统划分日志类别——协商、时钟、衬垫、队列、各基类、每个元件自带类别——类别名可从日志行首看到。排障流程因此顺理成章：三级全局跑一遍，从日志行首认出可疑类别，把它单独调高重跑。两轮下来，日志量常从几万行缩到几十行。

管线快照：把运行中的树画出来

结构类故障（接错垫、漏链接、线程边界意外）用眼睛看图最快。设置快照导出目录环境变量后，管线每次状态跃迁都会导出一张对象树图（图形描述格式），转成图片即可看到真实的连接关系、每条线程的边界、队列位置。快照的杀手级用途是对比：设计图与快照对比，能发现"以为接上了其实没接"的垫；好机器与坏机器的快照对比，能发现自动装配走了不同路径（第七章的硬解回退就靠这招现形）。

# 设置快照目录后正常运行业务 状态跃迁自动落图
GST_DEBUG_DUMP_DOT_DIR=/tmp gst-launch-1.0 ...
# 产物为若干图形描述文件 转换为图片查看
dot -Tpng /tmp/*.dot -O
​

统计追踪器：把性能变成数字

第八章试压台的重头工具。统计追踪器在运行时统计每个元件的帧数、字节量、处理时长、时钟等待时长，按时间片输出汇总表——性能定位从"感觉哪慢"变成"表格指认谁慢"。用法是一条环境变量加一个运行周期。

# 统计追踪：每秒输出各元件的处理统计
GST_DEBUG=GST_TRACER:7 GST_TRACERS="stats" \
  gst-launch-1.0 videotestsrc ! videoconvert ! autovideosink
# 汇总表里每个元件一行 时间列直接指认热点
​

解读统计表的三条经验：处理时长列找热点元件（谁的时长占比异常）；时钟等待列辨"算得慢"与"等得慢"（等待大说明上游供给不足或同步策略保守，处理大才是真热点）；帧数列对不上说明某处在丢帧（结合 5.3 节的队列水位判断丢弃点）。除统计外还有日志追踪器可输出结构化事件流、内存追踪器盯分配热点，按需挂载。

⚠️ 常见坑：带着追踪器做性能结论。追踪器本身有观测开销，最终数字要在无追踪状态复核；它的价值是指认方向，不是给出精确值。

💡 关键直觉：四件工具对应四种故障形态——行为错用分级日志、结构错用快照、性能差用统计追踪器、类别不明就三级起步先看全貌。先判形态再拿工具，别抡着锤子找钉子。

两个高频日志现场的走读

现场一：协商现场。新管线首跑必看。协商类日志按"模板通报—求交—定格"三段展开，走读时抓定格行与能力集行对照：定格字段与过滤器约束不符、或求交结果比预期窄，都在这一眼之间。现场二：收尾现场。流结束前后的日志。数据流类别会记录冲刷、段结束与流结束的次序，收尾顺序错乱（先报流结束数据还在飞）往往预示着自定义元件的事件应答有缺陷——8.2 节类型病的另一副面孔。

日志留存策略

生产环境的日志策略与排障期不同：分级日志默认三级起步并落盘轮转，快照在每次状态跃迁自动导出、按会话归档，统计追踪器按需开启并限定时长。留存的价值在对比——故障现场的日志与正常时段的快照对比，往往比任何实时分析都快。为对比而留存，日志才不是用过即弃的流水。

日志格式的速读法

一行日志的固定结构值得拆一次：时间戳（相对进程启动的秒数，看间隔找周期）、类别与等级（行首的类别名比等级更值得先看——同类别的日志是一段连续剧情）、对象路径（从管线根到元件的完整路径，一眼定位"是谁家的孩子"）、正文。速读的习惯是先扫对象路径再读正文——同一条正文挂在不同对象上，意义完全不同。

快照对比法的完整流程再走一遍：设计阶段画好期望图；正常运行时导出快照；故障时导出故障快照；三图并排比对。比对重点三处——连线（有没有断链或漏接）、线程边界（队列位置对不对）、自动装配的实际选择（硬解还是软解、哪个渲染器）。多数结构类故障在第三处现形——"配置写的是一个元件、实际跑的是另一个"，只有快照会告诉你真相。

本节要点回顾

• 三级起步、分类深入、锁定再全开：日志用量的九字手感；
• 类别名从行首认：把可疑类别单独调高，两轮收敛日志量；
• 快照对比法：设计对快照、好机对坏机，结构差异现形；
• 统计表三列：时长找热点、等待辨供给、帧数查丢弃；
• 追踪器指方向不复核定值：观测开销要记在心里。

工具上手，下一节实弹演习：一起真实的启动失败，六步剧本从头走到尾。