draft-tracing: update draft design with timer ideas

diff --git a/docs/design/draft-tracing.txt b/docs/design/draft-tracing.txt
index bf28924..39c20fb 100644 (file)
--- a/docs/design/draft-tracing.txt
+++ b/docs/design/draft-tracing.txt
@@ -1,12 +1,13 @@
 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 life
+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.
+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
@@ -25,16 +26,19 @@ 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 somthing along the lines of:
+it will become something along the lines of:
 if (__tracer) {
   gst_tracer_push_buffer (pad, buffer);
 }
 
-Plugins can attach to a specific (named) hook or to groups of them. Groups could be:
-all, topology, communication. When a hook such as gst_tracer_push_buffer () is called
-it will take a timstamp and call all attached plugins from all, each group and this
-hook. 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.
+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?
 
@@ -43,20 +47,31 @@ Plugins
 
 meminfo
 -------
-- register to the "all" group.
+- register to an interval-timer hook.
 - call mallinfo() and log memory usage
 
 rusage
 ------
-- register to the "all" group.
-- call getrusage() and log ressource usage
+- register to an interval-timer hook.
+- call getrusage() and log resource usage
 
 dbus
 ----
-- provide a dbus iface to announe applications that are traced
+- 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
+  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
 ==
@@ -70,7 +85,7 @@ the app.
 
 gst-trace-stats
 ---------------
-Such a tool could read a trace and sumarize the content like gst-tracelib did for
+Such a tool could read a trace and summarize the content like gst-tracelib did for
 stats in 0.10.