docs/devel/tracing.rst

19     $ qemu --trace "memory_region_ops_*" ...
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 -------------------
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
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".
69 Source files in the source tree do not directly include generated files in
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 ------------------
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
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::
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``
184   View available trace events and their state.  State 1 means enabled, state 0
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,
277 ------
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
337 View the trace::
339     lttng view
345 Babeltrace can be used at any later time to view the trace::
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