docs/design/draft-tracing.txt

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 && __tracer_hook_is_used) {
  gst_tracer_push_buffer (pad, buffer);
}

TODO(ensonic): we should eval if we can use something like jump_label in the kernel
- http://lwn.net/Articles/412072/ + http://lwn.net/Articles/435215/
- http://lxr.free-electrons.com/source/kernel/jump_label.c
- http://lxr.free-electrons.com/source/include/linux/jump_label.h
- http://lxr.free-electrons.com/source/arch/x86/kernel/jump_label.c
TODO(ensonic): liblttng-ust provides such a mechanism for user-space
- but this is mostly about logging traces
- it is linux specific :/

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 (=read) 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