This crate bridges between gstreamer and tracing ecosystems.

Overview

This crate provides a bridge between gstreamer and the tracing ecosystem.

The goal is to allow Rust applications utilizing GStreamer to better integrate into application that otherwise use the tracing crate for their observability needs.

Examples

Events

To output gstreamer log messages as tracing events, call the [integrate_events] function. Calling it before the call to any other gstreamer call (especially before the gstreamer::init) is most likely to correctly forward all of the messages:

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

tracing_gstreamer::integrate_events();
gstreamer::debug_remove_default_log_function();
gstreamer::init();

Keep in mind that both GST_DEBUG and tracing filters are in effect. The gstreamer side of filters can be relaxed from code via:

gstreamer::debug_set_default_threshold(gstreamer::DebugLevel::Count);

Similarly you can use tracing APIs to adjust the filters on the tracing side.

Spans

To provide tracing with more contextual information for some of the events, you can also enable support for generating spans via gstreamer's own tracing infrastructure.

This functionality can be enabled by calling the [integrate_spans] function. It must be called after gstreamer::init.

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

Subscriber showcase

This section demonstrates the results obtained with different kinds of subscribers.

tracing_subscriber::fmt

This subscriber is a great replacement for the built-in gstreamer log handler. Here's an example of what the output might look like when using this subscriber:

$ 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.
    '

Certain messages may also provide more information than the built-in logger. While builtin logger does present you with the type and address of the object being logged, tracing-gstreamer may provide more readily useful information such as the element name:

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"

or provide additional context via spans, which may help to figure out which element is logging the message when there is no other way to tell this otherwise, such as in this example:

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 is a profiler focused primarily on game development workloads, but works fairly well for general purpose code as well. Tracy features a sampling profiler, but works best with applications that have manually instrumented points of interest. tracing is a great source of such manual instrumentation points and tracing-tracy is the bridge between the two. The following video demonstrates the videoenc example from this repository adapted to utilize the tracing-tracy subscriber.

gstreamer-in-tracy.mp4

In this video there are a couple of highlights

  • We can quickly see the amount of concurrency our pipeline enables (2 threads; perhaps adding some queues would help?)
  • Overall thread utilization (low for the audio portion and high for the video portion);
  • Investigate the performance of the specific elements and quickly find out why some of them are slow. For example the opusenc0 element sometimes takes an unusually long time because the downstream muxer already has a buffer queued at the time.

Similar results can be achieved with some other subscribers as well.

You might also like...
tracing - a framework for instrumenting Rust programs to collect structured, event-based diagnostic information

tracing-appender Writers for logging events and spans Documentation | Chat Overview tracing is a framework for instrumenting Rust programs to collect

A rust `tracing` compatible framework inspired by log4rs.

trace4rs This crate allows users to configure output from tracing in the same way as you would configure the output of log4rs. Overview For a usage ex

A lean, minimal, and stable set of types for color interoperation between crates in Rust.

This library provides a lean, minimal, and stable set of types for color interoperation between crates in Rust. Its goal is to serve the same function that mint provides for (linear algebra) math types.

Easy switch between AWS Profiles and Regions
Easy switch between AWS Profiles and Regions

AWSP - CLI To Manage your AWS Profiles! AWSP provides an interactive terminal to interact with your AWS Profiles. The aim of this project is to make i

Simple interoperability between C++ coroutines and asynchronous Rust

cxx-async Overview cxx-async is a Rust crate that extends the cxx library to provide seamless interoperability between asynchronous Rust code using as

my attempt at compromise between unwrapping and bullying my dependencies' authors for Error impl

string-eyre Has this happened to you? error[E0599]: the method `wrap_err` exists for enum `Result(), tauri::Error`, but its trait bounds were not sa

Count and convert between different indexing schemes on utf8 string slices

