Statistics
| Branch: | Revision:

root / docs / tracing.txt @ 9a85d394

History | View | Annotate | Download (6.5 kB)

1
= Tracing =
2

    
3
== Introduction ==
4

    
5
This document describes the tracing infrastructure in QEMU and how to use it
6
for debugging, profiling, and observing execution.
7

    
8
== Quickstart ==
9

    
10
1. Build with the 'simple' trace backend:
11

    
12
    ./configure --trace-backend=simple
13
    make
14

    
15
2. Enable trace events you are interested in:
16

    
17
    $EDITOR trace-events  # remove "disable" from events you want
18

    
19
3. Run the virtual machine to produce a trace file:
20

    
21
    qemu ... # your normal QEMU invocation
22

    
23
4. Pretty-print the binary trace file:
24

    
25
    ./simpletrace.py trace-events trace-*
26

    
27
== Trace events ==
28

    
29
There is a set of static trace events declared in the trace-events source
30
file.  Each trace event declaration names the event, its arguments, and the
31
format string which can be used for pretty-printing:
32

    
33
    qemu_malloc(size_t size, void *ptr) "size %zu ptr %p"
34
    qemu_free(void *ptr) "ptr %p"
35

    
36
The trace-events file is processed by the tracetool script during build to
37
generate code for the trace events.  Trace events are invoked directly from
38
source code like this:
39

    
40
    #include "trace.h"  /* needed for trace event prototype */
41

    
42
    void *qemu_malloc(size_t size)
43
    {
44
        void *ptr;
45
        if (!size && !allow_zero_malloc()) {
46
            abort();
47
        }
48
        ptr = oom_check(malloc(size ? size : 1));
49
        trace_qemu_malloc(size, ptr);  /* <-- trace event */
50
        return ptr;
51
    }
52

    
53
=== Declaring trace events ===
54

    
55
The tracetool script produces the trace.h header file which is included by
56
every source file that uses trace events.  Since many source files include
57
trace.h, it uses a minimum of types and other header files included to keep
58
the namespace clean and compile times and dependencies down.
59

    
60
Trace events should use types as follows:
61

    
62
 * Use stdint.h types for fixed-size types.  Most offsets and guest memory
63
   addresses are best represented with uint32_t or uint64_t.  Use fixed-size
64
   types over primitive types whose size may change depending on the host
65
   (32-bit versus 64-bit) so trace events don't truncate values or break
66
   the build.
67

    
68
 * Use void * for pointers to structs or for arrays.  The trace.h header
69
   cannot include all user-defined struct declarations and it is therefore
70
   necessary to use void * for pointers to structs.
71

    
72
 * For everything else, use primitive scalar types (char, int, long) with the
73
   appropriate signedness.
74

    
75
Format strings should reflect the types defined in the trace event.  Take
76
special care to use PRId64 and PRIu64 for int64_t and uint64_t types,
77
respectively.  This ensures portability between 32- and 64-bit platforms.
78

    
79
=== Hints for adding new trace events ===
80

    
81
1. Trace state changes in the code.  Interesting points in the code usually
82
   involve a state change like starting, stopping, allocating, freeing.  State
83
   changes are good trace events because they can be used to understand the
84
   execution of the system.
85

    
86
2. Trace guest operations.  Guest I/O accesses like reading device registers
87
   are good trace events because they can be used to understand guest
88
   interactions.
89

    
90
3. Use correlator fields so the context of an individual line of trace output
91
   can be understood.  For example, trace the pointer returned by malloc and
92
   used as an argument to free.  This way mallocs and frees can be matched up.
93
   Trace events with no context are not very useful.
94

    
95
4. Name trace events after their function.  If there are multiple trace events
96
   in one function, append a unique distinguisher at the end of the name.
97

    
98
5. Declare trace events with the "disable" keyword.  Some trace events can
99
   produce a lot of output and users are typically only interested in a subset
100
   of trace events.  Marking trace events disabled by default saves the user
101
   from having to manually disable noisy trace events.
102

    
103
== Trace backends ==
104

    
105
The tracetool script automates tedious trace event code generation and also
106
keeps the trace event declarations independent of the trace backend.  The trace
107
events are not tightly coupled to a specific trace backend, such as LTTng or
108
SystemTap.  Support for trace backends can be added by extending the tracetool
109
script.
110

    
111
The trace backend is chosen at configure time and only one trace backend can
112
be built into the binary:
113

    
114
    ./configure --trace-backend=simple
115

    
116
For a list of supported trace backends, try ./configure --help or see below.
117

    
118
The following subsections describe the supported trace backends.
119

    
120
=== Nop ===
121

    
122
The "nop" backend generates empty trace event functions so that the compiler
123
can optimize out trace events completely.  This is the default and imposes no
124
performance penalty.
125

    
126
=== Simpletrace ===
127

    
128
The "simple" backend supports common use cases and comes as part of the QEMU
129
source tree.  It may not be as powerful as platform-specific or third-party
130
trace backends but it is portable.  This is the recommended trace backend
131
unless you have specific needs for more advanced backends.
132

    
133
==== Monitor commands ====
134

    
135
* info trace
136
  Display the contents of trace buffer.  This command dumps the trace buffer
137
  with simple formatting.  For full pretty-printing, use the simpletrace.py
138
  script on a binary trace file.
139

    
140
  The trace buffer is written into until full.  The full trace buffer is
141
  flushed and emptied.  This means the 'info trace' will display few or no
142
  entries if the buffer has just been flushed.
143

    
144
* info trace-events
145
  View available trace events and their state.  State 1 means enabled, state 0
146
  means disabled.
147

    
148
* trace-event NAME on|off
149
  Enable/disable a given trace event.
150

    
151
* trace-file on|off|flush|set <path>
152
  Enable/disable/flush the trace file or set the trace file name.
153

    
154
==== Enabling/disabling trace events programmatically ====
155

    
156
The st_change_trace_event_state() function can be used to enable or disable trace
157
events at runtime inside QEMU:
158

    
159
    #include "trace.h"
160
    
161
    st_change_trace_event_state("virtio_irq", true); /* enable */
162
    [...]
163
    st_change_trace_event_state("virtio_irq", false); /* disable */
164

    
165
==== Analyzing trace files ====
166

    
167
The "simple" backend produces binary trace files that can be formatted with the
168
simpletrace.py script.  The script takes the trace-events file and the binary
169
trace:
170

    
171
    ./simpletrace.py trace-events trace-12345
172

    
173
You must ensure that the same trace-events file was used to build QEMU,
174
otherwise trace event declarations may have changed and output will not be
175
consistent.
176

    
177
=== LTTng Userspace Tracer ===
178

    
179
The "ust" backend uses the LTTng Userspace Tracer library.  There are no
180
monitor commands built into QEMU, instead UST utilities should be used to list,
181
enable/disable, and dump traces.