2. GStreamer 调试工具：GST_DEBUG 环境变量详解、调试级别与分类、常用调试类别
调试流媒体管道，说白了就是跟黑盒子打交道。你丢进去一个视频流，它可能出来花屏、卡顿，甚至直接崩掉。这时候如果只会加 printf，那效率就太低了。GStreamer 自带的 GST_DEBUG 机制，就是专门干这个的。
我个人习惯，遇到问题第一件事不是翻代码，而是先调 GST_DEBUG 级别。很多时候，日志里已经把答案告诉你了。
2.1 GST_DEBUG 环境变量：调试的入口
GST_DEBUG 是 GStreamer 最核心的调试开关。它控制着整个框架输出什么级别的日志、从哪些模块输出。
基本格式很简单：
GST_DEBUG=<类别>:<级别>,<类别>:<级别>,...举个例子：
GST_DEBUG=*:3 ./my_pipeline这表示所有类别（* 是通配符）都输出级别 3 及以上的日志。级别 3 是 WARNING，也就是说只有警告和错误才会打印出来。
GST_DEBUG=*:4（INFO 级别），既能看清流程，又不会被海量 DEBUG 日志刷屏。等定位到具体模块了，再单独提高那个模块的级别。
如果你想同时看多个模块，用逗号分隔就行：
GST_DEBUG=rtpjitterbuffer:6,rtpsession:5,udpsrc:4这条命令的意思是：rtpjitterbuffer 模块输出级别 6（LOG）的日志，rtpsession 输出级别 5（DEBUG），udpsrc 输出级别 4（INFO）。
*:7（TRACE），结果日志文件每分钟涨 2GB，直接把磁盘撑爆了。嗯，从那以后我再也不敢在生产环境开超过级别 4 了。
2.2 调试级别：从 ERROR 到 TRACE
GStreamer 定义了 8 个调试级别，从 0 到 7。数字越大，信息越详细。
| 级别 | 名称 | 含义 | 我什么时候用 |
|---|---|---|---|
| 0 | NONE | 不输出任何日志 | 生产环境，或者跑 benchmark 时 |
| 1 | ERROR | 致命错误，管道无法继续 | 排查崩溃、断流等严重问题 |
| 2 | WARNING | 非致命异常，但可能影响质量 | 检查丢包、延迟抖动等 |
| 3 | FIXME | 代码中标记的待办事项 | 很少主动用，通常是看源码时顺带 |
| 4 | INFO | 关键流程信息 | 日常开发，看管道状态变化 |
| 5 | DEBUG | 详细的内部状态 | 定位具体函数调用、状态机跳转 |
| 6 | LOG | 更细粒度的日志 | 分析数据流、缓冲区操作 |
| 7 | TRACE | 最详细的日志，包含所有调用 | 万不得已才用，比如查死锁 |
为什么会分这么多级别？你想想看，如果所有信息都混在一起，你根本找不到重点。级别 1 的 ERROR 日志，一眼就能看到红色报错；级别 7 的 TRACE 日志，一行一行全是函数进出，适合用 grep 过滤。
rtpjitterbuffer:6，结果日志里全是 "push packet" 和 "pop packet" 的 LOG 信息。我直接用 grep "seqnum" 过滤出序列号变化，5 分钟就找到了丢包原因。如果不开 LOG 级别，根本看不到这些细节。
2.3 调试类别：精准定位模块
调试类别（Category）是 GStreamer 的模块标识。每个插件、每个核心组件都有自己的类别名。你可以在代码里看到类似 GST_DEBUG_CATEGORY_STATIC (rtpjitterbuffer); 这样的声明。
常用的调试类别有哪些？我整理了一张表：
| 类别名 | 所属模块 | 典型调试场景 |
|---|---|---|
* |
所有模块 | 全局开关，快速定位问题范围 |
GST_PLUGIN_LOADING |
插件加载 | 插件找不到、版本冲突 |
GST_PADS |
Pad 连接 | Capabilities 协商失败 |
GST_STATES |
状态机 | 管道卡在某个状态、状态切换失败 |
GST_BUFFER |
缓冲区管理 | 内存泄漏、缓冲区分配异常 |
GST_CLOCK |
时钟同步 | 音画不同步、时间戳异常 |
rtpjitterbuffer |
RTP 抖动缓冲 | 丢包、乱序、延迟抖动 |
rtpsession |
RTP 会话 | SSRC 冲突、RTCP 交互异常 |
udpsrc |
UDP 源 | 网络丢包、端口绑定失败 |
queue |
队列 | 队列溢出、死锁 |
videotestsrc |
测试源 | 测试管道基本功能 |
你可能会问：我怎么知道某个插件对应的类别名是什么？有两个办法：
- 看源码：搜索
GST_DEBUG_CATEGORY_STATIC或GST_DEBUG_CATEGORY_INIT，后面跟着的就是类别名。 - 用
gst-inspect-1.0：运行gst-inspect-1.0 插件名 | grep debug，会直接告诉你类别名。
GST_DEBUG=*:4,插件名:6 这种组合。先全局开 INFO，再单独给目标插件开 DEBUG。这样既能看到上下文，又能聚焦到具体模块。
2.4 其他有用的调试环境变量
除了 GST_DEBUG，还有几个环境变量我经常搭配使用：
| 环境变量 | 作用 | 示例 |
|---|---|---|
GST_DEBUG_FILE |
将日志输出到文件，而不是 stderr | GST_DEBUG_FILE=/tmp/gst.log |
GST_DEBUG_NO_COLOR |
禁用彩色输出，方便重定向到文件 | GST_DEBUG_NO_COLOR=1 |
GST_DEBUG_DUMP_DOT_DIR |
将管道图导出为 .dot 文件 | GST_DEBUG_DUMP_DOT_DIR=/tmp/dot |
GST_TRACERS |
启用性能追踪器 | GST_TRACERS="stats;latency" |
我个人最常用的是 GST_DEBUG_DUMP_DOT_DIR。它会在管道状态变化时自动生成 .dot 文件，用 Graphviz 打开就能看到完整的管道拓扑图。对于复杂的 RTP 流控管道，这个功能简直是神器。
2.5 知识体系：GST_DEBUG 调试全景图
下面这张 SVG 图，把 GST_DEBUG 的核心逻辑串起来了。你可以把它当作调试时的路线图。
2.6 实战：一个完整的调试流程
假设你正在调试一个 RTP 接收管道，发现视频经常卡顿。你会怎么做？
我的流程是这样的：
- 先开全局 INFO：
GST_DEBUG=*:4，看看管道状态切换是否正常。 - 发现 WARNING 日志：看到
rtpjitterbuffer报 "packet lost" 或 "too late"。这时候把级别提高到 DEBUG。 - 开模块 DEBUG：
GST_DEBUG=rtpjitterbuffer:5，看具体是哪些序列号丢了。 - 如果还不够：开 LOG 级别
GST_DEBUG=rtpjitterbuffer:6，看每个包的到达时间和抖动缓冲状态。 - 导出管道图：
GST_DEBUG_DUMP_DOT_DIR=/tmp/dot，看看管道拓扑有没有问题。