docs/devel/tracing.rst

17 events::
34     $ echo "memory_region_ops_*" >/tmp/events
35     $ echo "kvm_*" >>/tmp/events
36     $ qemu --trace events=/tmp/events ...
38 Trace events
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
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,
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
90 Using trace events
93 Trace events are invoked directly from source code like this::
110 Declaring trace events
114 every source file that uses trace events.  Since many source files include
118 Trace events should use types as follows:
123    (32-bit versus 64-bit) so trace events don't truncate values or break
151 Hints for adding new trace events
156    changes are good trace events because they can be used to understand the
160    are good trace events because they can be used to understand guest
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
181 The state of events can also be queried and modified through monitor commands:
183 * ``info trace-events``
184   View available trace events and their state.  State 1 means enabled, state 0
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
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
196 to enable an entire family of events but one noisy event needs to be disabled.
199 events list file. That means you can enable/disable the events having a common
200 prefix in a batch. For example, virtio-blk trace events could be enabled using
210 events are not tightly coupled to a specific trace backend, such as LTTng or
230 can optimize out trace events completely.  This imposes no performance
233 Note that regardless of the selected trace backend, events with the "disable"
239 The "log" backend sends trace events directly to standard error.  This
240 effectively turns trace events into debug printfs.
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,
280 sends trace events to ftrace ring buffer, and you can compare qemu trace
283 if you use KVM, enable kvm events in ftrace::
285    # echo 1 > /sys/kernel/debug/tracing/events/kvm/enable
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
299 them). All events are logged at LOG_INFO level.
301 NOTE: syslog may squash duplicate consecutive trace events and apply rate
319 events::
327 Enable events::
331 Where the events can either be a comma-separated list of events, or "-a" to
332 enable all tracepoint events. Start and stop tracing as needed::
362                          trace-events-all \
372 Each event in the "trace-events-all" file can be prefixed with a space-separated
385 edit the "trace-events-all" file).