== Trace events ==
-There is a set of static trace events declared in the trace-events source
+There is a set of static trace events declared in the "trace-events" source
file. Each trace event declaration names the event, its arguments, and the
format string which can be used for pretty-printing:
qemu_malloc(size_t size, void *ptr) "size %zu ptr %p"
qemu_free(void *ptr) "ptr %p"
-The trace-events file is processed by the tracetool script during build to
+The "trace-events" file is processed by the "tracetool" script during build to
generate code for the trace events. Trace events are invoked directly from
source code like this:
=== Declaring trace events ===
-The tracetool script produces the trace.h header file which is included by
+The "tracetool" script produces the trace.h header file which is included by
every source file that uses trace events. Since many source files include
-trace.h, it uses a minimum of types and other header files included to keep
-the namespace clean and compile times and dependencies down.
+trace.h, it uses a minimum of types and other header files included to keep the
+namespace clean and compile times and dependencies down.
Trace events should use types as follows:
cannot include all user-defined struct declarations and it is therefore
necessary to use void * for pointers to structs.
+ Pointers (including char *) cannot be dereferenced easily (or at all) in
+ some trace backends. If pointers are used, ensure they are meaningful by
+ themselves and do not assume the data they point to will be traced. Do
+ not pass in string arguments.
+
* For everything else, use primitive scalar types (char, int, long) with the
appropriate signedness.
+Format strings should reflect the types defined in the trace event. Take
+special care to use PRId64 and PRIu64 for int64_t and uint64_t types,
+respectively. This ensures portability between 32- and 64-bit platforms. Note
+that format strings must begin and end with double quotes. When using
+portability macros, ensure they are preceded and followed by double quotes:
+"value %"PRIx64"".
+
=== Hints for adding new trace events ===
1. Trace state changes in the code. Interesting points in the code usually
== Trace backends ==
-The tracetool script automates tedious trace event code generation and also
+The "tracetool" script automates tedious trace event code generation and also
keeps the trace event declarations independent of the trace backend. The trace
events are not tightly coupled to a specific trace backend, such as LTTng or
-SystemTap. Support for trace backends can be added by extending the tracetool
+SystemTap. Support for trace backends can be added by extending the "tracetool"
script.
The trace backend is chosen at configure time and only one trace backend can
can optimize out trace events completely. This is the default and imposes no
performance penalty.
+=== Stderr ===
+
+The "stderr" backend sends trace events directly to standard error. This
+effectively turns trace events into debug printfs.
+
+This is the simplest backend and can be used together with existing code that
+uses DPRINTF().
+
=== Simpletrace ===
The "simple" backend supports common use cases and comes as part of the QEMU
==== Analyzing trace files ====
The "simple" backend produces binary trace files that can be formatted with the
-simpletrace.py script. The script takes the trace-events file and the binary
+simpletrace.py script. The script takes the "trace-events" file and the binary
trace:
./simpletrace.py trace-events trace-12345
-You must ensure that the same trace-events file was used to build QEMU,
+You must ensure that the same "trace-events" file was used to build QEMU,
otherwise trace event declarations may have changed and output will not be
consistent.
The "ust" backend uses the LTTng Userspace Tracer library. There are no
monitor commands built into QEMU, instead UST utilities should be used to list,
enable/disable, and dump traces.
+
+=== SystemTap ===
+
+The "dtrace" backend uses DTrace sdt probes but has only been tested with
+SystemTap. When SystemTap support is detected a .stp file with wrapper probes
+is generated to make use in scripts more convenient. This step can also be
+performed manually after a build in order to change the binary name in the .stp
+probes:
+
+ scripts/tracetool --dtrace --stap \
+ --binary path/to/qemu-binary \
+ --target-type system \
+ --target-arch x86_64 \
+ <trace-events >qemu.stp