此 crate 提供了 gstreamer 和跟踪生态系统之间的桥梁。

目标是允许利用 GStreamer 的 Rust 应用程序更好地集成到其他使用 tracing crate 来满足其可观察性需求的应用程序中。

示例

事件

要将 gstreamer 日志消息作为 tracing 事件输出，请调用 integrate_events 函数。在调用任何其他 gstreamer 调用之前（特别是 gstreamer::init 之前）调用它最有可能正确转发所有消息

// Set up the tracing subscriber.
//
// e.g. tracing_subscriber::fmt::init();

tracing_gstreamer::integrate_events();
gstreamer::log::remove_default_log_function();
gstreamer::init();

请注意，`GST_DEBUG` 和跟踪过滤器都处于活动状态。可以通过代码从 gstreamer 端放松过滤器。

gstreamer::log::set_default_threshold(gstreamer::DebugLevel::Memdump);

同样，您可以使用 tracing API 来调整 tracing 端的过滤器。

跨度

为了为某些事件提供更多上下文信息，您还可以通过 gstreamer 自身的 跟踪基础设施 启用支持生成跨度。

可以通过调用 integrate_spans 函数来启用此功能。它必须在调用 gstreamer::init 之后调用。

gstreamer::init();
tracing_gstreamer::integrate_spans();

订阅者展示

本节展示了使用不同类型的订阅者获得的结果。

tracing_subscriber::fmt

该订阅者是内置gstreamer日志处理程序的优秀替代品。以下是一个使用此订阅者可能输出的示例

$ env RUST_LOG=info cargo run --example videoenc
    Finished dev [unoptimized + debuginfo] target(s) in 0.04s
     Running `target/debug/examples/videoenc`
Jan 01 00:00:00.000  INFO gstreamer::GST_INIT: Initializing GStreamer Core Library version 1.18.4
<snip>
Jan 01 00:00:00.000  INFO gstreamer::GST_INIT: initialized GStreamer successfully
Jan 01 00:00:00.000  INFO gstreamer::GST_PIPELINE: parsing pipeline description '
        videotestsrc num-buffers=120
        ! vp9enc
        ! webmmux name=mux
        ! fakesink sync=false

        audiotestsrc num-buffers=120
        ! opusenc
        ! mux.
    '

某些消息可能比内置日志记录器提供更多信息。虽然内置日志记录器会显示正在记录的对象类型和地址，但tracing-gstreamer可能提供更实用的信息，例如元素名称

Jan 01 00:00:00.000  INFO gstreamer::GST_STATES: completed state change to READY gobject.address=94331150660528 gobject.type="GstAudioTestSrc" gstobject.name="audiotestsrc0" gstelement.state="ready" gstelement.pending_state="void-pending"

或通过span提供额外上下文，这有助于在无法通过其他方式确定的情况下确定哪个元素记录了消息，例如在此示例中

Jan 01 00:00:00.000  INFO pad_push{gstpad.state={NEED_PARENT} gstpad.parent.name="audiotestsrc0"}: gstreamer::structure: Expected field 'channel-mask' in structure: audio/x-raw, rate=(int)48000, channels=(int)1, format=(string)S16LE, layout=(string)interleaved;

tracing-tracy

Tracy是一个主要针对游戏开发工作负载的剖析器，但也适用于通用代码。Tracy具有采样剖析器，但与手动设置感兴趣点的应用程序结合使用效果最佳。tracing是此类手动设置点的绝佳来源，而tracing-tracy则是两者之间的桥梁。以下视频展示了从本存储库中适配的videoenc示例，该示例利用了tracing-tracy订阅者。

本视频中有几个亮点

• 我们可以快速看到我们的管道启用的并发量（2个线程；也许添加一些queue会有所帮助？）
• 整体线程利用率（音频部分低，视频部分高）；
• 调查特定元素的性能，并快速找出为什么其中一些元素运行缓慢。例如，opusenc0元素有时会花费异常长的时间，因为下游多路复用器已经在该时间点有一个缓冲区排队。

其他一些订阅者也可以实现类似的结果。

GStreamer跟踪器

还有几个GStreamer跟踪器可供选择，因此可以在不修改使用GStreamer的应用程序的情况下将GStreamer跟踪和日志记录集成到Rust跟踪系统中。

要使GStreamer找到跟踪器，您需要确保libtracing_gstreamer.so已作为GStreamer插件安装（您还可以设置GST_PLUGIN_PATH，例如使用export GST_PLUGIN_PATH=$PWD/target/debug/:$GST_PLUGIN_PATH）。

目前有两个跟踪器可用

• chrometracing：此跟踪器将以Chrome json跟踪格式输出跟踪事件。这将创建一个trace-XXX.json文件，位于当前目录，可以打开perfetto。这对于以图形方式分析GStreamer性能很有用。

• fmttracing：使用tracing-subscriber::fmt订阅者来格式化跟踪事件。这对于获取可读的输出很有用。要实际获取输出，您还需要设置RUST_LOG=<loglevel>

请注意，一次只能使用一个这些跟踪器，应用程序本身不应激活任何其他跟踪器。

跟踪器参数

跟踪器有以下参数

• log-level：与GST_DEBUG环境变量相同的格式的字符串，定义了哪些GStreamer日志级别和类别应该记录到跟踪系统中。这意味着将禁用常规的GStreamer日志系统，并使用rust替代。

示例

例如，您可以使用以下命令使用gst-launch-1.0来配置GStreamer流水线：

使用chrometracing跟踪器

# Builds the tracer plugin and make sure GStreamer finds it.
# Enable the tracer with the chrome tracing output and activating GStreamer info logs
cargo build --features "tracing-chrome" && \
  GST_PLUGIN_PATH=$PWD/target/debug/:$GST_PLUGIN_PATH \
  GST_TRACERS="chrometracing(log-level=4)" \
  gst-launch-1.0 playbin3 uri="https://www.freedesktop.org/software/gstreamer-sdk/data/media/sintel_trailer-480p.webm"

将在当前目录下创建一个新的trace-XXX.json文件。然后您可以在perfetto中打开它进行分析。

使用fmttracing跟踪器

# Builds the tracer plugin and make sure GStreamer finds it.
# Enable the tracer with the fmt tracing output and activating GStreamer info logs
# Logs will be output on stderr in the `tracing-subscriber::fmt` format
cargo build && \
  GST_PLUGIN_PATH=$PWD/target/debug/:$GST_PLUGIN_PATH \
  RUST_LOG=debug GST_TRACERS="fmttracing(log-level=4)" \
  gst-launch-1.0 playbin3 uri="https://www.freedesktop.org/software/gstreamer-sdk/data/media/sintel_trailer-480p.webm"