gstreamer_tracing/
lib.rs

1#![doc = include_str!("../README.md")]
2#![deny(unreachable_pub)]
3// This crate uses unsafe code for introspecting GObject fields (ref_count, type,
4// name, state, etc.) in the log handler, since the safe bindings don't expose
5// these details through `LoggedObject`.
6#![deny(unsafe_op_in_unsafe_fn)]
7
8macro_rules! skip_assert_initialized {
9    () => {};
10}
11
12pub use gst;
13pub use log::attach_span;
14use tracing_core::field::Value;
15
16#[macro_use]
17mod macros;
18mod callsite;
19mod log;
20pub mod tracer;
21
22/// The top-level target component of the events and spans dispatched to `tracing` by this library.
23///
24/// You can use this to filter events with e.g. `RUST_LOG` environment variable when using the fmt
25/// subscriber. The value of this constant is not guaranteed to be stable.
26///
27/// See [`tracing::Metadata`][tracing_core::Metadata] for further information.
28pub const TARGET: &str = "gstreamer";
29
30trait UnsizeValue {
31    fn unsize_value(&self) -> Option<&dyn Value>;
32}
33
34impl<V: Value> UnsizeValue for Option<V> {
35    fn unsize_value(&self) -> Option<&dyn Value> {
36        match self {
37            Some(v) => Some(v as &dyn Value),
38            None => None,
39        }
40    }
41}
42
43/// Enable the integration between GStreamer logging system and the `tracing` library.
44///
45/// Once enabled the default [`tracing::Subscriber`][tracing_core::subscriber::Subscriber] will
46/// receive an event for each of the GStreamer debug log messages.
47///
48/// The events produced this way will specify the “current” span as the event's parent. Doing
49/// nothing else, there won't be any span to act as the parent. Consider also using the
50/// integrations for producing spans.
51///
52/// This function can be executed at any time and will process events that occur after its
53/// execution.
54///
55/// Calling this function multiple times may cause duplicate events to be produced.
56pub fn integrate_events() {
57    log::debug_add_log_function();
58}
59
60/// Enable the integration between GStreamer tracing system and the `tracing` library.
61///
62/// Once enabled the default [`tracing::Subscriber`][tracing_core::subscriber::Subscriber] will
63/// have spans entered for certain GStreamer events such as data being pushed to a pad.
64///
65/// This will provide some meaningful context to the events produced by integrating those.
66///
67/// This function may only be called after `gst::init`.
68pub fn integrate_spans() {
69    static INIT: std::sync::Once = std::sync::Once::new();
70    INIT.call_once(|| {
71        // Keep the tracer alive for the rest of the process lifetime so parent
72        // propagation hooks remain active.
73        let tracer = gst::glib::Object::new::<tracer::TracingTracer>();
74        std::mem::forget(tracer);
75    });
76}
77
78/// Disable the integration between GStreamer logging system and the `tracing` library.
79///
80/// As an implementation detail, this will _not_ release certain resources that have been allocated
81/// during the period of event integration. Some of the resources are required to live for
82/// `'static` and therefore cannot be soundly released by any other way except by terminating the
83/// program.
84pub fn disable_events() {
85    log::debug_remove_log_function();
86}
87
88#[cfg(test)]
89mod tests;
gstreamer_tracing/lib.rs

gstreamer_tracing/
lib.rs
