= GStreamer tracing library =
This package contains a library that hooks into some gstreamer key functions and
logs the behaviour. When the application exits it can display some general
statistics. Further analysis can be done based on the data written to the
logfile. The packages also includes a UI to display pipeline structure and some
statistics.

The idea is not avoid adding API for performance meassurement to gstreamer.
http://bugzilla.gnome.org/show_bug.cgi?id=353680

Right now it logs
* dataflow, messages, queries and events.
* caps set|get
* pipeline topology changes
* ressource usage

It can also do some sanity checks on dataflow.

== Log Format ==
* we log into one file for performance reasons and split later

== Running ==
The tracelib can be used uninstalled like this:
LD_PRELOAD=src/.libs/libgsttracelib.so gst-launch-0.10 fakesrc num-buffers=10 ! fakesink
LD_PRELOAD=src/.libs/libgsttracelib.so gst-launch-0.10 videotestsrc num-buffers=50 ! xvimagesink
LD_PRELOAD=src/.libs/libgsttracelib.so gst-launch-0.10 filesrc location=$HOME/audio/bladerun.mod ! decodebin ! alsasink
LD_PRELOAD=src/.libs/libgsttracelib.so GSTTL_NO_LOG=1 gst-launch-0.10 filesrc location=$HOME/audio/klingon.mp3 ! decodebin2 ! fakesink sync=true
LD_PRELOAD=src/.libs/libgsttracelib.so GSTTL_NO_LOG=1 gst-launch-0.10 filesrc location=$HOME/video/XMen3Trailer.avi ! decodebin2 name=decodebin ! xvimagesink decodebin. ! audioconvert ! alsasink
LD_PRELOAD=src/.libs/libgsttracelib.so GSTTL_NO_LOG=1 gst-launch-0.10 filesrc location=$HOME/video/XMen3Trailer.avi ! decodebin2 name=decodebin ! fakesink sync=true name=vsink decodebin. ! fakesink sync=true name=asink
LD_PRELOAD=src/.libs/libgsttracelib.so GSTTL_NO_LOG=1 gst-launch-0.10 playbin uri=file://$HOME/video/cairo-dock-2.ogg
LD_PRELOAD=src/.libs/libgsttracelib.so gst-seek 16 uri=file://$HOME/video/cairo-dock-2.ogg
LD_PRELOAD=src/.libs/libgsttracelib.so gst-launch-0.10 --gst-disable-registry-update playbin2 uri=file:///home/ensonic/video/TheChubbChubbs.divx311.avi flags=99

LD_PRELOAD=src/.libs/libgsttracelib.so gst-launch-0.10 --gst-disable-registry-update audiotestsrc num-buffers=50 ! audio/x-raw-int,channels=1,hello=5 ! pulsesink

LD_PRELOAD="/usr/lib/libv4l/v4l2convert.so src/.libs/libgsttracelib.so" gst-launch-0.10 camerabin

If it is installed, one can use the 'gsttl' wrapper script to ldpreload the lib.

There are some additional env vars to influence the behaviour:
GSTTL_LOG_NAME - full path to log file
  "/tmp/gsttl.log" if empty
  "-" for stdout
GSTTL_LOG_SIZE - size of preallocated logbuffer
  if not given or 0 gsttracelib uses linebuffered file logging,
  if a size is given a memory buffer of that many bytes is preallocated and all
  events are logged to the memory, the buffer is written at the end of the run
  if the memory buffer was too small, only a partial log is written and a message
  at the end tells how much would have been needed
GSTTL_LOG_SERVER - 127.0.0.1:34567 ip+port or servername+port
  if both values are given send the log data over the network
GSTTL_NO_LOG - do not log if set to anything
GSTTL_NO_STATS - don't collect any statistics

GSTTL_{SHOW,HIDE} - specify log details, multiple entries separated with ';' (no spaces)
  defaults (none given) are GSTTL_SHOW=<all>, GSTTL_HIDE=<none>
  these are the details: "caps;chk;ev;mallinfo;msg;pad;qry;rusage;topo"

Specifying both GSTTL_NO_LOG, GSTTL_NO_STATS is quite useless. Turning off the
statistics will lower the overhead when capturing the trace (FIXME: ideally we
will do statistics based on the log file). Also turning of some log details
(e.g. mallinfo or rusage) can save overhead.

== Exploration ==
=== Plot graphs using gnuplot >=4.3 ===
; preprocess the data
rm -r /tmp/gsttl
./src/gsttl_splitlog.py
; plot as png
./src/gsttl_plot.sh --format=png | gnuplot
eog /tmp/gsttl.png
; plot as svg (default)
./src/gsttl_plot.sh | gnuplot
evince /tmp/gsttl.svg
rsvg-view /tmp/gsttl.svg

=== gsttlui ===
run the UI:
  gsttlui --log-port=8765
make some noise:
  cat gsttl.log | netcat 127.0.0.1 8765
  GSTTL_LOG_SERVER=127.0.0.1:8765 gsttl gst-launch-0.10 fakesrc num-buffers=100 ! fakesink

Instead of the UI one can also use netcat again:
  netcat -l -p 8765 127.0.0.1
  netcat -l 127.0.0.1 8765
  
If the package is configured with --enable-trace one can get debug prints from the UI:
  GSTTLUI_DEBUG=1 gsttlui
  
If the UI crashes it is most likely graphviz :/
quite broken version (e.g. on opensuse 11.3)
- graphviz version 2.26.3 (20100126.1600)
very broken version (e.g. on ubuntu 10.4)
- graphviz version 2.20.2

=== In the future ===
pygtk ui using mathplotlib
gst-debug-viewer

== Ideas ==
* could be used in gst-qa-system (aka insanity) suite as a monitor