docs/design/draft-tracing.txt

   1 Tracing
   2 =======
   3
   4 This subsystem will provide a mechanism to get structured tracing info from GStreamer
   5 applications. This can be used for post-run analysis as well as for live
   6 introspection.
   7
   8 We are going to introduce a GstTracer object. There will be only a single instance
   9 per process or none if tracing is off (not enabled via envvar or compiled out).
  10
  11 Certain GStreamer core function (such as gst_pad_push or gst_element_add_pad) will
  12 call into the tracer. The tracer will dispatch into loaded tracing plugins.
  13 Developers will be able to select a list of plugins by setting an environment
  14 variable, such as GST_TRACE="meminfo,dbus". One can also pass parameters to
  15 plugins:  GST_TRACE="log(events;buffers),stats(all)".
  16 When then plugins are loaded, we'll add them to certain hooks according to that
  17 they are interested in.
  18
  19 Another env var GST_TRACE_CHANNEL can be used to send the tracing to a file or
  20 a socket (Do the same for GST_DEBUG_CHANNEL). The syntax could be
  21 GST_XXX_CHANNEL=file:///path/to/file or GST_XXX_CHANNEL=tcp://<ip>:<port>.
  22 If no channel is set, the tracing goes to stderr like the debug logging.
  23
  24 TODO(ensonic): we might want to have GST_{DEBUG|TRACE)_FORMAT envars as well.
  25 These could be raw, ansi-color, binary, suitable for babeltrace (see lttng), ...
  26
  27 With these we can deprecate GST_DEBUG_FILE and GST_DEBUG_NO_COLOR.
  28
  29 Hook api
  30 --------
  31 e.g. gst_pad_push() would become:
  32
  33 #ifndef GST_DISABLE_GST_DEBUG
  34 static inline GstFlowReturn __gst_pad_push (GstPad * pad, GstBuffer * buffer);
  35 #endif
  36
  37 GstFlowReturn
  38 gst_pad_push (GstPad * pad, GstBuffer * buffer)
  39 #ifndef GST_DISABLE_GST_DEBUG
  40 {
  41   if (__tracer_enabled && __tracer_hook_is_used)
  42     gst_tracer_push_buffer_pre (pad, buffer);
  43   GstFlowReturn res = __gst_pad_push (GstPad * pad, GstBuffer * buffer);
  44   if (__tracer_enabled && __tracer_hook_is_used)
  45     gst_tracer_push_buffer_post (pad, res);
  46   return res;
  47 }
  48
  49 static inline GstFlowReturn
  50 __gst_pad_push (GstPad * pad, GstBuffer * buffer)
  51 #endif
  52 {
  53   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
  54   g_return_val_if_fail (GST_PAD_IS_SRC (pad), GST_FLOW_ERROR);
  55   g_return_val_if_fail (GST_IS_BUFFER (buffer), GST_FLOW_ERROR);
  56
  57   return gst_pad_push_data (pad,
  58       GST_PAD_PROBE_TYPE_BUFFER | GST_PAD_PROBE_TYPE_PUSH, buffer);
  59 }
  60
  61 TODO(ensonic): gcc has some magic for wrapping functions
  62 - http://gcc.gnu.org/onlinedocs/gcc/Constructing-Calls.html
  63 - http://www.clifford.at/cfun/gccfeat/#gccfeat05.c
  64
  65 TODO(ensonic): we should eval if we can use something like jump_label in the kernel
  66 - http://lwn.net/Articles/412072/ + http://lwn.net/Articles/435215/
  67 - http://lxr.free-electrons.com/source/kernel/jump_label.c
  68 - http://lxr.free-electrons.com/source/include/linux/jump_label.h
  69 - http://lxr.free-electrons.com/source/arch/x86/kernel/jump_label.c
  70 TODO(ensonic): liblttng-ust provides such a mechanism for user-space
  71 - but this is mostly about logging traces
  72 - it is linux specific :/
  73
  74 In addition to api hooks we should also provide timer hooks. Interval timers are
  75 useful to get e.g. resource usage snapshots. Also absolute timers might make
  76 sense. All this could be implemented with a clock thread.
  77
  78 Hooks
  79 -----
  80   gst_bin_add
  81   gst_bin_remove
  82   gst_element_add_pad
  83   gst_element_post_message
  84   gst_element_query
  85   gst_element_remove_pad
  86   gst_pad_link
  87   gst_pad_pull_range
  88   gst_pad_push
  89   gst_pad_push_list
  90   gst_pad_push_event
  91   gst_pad_unlink
  92
  93 Plugin api
  94 ----------
  95
  96 TracerPlugins are plugin features. They have a simple api:
  97
  98 GstTracerHookMask init(gchar *params);
  99 Plugins can attach handlers to one or more hooks. They use a HookMask to tell
 100 which events they are interested in. The params are the extra detail from the
 101 environment var.
 102
 103 void invoke(GstStructure *s);
 104 Hooks marshall the parameters given to a trace hook into a GstStructure and also
 105 add some extra into such as a timestamp. The hooks will receive this structure.
 106 Hooks will be called from misc threads. The trace plugins should only consume
 107 (=read) the provided data. Most trace plugins will log data to a trace channel.
 108
 109 void done(void);
 110 Plugins can output results and release data. This would ideally be done at the
 111 end of the applications, but gst_deinit() is not mandatory. gst_tracelib was
 112 using a gcc_destructor
 113
 114 Plugins ideas
 115 =============
 116
 117 We can have some under gstreamer/plugins/tracers/
 118
 119 meminfo
 120 -------
 121 - register to an interval-timer hook.
 122 - call mallinfo() and log memory usage
 123
 124 rusage
 125 ------
 126 - register to an interval-timer hook.
 127 - call getrusage() and log resource usage
 128
 129 dbus
 130 ----
 131 - provide a dbus iface to announce applications that are traced
 132 - tracing UIs can use the dbus iface to find the channels where logging and tracing
 133   is getting logged to
 134 - one would start the tracing UI first and when the application is started with
 135   tracing activated, the dbus plugin will announce the new application,
 136   upon which the tracing UI can start reading from the log channels, this avoid
 137   missing some data
 138
 139 topology
 140 --------
 141 - register to pipeline topology hooks
 142 - tracing UIs can show a live pipeline graph
 143
 144 stats
 145 -----
 146 - register to buffer, event, message and query flow
 147 - tracing apps can do e.g. statistics
 148
 149 UI
 150 ==
 151
 152 gst-debug-viewer
 153 ----------------
 154 gst-debug-viewer could be given the tracelog in addition to the debug log.
 155 Alternatively it would show a dialog that shows all local apps (if the dbus plugin
 156 is loaded) and read the log streams from the sockets/files that are configured for
 157 the app.
 158
 159 gst-tracer
 160 ----------
 161 Counterpart of gst-tracelib-ui
 162
 163
 164 Problems / Open items
 165 =====================
 166 - when hooking into a timer, should we just have some predefined intervals?
 167 - how to trigger the shutdown processing?
 168 - when connecting to a running app, we cant easily get the 'current' state if logging
 169 is using a socket, as past events are not stored
 170
 171
 172 Try it
 173 ======
 174 GST_DEBUG="GST_REG*:4,GST_TRACER:4,log:7" GST_TRACE=log gst-launch-1.0 fakesrc num-buffers=10 ! fakesink
 175 - traces for buffer flow in TRACE level and default category
 176