qemu/docs/tracing.txt
<<
>>
Prefs
   1= Tracing =
   2
   3== Introduction ==
   4
   5This document describes the tracing infrastructure in QEMU and how to use it
   6for debugging, profiling, and observing execution.
   7
   8== Quickstart ==
   9
  101. Build with the 'simple' trace backend:
  11
  12    ./configure --enable-trace-backends=simple
  13    make
  14
  152. Create a file with the events you want to trace:
  16
  17   echo bdrv_aio_readv   > /tmp/events
  18   echo bdrv_aio_writev >> /tmp/events
  19
  203. Run the virtual machine to produce a trace file:
  21
  22    qemu -trace events=/tmp/events ... # your normal QEMU invocation
  23
  244. Pretty-print the binary trace file:
  25
  26    ./scripts/simpletrace.py trace-events trace-* # Override * with QEMU <pid>
  27
  28== Trace events ==
  29
  30There is a set of static trace events declared in the "trace-events" source
  31file.  Each trace event declaration names the event, its arguments, and the
  32format string which can be used for pretty-printing:
  33
  34    qemu_vmalloc(size_t size, void *ptr) "size %zu ptr %p"
  35    qemu_vfree(void *ptr) "ptr %p"
  36
  37The "trace-events" file is processed by the "tracetool" script during build to
  38generate code for the trace events.  Trace events are invoked directly from
  39source code like this:
  40
  41    #include "trace.h"  /* needed for trace event prototype */
  42    
  43    void *qemu_vmalloc(size_t size)
  44    {
  45        void *ptr;
  46        size_t align = QEMU_VMALLOC_ALIGN;
  47     
  48        if (size < align) {
  49            align = getpagesize();
  50        }
  51        ptr = qemu_memalign(align, size);
  52        trace_qemu_vmalloc(size, ptr);
  53        return ptr;
  54    }
  55
  56=== Declaring trace events ===
  57
  58The "tracetool" script produces the trace.h header file which is included by
  59every source file that uses trace events.  Since many source files include
  60trace.h, it uses a minimum of types and other header files included to keep the
  61namespace clean and compile times and dependencies down.
  62
  63Trace events should use types as follows:
  64
  65 * Use stdint.h types for fixed-size types.  Most offsets and guest memory
  66   addresses are best represented with uint32_t or uint64_t.  Use fixed-size
  67   types over primitive types whose size may change depending on the host
  68   (32-bit versus 64-bit) so trace events don't truncate values or break
  69   the build.
  70
  71 * Use void * for pointers to structs or for arrays.  The trace.h header
  72   cannot include all user-defined struct declarations and it is therefore
  73   necessary to use void * for pointers to structs.
  74
  75 * For everything else, use primitive scalar types (char, int, long) with the
  76   appropriate signedness.
  77
  78Format strings should reflect the types defined in the trace event.  Take
  79special care to use PRId64 and PRIu64 for int64_t and uint64_t types,
  80respectively.  This ensures portability between 32- and 64-bit platforms.
  81
  82=== Hints for adding new trace events ===
  83
  841. Trace state changes in the code.  Interesting points in the code usually
  85   involve a state change like starting, stopping, allocating, freeing.  State
  86   changes are good trace events because they can be used to understand the
  87   execution of the system.
  88
  892. Trace guest operations.  Guest I/O accesses like reading device registers
  90   are good trace events because they can be used to understand guest
  91   interactions.
  92
  933. Use correlator fields so the context of an individual line of trace output
  94   can be understood.  For example, trace the pointer returned by malloc and
  95   used as an argument to free.  This way mallocs and frees can be matched up.
  96   Trace events with no context are not very useful.
  97
  984. Name trace events after their function.  If there are multiple trace events
  99   in one function, append a unique distinguisher at the end of the name.
 100
 101== Generic interface and monitor commands ==
 102
 103You can programmatically query and control the state of trace events through a
 104backend-agnostic interface provided by the header "trace/control.h".
 105
 106Note that some of the backends do not provide an implementation for some parts
 107of this interface, in which case QEMU will just print a warning (please refer to
 108header "trace/control.h" to see which routines are backend-dependent).
 109
 110The state of events can also be queried and modified through monitor commands:
 111
 112* info trace-events
 113  View available trace events and their state.  State 1 means enabled, state 0
 114  means disabled.
 115
 116* trace-event NAME on|off
 117  Enable/disable a given trace event or a group of events (using wildcards).
 118
 119The "-trace events=<file>" command line argument can be used to enable the
 120events listed in <file> from the very beginning of the program. This file must
 121contain one event name per line.
 122
 123If a line in the "-trace events=<file>" file begins with a '-', the trace event
 124will be disabled instead of enabled.  This is useful when a wildcard was used
 125to enable an entire family of events but one noisy event needs to be disabled.
 126
 127Wildcard matching is supported in both the monitor command "trace-event" and the
 128events list file. That means you can enable/disable the events having a common
 129prefix in a batch. For example, virtio-blk trace events could be enabled using
 130the following monitor command:
 131
 132    trace-event virtio_blk_* on
 133
 134== Trace backends ==
 135
 136The "tracetool" script automates tedious trace event code generation and also
 137keeps the trace event declarations independent of the trace backend.  The trace
 138events are not tightly coupled to a specific trace backend, such as LTTng or
 139SystemTap.  Support for trace backends can be added by extending the "tracetool"
 140script.
 141
 142The trace backends are chosen at configure time:
 143
 144    ./configure --enable-trace-backends=simple
 145
 146For a list of supported trace backends, try ./configure --help or see below.
 147If multiple backends are enabled, the trace is sent to them all.
 148
 149The following subsections describe the supported trace backends.
 150
 151=== Nop ===
 152
 153The "nop" backend generates empty trace event functions so that the compiler
 154can optimize out trace events completely.  This is the default and imposes no
 155performance penalty.
 156
 157Note that regardless of the selected trace backend, events with the "disable"
 158property will be generated with the "nop" backend.
 159
 160=== Log ===
 161
 162The "log" backend sends trace events directly to standard error.  This
 163effectively turns trace events into debug printfs.
 164
 165This is the simplest backend and can be used together with existing code that
 166uses DPRINTF().
 167
 168=== Simpletrace ===
 169
 170The "simple" backend supports common use cases and comes as part of the QEMU
 171source tree.  It may not be as powerful as platform-specific or third-party
 172trace backends but it is portable.  This is the recommended trace backend
 173unless you have specific needs for more advanced backends.
 174
 175=== Ftrace ===
 176
 177The "ftrace" backend writes trace data to ftrace marker. This effectively
 178sends trace events to ftrace ring buffer, and you can compare qemu trace
 179data and kernel(especially kvm.ko when using KVM) trace data.
 180
 181if you use KVM, enable kvm events in ftrace:
 182
 183   # echo 1 > /sys/kernel/debug/tracing/events/kvm/enable
 184
 185After running qemu by root user, you can get the trace:
 186
 187   # cat /sys/kernel/debug/tracing/trace
 188
 189Restriction: "ftrace" backend is restricted to Linux only.
 190
 191==== Monitor commands ====
 192
 193* trace-file on|off|flush|set <path>
 194  Enable/disable/flush the trace file or set the trace file name.
 195
 196==== Analyzing trace files ====
 197
 198The "simple" backend produces binary trace files that can be formatted with the
 199simpletrace.py script.  The script takes the "trace-events" file and the binary
 200trace:
 201
 202    ./scripts/simpletrace.py trace-events trace-12345
 203
 204You must ensure that the same "trace-events" file was used to build QEMU,
 205otherwise trace event declarations may have changed and output will not be
 206consistent.
 207
 208=== LTTng Userspace Tracer ===
 209
 210The "ust" backend uses the LTTng Userspace Tracer library.  There are no
 211monitor commands built into QEMU, instead UST utilities should be used to list,
 212enable/disable, and dump traces.
 213
 214Package lttng-tools is required for userspace tracing. You must ensure that the
 215current user belongs to the "tracing" group, or manually launch the
 216lttng-sessiond daemon for the current user prior to running any instance of
 217QEMU.
 218
 219While running an instrumented QEMU, LTTng should be able to list all available
 220events:
 221
 222    lttng list -u
 223
 224Create tracing session:
 225
 226    lttng create mysession
 227
 228Enable events:
 229
 230    lttng enable-event qemu:g_malloc -u
 231
 232Where the events can either be a comma-separated list of events, or "-a" to
 233enable all tracepoint events. Start and stop tracing as needed:
 234
 235    lttng start
 236    lttng stop
 237
 238View the trace:
 239
 240    lttng view
 241
 242Destroy tracing session:
 243
 244    lttng destroy
 245
 246Babeltrace can be used at any later time to view the trace:
 247
 248    babeltrace $HOME/lttng-traces/mysession-<date>-<time>
 249
 250=== SystemTap ===
 251
 252The "dtrace" backend uses DTrace sdt probes but has only been tested with
 253SystemTap.  When SystemTap support is detected a .stp file with wrapper probes
 254is generated to make use in scripts more convenient.  This step can also be
 255performed manually after a build in order to change the binary name in the .stp
 256probes:
 257
 258    scripts/tracetool.py --backends=dtrace --format=stap \
 259                         --binary path/to/qemu-binary \
 260                         --target-type system \
 261                         --target-name x86_64 \
 262                         <trace-events >qemu.stp
 263
 264== Trace event properties ==
 265
 266Each event in the "trace-events" file can be prefixed with a space-separated
 267list of zero or more of the following event properties.
 268
 269=== "disable" ===
 270
 271If a specific trace event is going to be invoked a huge number of times, this
 272might have a noticeable performance impact even when the event is
 273programmatically disabled.
 274
 275In this case you should declare such event with the "disable" property. This
 276will effectively disable the event at compile time (by using the "nop" backend),
 277thus having no performance impact at all on regular builds (i.e., unless you
 278edit the "trace-events" file).
 279
 280In addition, there might be cases where relatively complex computations must be
 281performed to generate values that are only used as arguments for a trace
 282function. In these cases you can use the macro 'TRACE_${EVENT_NAME}_ENABLED' to
 283guard such computations and avoid its compilation when the event is disabled:
 284
 285    #include "trace.h"  /* needed for trace event prototype */
 286    
 287    void *qemu_vmalloc(size_t size)
 288    {
 289        void *ptr;
 290        size_t align = QEMU_VMALLOC_ALIGN;
 291    
 292        if (size < align) {
 293            align = getpagesize();
 294        }
 295        ptr = qemu_memalign(align, size);
 296        if (TRACE_QEMU_VMALLOC_ENABLED) { /* preprocessor macro */
 297            void *complex;
 298            /* some complex computations to produce the 'complex' value */
 299            trace_qemu_vmalloc(size, ptr, complex);
 300        }
 301        return ptr;
 302    }
 303
 304You can check both if the event has been disabled and is dynamically enabled at
 305the same time using the 'trace_event_get_state' routine (see header
 306"trace/control.h" for more information).
 307
 308=== "tcg" ===
 309
 310Guest code generated by TCG can be traced by defining an event with the "tcg"
 311event property. Internally, this property generates two events:
 312"<eventname>_trans" to trace the event at translation time, and
 313"<eventname>_exec" to trace the event at execution time.
 314
 315Instead of using these two events, you should instead use the function
 316"trace_<eventname>_tcg" during translation (TCG code generation). This function
 317will automatically call "trace_<eventname>_trans", and will generate the
 318necessary TCG code to call "trace_<eventname>_exec" during guest code execution.
 319
 320Events with the "tcg" property can be declared in the "trace-events" file with a
 321mix of native and TCG types, and "trace_<eventname>_tcg" will gracefully forward
 322them to the "<eventname>_trans" and "<eventname>_exec" events. Since TCG values
 323are not known at translation time, these are ignored by the "<eventname>_trans"
 324event. Because of this, the entry in the "trace-events" file needs two printing
 325formats (separated by a comma):
 326
 327    tcg foo(uint8_t a1, TCGv_i32 a2) "a1=%d", "a1=%d a2=%d"
 328
 329For example:
 330
 331    #include "trace-tcg.h"
 332    
 333    void some_disassembly_func (...)
 334    {
 335        uint8_t a1 = ...;
 336        TCGv_i32 a2 = ...;
 337        trace_foo_tcg(a1, a2);
 338    }
 339
 340This will immediately call:
 341
 342    void trace_foo_trans(uint8_t a1);
 343
 344and will generate the TCG code to call:
 345
 346    void trace_foo(uint8_t a1, uint32_t a2);
 347
 348=== "vcpu" ===
 349
 350Identifies events that trace vCPU-specific information. It implicitly adds a
 351"CPUState*" argument, and extends the tracing print format to show the vCPU
 352information. If used together with the "tcg" property, it adds a second
 353"TCGv_env" argument that must point to the per-target global TCG register that
 354points to the vCPU when guest code is executed (usually the "cpu_env" variable).
 355
 356The following example events:
 357
 358    foo(uint32_t a) "a=%x"
 359    vcpu bar(uint32_t a) "a=%x"
 360    tcg vcpu baz(uint32_t a) "a=%x", "a=%x"
 361
 362Can be used as:
 363
 364    #include "trace-tcg.h"
 365    
 366    CPUArchState *env;
 367    TCGv_ptr cpu_env;
 368    
 369    void some_disassembly_func(...)
 370    {
 371        /* trace emitted at this point */
 372        trace_foo(0xd1);
 373        /* trace emitted at this point */
 374        trace_bar(ENV_GET_CPU(env), 0xd2);
 375        /* trace emitted at this point (env) and when guest code is executed (cpu_env) */
 376        trace_baz_tcg(ENV_GET_CPU(env), cpu_env, 0xd3);
 377    }
 378
 379If the translating vCPU has address 0xc1 and code is later executed by vCPU
 3800xc2, this would be an example output:
 381
 382    // at guest code translation
 383    foo a=0xd1
 384    bar cpu=0xc1 a=0xd2
 385    baz_trans cpu=0xc1 a=0xd3
 386    // at guest code execution
 387    baz_exec cpu=0xc2 a=0xd3
 388