Str Indices Count and convert between different indexing schemes on utf8 string slices. The following schemes are currently supported: Chars (or "Unic

A translator interface between VoiceMeeter/VBAN and the X-Touch

VBAN - XCtrl translator This serves as a network based translator for interfacing the Behringer X-Touch with VoiceMeeter Potato. It is designed to ru

Create virtual serial ports, connect them to physical serial ports, and create routes between them all.

Virtual Serial Port Router (vsp-router) Create virtual serial ports, connect them to physical serial ports, and create routes between them all. vsp-ro

Comments
  • non-exhaustive patterns/ does not compile

    non-exhaustive patterns/ does not compile

    Сompile time error :

    ➜  new-rtsp-service git:(main) ✗ cargo run
       Compiling tracing-gstreamer v0.3.0
       Compiling gstreamer-rtsp-server v0.18.0
    error[E0004]: non-exhaustive patterns: `(&Kind(0_u8), _)` and `(&Kind(3_u8..=u8::MAX), _)` not covered
       --> /home/***/.cargo/registry/src/github.com-1ecc6299db9ec823/tracing-gstreamer-0.3.0/src/callsite.rs:152:38
        |
    152 |             .then_with(move || match (&self.kind, &other.kind) {
        |                                      ^^^^^^^^^^^^^^^^^^^^^^^^^ patterns `(&Kind(0_u8), _)` and `(&Kind(3_u8..=u8::MAX), _)` not covered
        |
        = help: ensure that all possible cases are being handled, possibly by adding wildcards or more match arms
        = note: the matched value is of type `(&Kind, &Kind)`
    

    Cargo.toml:

    [dependencies]
    tracing = "0.1"
    tracing-subscriber = "0.3"
    tracing-gstreamer = "0.3"
    log-panics = "2"
    
    
    gstreamer-rtsp-server = "0.18"
    
    url = "2"
    
    tokio = {version = "1", features = ["rt-multi-thread", "macros", "sync"]}
    
    opened by RustPanda 5
  • Address breaking changes in tracing_core

    Address breaking changes in tracing_core

    tracing-core 0.1.22 introduced an unfortunate breaking change. One of the public types was intended to be non-exhaustive, but turns out rustc was smart enough to make it exhaustive anyway.

    The hope was that there wouldn't be any way to obtain the Kind from a Metadata and even less of a reason to actually match on one. Alas, it turned out to be not true for us, where we were trying to open code an implementation of PartialEq for Kind.

    In retrospective we should've been using our own defined type anyway and deriving PartialEq as that's just cleaner (we don't need to think about any future variants added to Kind.)

    Fixes #6

    opened by nagisa 0
  • Implement handling of event interests

    Implement handling of event interests

    This was pretty fun a headscratcher. What happens here is that any time a new Callsite is created (conceptually a location in code which contains a log statement) we must register ourselves with tracing runtime and obtain subscribers' interest in the event, and filter accordingly.

    This avoids unnecessarily spending timme on invoking all of the subscriber machineries among other things. As a future optimisation on our side, we can also check the interest before allocating/leaking the Metadata and Callsite, at the cost of checking the interest twice when we do actually register the callsite.

    opened by nagisa 0
  • More configurable span tracing categories

    More configurable span tracing categories

    Today this library registers a single tracer which in turn unconditionally registers all the hooks it is interested at once:

    https://github.com/standard-ai/tracing-gstreamer/blob/9b7d80b43b794499a40f5252634427ad362494e8/src/tracer.rs#L108-L117

    If we wanted to extend the scope of the tracing this library does (which I would very much like to,) we sort-of need to figure out a way to make the trace interest more configurable. One option would be to actually have different Tracer objects for each different trace categories. We could alternatively expose the Tracer as a public API and handle the registration of different events outside of the object creation, giving users granular control to do the same for themselves.


    If nothing else, this gives a great way for people to mitigate locally issues that might occur as a result of bug in bindings or this library in tracers for a specific event.

    opened by nagisa 0
Owner
Standard Cognition OSS
Standard Cognition Open Source Software
Standard Cognition OSS
A convenient tracing config and init lib, with symlinking and local timezone.

clia-tracing-config A convenient tracing config and init lib, with symlinking and local timezone. Use these formats default, and can be configured: pr

Cris Liao 5 Jan 3, 2023
An example of a fairing for rocket to use tracing (as this pops up at many places in dicussions and questions)

Rocket Tracing Fairing Example This repository aims to give a short example of how you can add a Fairing to your Rocket for tracing and how to use it

Christof Weickhardt 9 Nov 23, 2022
Tracing layer to quickly inspect spans and events

tracing-texray First, a word of warning: This is alpha software. Don't run this in prod or anywhere where a panic would ruin your day. tracing-texray

Russell Cohen 23 Dec 3, 2022
Middlewares and tools to integrate axum + tracing + opentelemetry

axum-tracing-opentelemetry Middlewares and tools to integrate axum + tracing + opentelemetry. Read OpenTelemetry header from incoming request Start a

David Bernard 31 Jan 4, 2023
Error propagation tracing in Rust.

Propagate Error propagation tracing in Rust. Why Propagate? Being able to trace the cause of an error is critical for many types of software written i

Ben Reeves 10 Sep 23, 2021
A tracing profiler for the Sega MegaDrive/Genesis

md-profiler, a tracing profiler for the Sega MegaDrive/Genesis This program, meant to be used with this fork of BlastEm, helps you finding bottlenecks

null 15 Nov 3, 2022
A tracing layer for macOS/iOS's `oslog`

tracing_oslog This is a tracing layer for the Apple OS logging framework. Activities are used to handle spans, Example use tracing_oslog::OsLogger; l

Lucy 12 Dec 6, 2022
Emit ETW events in tracing-enabled Rust applications.

tracing-etw Emit ETW events in tracing-enabled Rust applications. This crate depends on rust_win_etw. There are four ETW events. fn NewSpan(span_id: u

Microsoft 11 Aug 10, 2022
A patch to fix tracing LocalTime problem.

tracing-local-time A patch to fix tracing LocalTime problem. Tracing-subscriber now has a bug in LocalTime, so build ourselves' to fix it. In this pat

Cris Liao 2 Dec 27, 2021
A dynamic binary tracing tool

Backlight Backlight is a dynamic binary tracing tool. Install $ git clone [email protected]:JoshMcguigan/backlight.git $ cd backlight $ cargo install-b

Josh Mcguigan 42 Dec 3, 2022