1 files changed, 96 insertions, 0 deletions
diff --git a/docs/design/draft-tracing.txt b/docs/design/draft-tracing.txt
new file mode 100644
index 0000000..39c20fb
--- /dev/null
+++ b/docs/design/draft-tracing.txt
@@ -0,0 +1,96 @@
+Tracing
+=======
+
+This subsystem will provide a mechanism to get structured tracing info from GStreamer
+applications. This can be used for post-run analysis as well as for live
+introspection.
+
+We are going to introduce a GstTracer object. There will be only a single instance
+per process or none if tracing is off (not enabled via envvar or compiled out).
+
+Certain GStreamer core function (such as gst_pad_push or gst_element_add_pad) will
+call into the tracer. The tracer will dispatch into loaded tracing plugins.
+Developers will be able to select a list of plugins by setting an environment
+variable, such as GST_TRACE="meminfo,dbus". When then plugins are loaded, they will
+add them to certain hooks. Another env var GST_TRACE_CHANNEL can be used to send
+the tracing to a file or a socket (Do the same for GST_DEBUG_CHANNEL). The syntax
+could be GST_XXX_CHANNEL=file:///path/to/file or GST_XXX_CHANNEL=tcp://<ip>:<port>.
+If no channel is set, the tracing goes to stderr like the debug logging.
+
+TODO(ensonic): we might want to have GST_{DEBUG|TRACE)_FORMAT envars as well. These
+could be raw, ansi-color, binary, ...
+
+Hooks
+-----
+e.g. gst_pad_push() will do add this line:
+GST_TRACER_PUSH_BUFFER (pad, buffer)
+
+If tracing is disable at compile time the macro will evaluate to nothing. Otherwise
+it will become something along the lines of:
+if (__tracer) {
+  gst_tracer_push_buffer (pad, buffer);
+}
+
+In addition to api hooks we should also provide timer hooks. Interval timers are
+useful to get e.g. resource usage snapshots. Also absolute timers might make sense. 
+
+Plugins can attach handlers to one or more hooks. When a hook such as
+gst_tracer_push_buffer () is called it will take a timestamp and call all attached
+handlers. Hooks will be called from misc threads. The trace plugins should only
+consume the provided data. Most trace plugins will log data to a trace channel.
+
+
+TODO(ensonic): use GSignal for the hooks?
+
+Plugins
+=======
+
+meminfo
+-------
+- register to an interval-timer hook.
+- call mallinfo() and log memory usage
+
+rusage
+------
+- register to an interval-timer hook.
+- call getrusage() and log resource usage
+
+dbus
+----
+- provide a dbus iface to announce applications that are traced
+- tracing UIs can use the dbus iface to find the channels where logging and tracing
+  is getting logged to, one would start the tracing UI first and when the
+  application is started with tracing activated, the dbus plugin will announce the
+  new application, upon which the tracing UI can start reading from the log channels
+
+topology
+--------
+- register to pipeline topology hooks
+- tracing UIs can show a live pipeline graph
+
+communication
+-------------
+- register to buffer, event, message and query flow
+- tracing apps can do e.g. statistics
+
+UI
+==
+
+gst-debug-viewer
+----------------
+gst-debug-viewer could be given the tracelog in addition to the debug log.
+Alternatively it would show a dialog that shows all local apps (if the dbus plugin
+is loaded) and read the log streams from the sockets/files that are configured for
+the app.
+
+gst-trace-stats
+---------------
+Such a tool could read a trace and summarize the content like gst-tracelib did for
+stats in 0.10.
+
+
+Problems / Open items
+=====================
+- when connecting to a running app, we cant easily get the 'current' state if logging
+is using a socket, as past events are not stored
+