docs/devel/tracing.rst

19     $ qemu --trace "memory_region_ops_*" ...
21 …19585@1608130130.441188:memory_region_ops_read cpu 0 mr 0x562fdfbb3820 addr 0x3cc value 0x67 size 1
22 …585@1608130130.441190:memory_region_ops_write cpu 0 mr 0x562fdfbd2f00 addr 0x3d4 value 0x70e size 2
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 ...
41 Sub-directory setup
42 -------------------
45 "trace-events" file. All directories which contain "trace-events" files must be
47 file. During build, the "trace-events" file in each listed subdirectory will be
50 The individual "trace-events" files are merged into a "trace-events-all" file,
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".
71 any sub-directory path prefix. eg io/channel-buffer.c would do::
76 corresponding "trace/trace-<subdir>.h" file that will be generated in the
79   $ echo '#include "trace/trace-io.h"' >io/trace.h
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
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
91 ------------------
97     void *qemu_vmalloc(size_t size)
102         if (size < align) {
105         ptr = qemu_memalign(align, size);
106         trace_qemu_vmalloc(size, ptr);
111 ----------------------
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
122    types over primitive types whose size may change depending on the host
123    (32-bit versus 64-bit) so trace events don't truncate values or break
127    cannot include all user-defined struct declarations and it is therefore
140 respectively.  This ensures portability between 32- and 64-bit platforms.
145 finally a format string for pretty-printing. For example::
147     qemu_vmalloc(size_t size, void *ptr) "size %zu ptr %p"
152 ---------------------------------
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``
187 * ``trace-event NAME on|off``
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
216     ./configure --enable-trace-backends=simple,dtrace
218 For a list of supported trace backends, try ./configure --help or see below.
227 ---
237 ---
245 The -msg timestamp=on|off command-line option controls whether or not to print
249 -----------
254 platform-specific or third-party trace backends but it is portable and has no
260 * ``trace-file on|off|flush|set <path>``
267 simpletrace.py script.  The script takes the "trace-events-all" file and the
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,
276 Ftrace  section in Trace backends
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
283 if you use KVM, enable kvm events in ftrace::
291 Restriction: "ftrace" backend is restricted to Linux only.
294 ------
307 ----------------------
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
347     babeltrace $HOME/lttng-traces/mysession-<date>-<time>
350 ---------
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.
372 Each event in the "trace-events-all" file can be prefixed with a space-separated
376 ---------
385 edit the "trace-events-all" file).
391 compile-time disabled or run-time disabled. If the event is compile-time
398     void *qemu_vmalloc(size_t size)
403         if (size < align) {
406         ptr = qemu_memalign(align, size);
410             trace_qemu_vmalloc(size, ptr, complex);