From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from [140.186.70.92] (port=33378 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OnIRm-0007fF-Kw for qemu-devel@nongnu.org; Sun, 22 Aug 2010 17:55:33 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OnINr-0007rw-C6 for qemu-devel@nongnu.org; Sun, 22 Aug 2010 17:47:20 -0400 Received: from mail-gy0-f173.google.com ([209.85.160.173]:49785) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OnINr-0007rr-87 for qemu-devel@nongnu.org; Sun, 22 Aug 2010 17:47:19 -0400 Received: by gyh4 with SMTP id 4so2066519gyh.4 for ; Sun, 22 Aug 2010 14:47:18 -0700 (PDT) Message-ID: <4C719AE5.3090405@codemonkey.ws> Date: Sun, 22 Aug 2010 16:47:17 -0500 From: Anthony Liguori MIME-Version: 1.0 Subject: Re: [Qemu-devel] [PATCH 14/14] trace: Add user documentation References: <1281609395-17621-1-git-send-email-stefanha@linux.vnet.ibm.com> <1281609395-17621-15-git-send-email-stefanha@linux.vnet.ibm.com> In-Reply-To: <1281609395-17621-15-git-send-email-stefanha@linux.vnet.ibm.com> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Stefan Hajnoczi Cc: Julien Desfossez , qemu-devel@nongnu.org, Prerna Saxena On 08/12/2010 05:36 AM, Stefan Hajnoczi wrote: > Signed-off-by: Stefan Hajnoczi > 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 > + 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. >