docs/devel/tracing.rst

19     $ qemu --trace "memory_region_ops_*" ...
24 This output comes from the "log" trace backend that is enabled by default when
25 ``./configure --enable-trace-backends=BACKENDS`` was not explicitly specified.
27 Multiple patterns can be specified by repeating the ``--trace`` option::
29     $ qemu --trace "kvm_*" --trace "virtio_*" ...
32 file to avoid long command-line options::
36     $ qemu --trace events=/tmp/events ...
38 Trace events
41 Sub-directory setup
42 -------------------
44 Each directory in the source tree can declare a set of trace events in a local
45 "trace-events" file. All directories which contain "trace-events" files must be
46 listed in the "trace_events_subdirs" variable in the top level meson.build
47 file. During build, the "trace-events" file in each listed subdirectory will be
48 processed by the "tracetool" script to generate code for the trace events.
50 The individual "trace-events" files are merged into a "trace-events-all" file,
55 The following files are automatically generated in <builddir>/trace/ during the
56 build:
58  - trace-<subdir>.c - the trace event state declarations
59  - trace-<subdir>.h - the trace event enums and probe functions
60  - trace-dtrace-<subdir>.h - DTrace event probe specification
61  - trace-dtrace-<subdir>.dtrace - DTrace event probe helper declaration
62  - trace-dtrace-<subdir>.o - binary DTrace provider (generated by dtrace)
63  - trace-ust-<subdir>.h - UST event probe helper declarations
65 Here <subdir> is the sub-directory path with '/' replaced by '_'. For example,
66 "accel/kvm" becomes "accel_kvm" and the final filename for "trace-<subdir>.c"
67 becomes "trace-accel_kvm.c".
70 "<builddir>/trace/". Instead they #include the local "trace.h" file, without
71 any sub-directory path prefix. eg io/channel-buffer.c would do::
73   #include "trace.h"
75 The "io/trace.h" file must be created manually with an #include of the
76 corresponding "trace/trace-<subdir>.h" file that will be generated in the
79   $ echo '#include "trace/trace-io.h"' >io/trace.h
81 While it is possible to include a trace.h file from outside a source file's own
82 sub-directory, this is discouraged in general. It is strongly preferred that
83 all events be declared directly in the sub-directory that uses them. The only
84 exception is where there are some shared trace events defined in the top level
85 directory trace-events file.  The top level directory generates trace files
86 with a filename prefix of "trace/trace-root" instead of just "trace". This is
87 to avoid ambiguity between a trace.h in the current directory, vs the top level
90 Using trace events
91 ------------------
93 Trace events are invoked directly from source code like this::
95     #include "trace.h"  /* needed for trace event prototype */
110 Declaring trace events
111 ----------------------
113 The "tracetool" script produces the trace.h header file which is included by
114 every source file that uses trace events.  Since many source files include
115 trace.h, it uses a minimum of types and other header files included to keep the
118 Trace events should use types as follows:
120  * Use stdint.h types for fixed-size types.  Most offsets and guest memory
121    addresses are best represented with uint32_t or uint64_t.  Use fixed-size
123    (32-bit versus 64-bit) so trace events don't truncate values or break
124    the build.
126  * Use void * for pointers to structs or for arrays.  The trace.h header
127    cannot include all user-defined struct declarations and it is therefore
138 Format strings should reflect the types defined in the trace event.  Take
140 respectively.  This ensures portability between 32- and 64-bit platforms.
145 finally a format string for pretty-printing. For example::
151 Hints for adding new trace events
152 ---------------------------------
154 1. Trace state changes in the code.  Interesting points in the code usually
156    changes are good trace events because they can be used to understand the
157    execution of the system.
159 2. Trace guest operations.  Guest I/O accesses like reading device registers
160    are good trace events because they can be used to understand guest
163 3. Use correlator fields so the context of an individual line of trace output
164    can be understood.  For example, trace the pointer returned by malloc and
166    Trace events with no context are not very useful.
168 4. Name trace events after their function.  If there are multiple trace events
174 You can programmatically query and control the state of trace events through a
175 backend-agnostic interface provided by the header "trace/control.h".
179 header "trace/control.h" to see which routines are backend-dependent).
183 * ``info trace-events``
184   View available trace events and their state.  State 1 means enabled, state 0
187 * ``trace-event NAME on|off``
188   Enable/disable a given trace event or a group of events (using wildcards).
190 The "--trace events=<file>" command line argument can be used to enable the
194 If a line in the "--trace events=<file>" file begins with a '-', the trace event
198 Wildcard matching is supported in both the monitor command "trace-event" and the
200 prefix in a batch. For example, virtio-blk trace events could be enabled using
203     trace-event virtio_blk_* on
205 Trace backends
208 The "tracetool" script automates tedious trace event code generation and also
209 keeps the trace event declarations independent of the trace backend.  The trace
210 events are not tightly coupled to a specific trace backend, such as LTTng or
211 SystemTap.  Support for trace backends can be added by extending the "tracetool"
214 The trace backends are chosen at configure time::
216     ./configure --enable-trace-backends=simple,dtrace
218 For a list of supported trace backends, try ./configure --help or see below.
219 If multiple backends are enabled, the trace is sent to them all.
224 The following subsections describe the supported trace backends.
227 ---
229 The "nop" backend generates empty trace event functions so that the compiler
230 can optimize out trace events completely.  This imposes no performance
233 Note that regardless of the selected trace backend, events with the "disable"
237 ---
239 The "log" backend sends trace events directly to standard error.  This
240 effectively turns trace events into debug printfs.
245 The -msg timestamp=on|off command-line option controls whether or not to print
246 the tid/timestamp prefix for each trace event.
249 -----------
251 The "simple" backend writes binary trace logs to a file from a thread, making
253 offline trace file analysis scripts. It may not be as powerful as
254 platform-specific or third-party trace backends but it is portable and has no
260 * ``trace-file on|off|flush|set <path>``
261   Enable/disable/flush the trace file or set the trace file name.
263 Analyzing trace files
266 The "simple" backend produces binary trace files that can be formatted with the
267 simpletrace.py script.  The script takes the "trace-events-all" file and the
268 binary trace::
270     ./scripts/simpletrace.py trace-events-all trace-12345
272 You must ensure that the same "trace-events-all" file was used to build QEMU,
273 otherwise trace event declarations may have changed and output will not be
277 ------
279 The "ftrace" backend writes trace data to ftrace marker. This effectively
280 sends trace events to ftrace ring buffer, and you can compare qemu trace
281 data and kernel(especially kvm.ko when using KVM) trace data.
287 After running qemu by root user, you can get the trace::
289    # cat /sys/kernel/debug/tracing/trace
294 ------
296 The "syslog" backend sends trace events using the POSIX syslog API. The log
301 NOTE: syslog may squash duplicate consecutive trace events and apply rate
307 ----------------------
309 The "ust" backend uses the LTTng Userspace Tracer library.  There are no
310 monitor commands built into QEMU, instead UST utilities should be used to list,
313 Package lttng-tools is required for userspace tracing. You must ensure that the
315 lttng-sessiond daemon for the current user prior to running any instance of
321     lttng list -u
329     lttng enable-event qemu:g_malloc -u
331 Where the events can either be a comma-separated list of events, or "-a" to
337 View the trace::
345 Babeltrace can be used at any later time to view the trace::
347     babeltrace $HOME/lttng-traces/mysession-<date>-<time>
350 ---------
355 performed manually after a build in order to change the binary name in the .stp
358     scripts/tracetool.py --backends=dtrace --format=stap \
359                          --binary path/to/qemu-binary \
360                          --probe-prefix qemu.system.x86_64 \
361                          --group=all \
362                          trace-events-all \
366 logging of certain probes, a helper script "qemu-trace-stap" is provided.
369 Trace event properties
372 Each event in the "trace-events-all" file can be prefixed with a space-separated
376 ---------
378 If a specific trace event is going to be invoked a huge number of times, this
385 edit the "trace-events-all" file).
388 performed to generate values that are only used as arguments for a trace
391 compile-time disabled or run-time disabled. If the event is compile-time
396     #include "trace.h"  /* needed for trace event prototype */