[14/14] trace: Add user documentation

Signed-off-by: Stefan Hajnoczi <stefanha@linux.vnet.ibm.com>
---
 docs/tracing.txt |  149 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 149 insertions(+), 0 deletions(-)
 create mode 100644 docs/tracing.txt

On 08/12/2010 05:36 AM, Stefan Hajnoczi wrote:
> Signed-off-by: Stefan Hajnoczi<stefanha@linux.vnet.ibm.com>
>    

I very much like that you use wiki formatting.

> ---
>   docs/tracing.txt |  149 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>   1 files changed, 149 insertions(+), 0 deletions(-)
>   create mode 100644 docs/tracing.txt
>
> diff --git a/docs/tracing.txt b/docs/tracing.txt
> new file mode 100644
> index 0000000..fe3c6ac
> --- /dev/null
> +++ b/docs/tracing.txt
> @@ -0,0 +1,149 @@
> += Tracing =
> +
> +== Introduction ==
> +
> +This document describes the tracing infrastructure in QEMU and how to use it
> +for debugging, profiling, and observing execution.
> +
> +== Quickstart ==
> +
> +1. Build with the 'simple' trace backend:
> +
> +    ./configure --trace-backend=simple
> +    make
> +
> +2. Run the virtual machine to produce a trace file:
> +
> +    qemu ... # your normal QEMU invocation
> +
> +3. Pretty-print the binary trace file:
> +
> +    ./simpletrace.py trace-events /tmp/trace-*
> +
> +== Trace events ==
> +
> +There is a set of static trace events declared in the trace-events source
> +file.  Each trace event declaration names the event, its arguments, and the
> +format string which can be used for pretty-printing:
> +
> +    qemu_malloc(size_t size, void *ptr) "size %zu ptr %p"
> +    qemu_free(void *ptr) "ptr %p"
> +
> +The trace-events file is processed by the tracetool script during build to
> +generate code for the trace events.  Trace events are invoked directly from
> +source code like this:
> +
> +    #include "trace.h"  /* needed for trace event prototype */
> +
> +    void *qemu_malloc(size_t size)
> +    {
> +        void *ptr;
> +        if (!size&&  !allow_zero_malloc()) {
> +            abort();
> +        }
> +        ptr = oom_check(malloc(size ? size : 1));
> +        trace_qemu_malloc(size, ptr);  /*<-- trace event */
> +        return ptr;
> +    }
> +
> +This is all that needs to be known from a user perspective for adding new
> +trace events.
>    

Please add some information about the restrictions on types.  Clearly, 
you can't specify just any type in the trace file so what set of types 
are allowed?

Regards,

Anthony Liguori

> +=== Hints for adding new trace events ===
> +
> +1. Trace state changes in the code.  Interesting points in the code usually
> +   involve a state change like starting, stopping, allocating, freeing.  State
> +   changes are good trace events because they can be used to understand the
> +   execution of the system.
> +
> +2. Trace guest operations.  Guest I/O accesses like reading device registers
> +   are good trace events because they can be used to understand guest
> +   interactions.
> +
> +3. Use correlator fields so the context of an individual line of trace output
> +   can be understood.  For example, trace the pointer returned by malloc and
> +   used as an argument to free.  This way mallocs and frees can be matched up.
> +   Trace events with no context are not very useful.
> +
> +4. Name trace events after their function.  If there are multiple trace events
> +   in one function, append a unique distinguisher at the end of the name.
> +
> +== Trace backends ==
> +
> +The tracetool script automates tedious trace event code generation and also
> +keeps the trace event declarations independent of the trace backend.  The trace
> +events are not tightly coupled to a specific trace backend, such as LTTng or
> +SystemTap.  Support for trace backends can be added by extending the tracetool
> +script.
> +
> +The trace backend is chosen at configure time and only one trace backend can
> +be built into the binary:
> +
> +    ./configure --trace-backend=simple
> +
> +For a list of supported trace backends, try ./configure --help or see below.
> +
> +The following subsections describe the supported trace backends.
> +
> +=== Nop ===
> +
> +The "nop" backend generates empty trace event functions so that the compiler
> +can optimize out trace events completely.  This is the default and imposes no
> +performance penalty.
> +
> +=== Simpletrace ===
> +
> +The "simple" backend supports common use cases and comes as part of the QEMU
> +source tree.  It may not be as powerful as platform-specific or third-party
> +trace backends but it is portable.  This is the recommended trace backend
> +unless you have specific needs for more advanced backends.
> +
> +==== Monitor commands ====
> +
> +* info trace
> +  Display the contents of trace buffer.  This command dumps the trace buffer
> +  with simple formatting.  For full pretty-printing, use the simpletrace.py
> +  script on a binary trace file.
> +
> +  The trace buffer is written into until full.  The full trace buffer is
> +  flushed and emptied.  This means the 'info trace' will display few or no
> +  entries if the buffer has just been flushed.
> +
> +* info trace-events
> +  View available trace events and their state.  State 1 means enabled, state 0
> +  means disabled.
> +
> +* trace-event NAME on|off
> +  Enable/disable a given trace event.
> +
> +* trace-file on|off|flush|set<path>
> +  Enable/disable/flush the trace file or set the trace file name.
> +
> +==== Enabling/disabling trace events programmatically ====
> +
> +The st_change_trace_event_state() function can be used to enable or disable trace
> +events at runtime inside QEMU:
> +
> +    #include "trace.h"
> +
> +    st_change_trace_event_state("virtio_irq", true); /* enable */
> +    [...]
> +    st_change_trace_event_state("virtio_irq", false); /* disable */
> +
> +==== Analyzing trace files ====
> +
> +The "simple" backend produces binary trace files that can be formatted with the
> +simpletrace.py script.  The script takes the trace-events file and the binary
> +trace:
> +
> +    ./simpletrace.py trace-events /tmp/trace.log
> +
> +You must ensure that the same trace-events file was used to build QEMU,
> +otherwise trace event declarations may have changed and output will not be
> +consistent.
> +
> +=== LTTng Userspace Tracer ===
> +
> +The "ust" backend uses the LTTng Userspace Tracer library.  There are no
> +monitor commands built into QEMU, instead UST utilities should be used to list,
> +enable/disable, and dump traces.
>

On Sun, Aug 22, 2010 at 04:47:17PM -0500, Anthony Liguori wrote:
> Please add some information about the restrictions on types.
> Clearly, you can't specify just any type in the trace file so what
> set of types are allowed?

Sure, will fix in v2.

Stefan