docs/devel/tracing.rst

10 This document describes the tracing infrastructure in QEMU and how to use it
24 This output comes from the "log" trace backend that is enabled by default when
27 Multiple patterns can be specified by repeating the ``--trace`` option::
44 Each directory in the source tree can declare a set of trace events in a local
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,
52 This merged file is to be used by the "simpletrace.py" script to later analyse
53 traces in the simpletrace data format.
55 The following files are automatically generated in <builddir>/trace/ during the
58  - trace-<subdir>.c - the trace event state declarations
59  - trace-<subdir>.h - the trace event enums and probe functions
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"
69 Source files in the source tree do not directly include generated files in
70 "<builddir>/trace/". Instead they #include the local "trace.h" file, without
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
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
87 to avoid ambiguity between a trace.h in the current directory, vs the top level
113 The "tracetool" script produces the trace.h header file which is included by
115 trace.h, it uses a minimum of types and other header files included to keep the
122    types over primitive types whose size may change depending on the host
124    the build.
126  * Use void * for pointers to structs or for arrays.  The trace.h header
130  * For everything else, use primitive scalar types (char, int, long) with the
135    instead.  This may require scaling the value first by multiplying it by 1000
136    or the like when digits after the decimal point need to be preserved.
138 Format strings should reflect the types defined in the trace event.  Take
141 Format strings must not end with a newline character.  It is the responsibility
144 Each event declaration will start with the event name, then its arguments,
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.
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
169    in one function, append a unique distinguisher at the end of the name.
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".
177 Note that some of the backends do not provide an implementation for some parts
181 The state of events can also be queried and modified through monitor commands:
190 The "--trace events=<file>" command line argument can be used to enable the
191 events listed in <file> from the very beginning of the program. This file must
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
199 events list file. That means you can enable/disable the events having a common
201 the following monitor command::
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
211 SystemTap.  Support for trace backends can be added by extending the "tracetool"
214 The trace backends are chosen at configure time::
219 If multiple backends are enabled, the trace is sent to them all.
221 If no backends are explicitly selected, configure will default to the
224 The following subsections describe the supported trace backends.
229 The "nop" backend generates empty trace event functions so that the compiler
233 Note that regardless of the selected trace backend, events with the "disable"
234 property will be generated with the "nop" backend.
239 The "log" backend sends trace events directly to standard error.  This
242 This is the simplest backend and can be used together with existing code that
245 The -msg timestamp=on|off command-line option controls whether or not to print
246 the tid/timestamp prefix for each trace event.
251 The "simple" backend writes binary trace logs to a file from a thread, making
252 it lower overhead than the "log" backend. A Python API is available for writing
261   Enable/disable/flush the trace file or set the trace file name.
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
272 You must ensure that the same "trace-events-all" file was used to build QEMU,
279 The "ftrace" backend writes trace data to ftrace marker. This effectively
287 After running qemu by root user, you can get the trace::
296 The "syslog" backend sends trace events using the POSIX syslog API. The log
297 is opened specifying the LOG_DAEMON facility and LOG_PID option (so events
298 are tagged with the pid of the particular QEMU process that generated
309 The "ust" backend uses the LTTng Userspace Tracer library.  There are no
313 Package lttng-tools is required for userspace tracing. You must ensure that the
314 current user belongs to the "tracing" group, or manually launch the
315 lttng-sessiond daemon for the current user prior to running any instance of
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::
352 The "dtrace" backend uses DTrace sdt probes but has only been tested with
355 performed manually after a build in order to change the binary name in the .stp
372 Each event in the "trace-events-all" file can be prefixed with a space-separated
373 list of zero or more of the following event properties.
379 might have a noticeable performance impact even when the event is
382 In this case you should declare such event with the "disable" property. This
383 will effectively disable the event at compile time (by using the "nop" backend),
385 edit the "trace-events-all" file).
390 guard such computations, so they are skipped if the event has been either
391 compile-time disabled or run-time disabled. If the event is compile-time
409             /* some complex computations to produce the 'complex' value */