mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-12-27 02:30:35 +00:00
Code Issues 1 Projects Releases Wiki Activity

tracers: Document the 'log' tracer

Browse source 
This patch adds documentation to the 'log' tracer and amends the design
document of Tracers to replace a misleading example of the 'log' tracer
with a different example that uses tracer arguments with tracers that do
actually handle said arguments.

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/4153>
This commit is contained in:
Alicia Boya García 2023-03-10 20:45:35 +01:00 committed by GStreamer Marge Bot
parent 3b9ce6cb54
commit 136b2e0eae
2 changed files with 90 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
subprojects/gst-docs/markdown/additional/design/tracing.md
View file

@ -35,10 +35,14 @@ Certain GStreamer core function (such as `gst_pad_push()` or
`gst_element_add_pad()`) will call into the tracer subsystem to dispatch
into active tracing modules. Developers will be able to select a list of
plugins by setting an environment variable, such as
`GST_TRACERS="meminfo;dbus"`. One can also pass parameters to plugins:
`GST_TRACERS="log(events,buffers);stats(all)"`. When then plugins are
loaded, we’ll add them to certain hooks according to which they are
interested in.
`GST_TRACERS="meminfo;dbus"`. One can also pass parameters to plugins, e.g:
```
GST_TRACERS='leaks(filters="GstEvent,GstMessage",stack-traces-flags=none);latency(flags=pipeline+element+reported)'
```
When then plugins are loaded, we’ll add them to certain hooks according to
which they are interested in.
Right now tracing info is logged as `GstStructures` to the TRACE level.
Idea: Another env var `GST_TRACE_CHANNEL` could be used to send the

83
subprojects/gstreamer/plugins/tracers/gstlog.c
View file

@ -22,7 +22,88 @@
* SECTION:tracer-log
* @short_description: log hook event
*
* A tracing module that logs all data from all hooks.
* A tracing module that logs all data from all GstTracer hooks. Takes no
* arguments other than an optional name.
*
* ### Enabling the log tracer
*
* Enable through an environment variable: `GST_TRACERS=log` (notice
* the plural).
*
* You can double check the plugin has been enabled using
* `GST_DEBUG='*:INFO'`. You should see:
*
* ```
* $ GST_TRACERS="log" GST_DEBUG='*:INFO' \
* gst-launch-1.0 fakesrc num-buffers=1 ! fakesink \
* 2>&1 | grep "enabling tracers"
[...] _priv_gst_tracing_init: enabling tracers: 'log'
* ```
*
* ### Using the log tracer
*
* This tracer logs accross a number of categories at the `TRACE` level.
*
* **For this reason, you need to set `GST_DEBUG` to capture the output from
* this plugin.**
*
* These are the logging categories under which the different hooks operate:
*
* * `GST_DEBUG=GST_BUFFER:TRACE`
* * `pad-push-pre`, `pad-push-post`
* * `pad-pull-range-pre`, `pad-pull-range-post`
* * `GST_DEBUG=GST_BUFFER_LIST:TRACE`
* * `pad-push-list-pre`, `pad-push-list-post`
* * `GST_DEBUG=GST_EVENT:TRACE`
* * `pad-push-event-pre`, `pad-push-event-post`
* * `GST_DEBUG=GST_QUERY:TRACE`
* * `pad-query-pre`, `pad-query-post`
* * `element-query-pre`, `element-query-post`
* * `GST_DEBUG=GST_MESSAGE:TRACE`
* * `element-post-message-pre`, `element-post-message-post`
* * `GST_DEBUG=GST_ELEMENT_FACTORY:TRACE`
* * `element-new`
* * `GST_DEBUG=GST_ELEMENT_PADS:TRACE`
* * `element-add-pad`
* * `element-remove-pad`
* * `GST_DEBUG=GST_STATES:TRACE`
* * `element-change-state-pre`, `element-change-state-post`
* * `GST_DEBUG=GST_BIN:TRACE`
* * `bin-add-pre`, `bin-add-post`
* * `bin-remove-pre`, `bin-remove-post`
* * `GST_DEBUG=GST_PADS:TRACE`
* * `pad-link-pre`, `pad-link-post`
* * `pad-unlink-pre`, `pad-unlink-post`
*
* Since the categories mentioned above are not exclusive to this tracer
* plugin, but are also used by core GStreamer code, you should expect a lot of
* unrelated logging to appear.
*
* On the other hand, the functions in this plugin have a consistent naming
* scheme, which should make it easy to filter the logs: `do_{hook_name}`
*
* ### Example
*
* As an example, if we wanted to log the flow of events and pads being linked
* we could run the following command:
*
* ```
* $ GST_TRACERS="log" \
* GST_DEBUG=GST_EVENT:TRACE,GST_PADS:TRACE \
* gst-play-1.0 file.webm \
* 2>&1 | egrep -w 'do_(pad_link)_(pre|post):'
* [...]
* [...] GST_PADS :0:do_pad_link_pre:<typefind:src> 0:00:00.096516923, src=<typefind:src>, sink=<matroskademux0:sink>
* [...] GST_PADS :0:do_pad_link_post:<typefind:src> 0:00:00.096678191, src=<typefind:src>, sink=<matroskademux0:sink>, res=0
* [...] GST_PADS :0:do_pad_link_pre:<matroskademux0:audio_0> 0:00:00.103133773, src=<matroskademux0:audio_0>, sink=<decodepad1:proxypad2>
* [...] GST_PADS :0:do_pad_link_post:<matroskademux0:audio_0> 0:00:00.103567148, src=<matroskademux0:audio_0>, sink=<decodepad1:proxypad2>, res=0
* [...]
* [...] GST_EVENT :0:do_push_event_pre:<vp8dec0:sink> 0:00:00.930848627, pad=<vp8dec0:sink>, event=qos event: 0x7fec9c00c0a0, time 99:99:99.999999999, seq-num 393, GstEventQOS, type=(GstQOSType)overflow, proportion=(double)0.036137789409526271, diff=(gint64)-29350000, timestamp=(guint64)533000000;
* [...] GST_EVENT :0:do_push_event_pre:<multiqueue0:sink_1> 0:00:00.930901498, pad=<multiqueue0:sink_1>, event=qos event: 0x7fec9c00c0a0, time 99:99:99.999999999, seq-num 393, GstEventQOS, type=(GstQOSType)overflow, proportion=(double)0.036137789409526271, diff=(gint64)-29350000, timestamp=(guint64)533000000;
* [...] GST_EVENT :0:do_push_event_post:<multiqueue0:sink_1> 0:00:00.931041882, pad=<multiqueue0:sink_1>, res=1
* [...] GST_EVENT :0:do_push_event_post:<vp8dec0:sink> 0:00:00.931082112, pad=<vp8dec0:sink>, res=1
* [...]
* ```
*/
#ifdef HAVE_CONFIG_H