Message ID | 1281609395-17621-15-git-send-email-stefanha@linux.vnet.ibm.com |
---|---|
State | New |
Headers | show |
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
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.
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