Patchwork [14/14] trace: Add user documentation

login
register
mail settings
Submitter Stefan Hajnoczi
Date Aug. 12, 2010, 10:36 a.m.
Message ID <1281609395-17621-15-git-send-email-stefanha@linux.vnet.ibm.com>
Download mbox | patch
Permalink /patch/61553/
State New
Headers show

Comments

Stefan Hajnoczi - Aug. 12, 2010, 10:36 a.m.
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
Anthony Liguori - Aug. 22, 2010, 9:47 p.m.
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.
>
Stefan Hajnoczi - Aug. 23, 2010, 10:11 a.m.
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

Patch

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.
+
+=== 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.