X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=docs%2Ftracing.txt;h=bfc261bcaf595163d8fa2316e84c04e9c9efae13;hb=HEAD;hp=21183f9a6869dafbd7b66974f06cd65cc8e8df62;hpb=e54b7f5256659dddaf6b5c021847859829d7ebd7;p=qemu.git diff --git a/docs/tracing.txt b/docs/tracing.txt index 21183f9a6..bfc261bca 100644 --- a/docs/tracing.txt +++ b/docs/tracing.txt @@ -9,53 +9,56 @@ for debugging, profiling, and observing execution. 1. Build with the 'simple' trace backend: - ./configure --trace-backend=simple + ./configure --enable-trace-backend=simple make -2. Enable trace events you are interested in: +2. Create a file with the events you want to trace: - $EDITOR trace-events # remove "disable" from events you want + echo bdrv_aio_readv > /tmp/events + echo bdrv_aio_writev >> /tmp/events 3. Run the virtual machine to produce a trace file: - qemu ... # your normal QEMU invocation + qemu -trace events=/tmp/events ... # your normal QEMU invocation 4. Pretty-print the binary trace file: - ./simpletrace.py trace-events trace-* + ./scripts/simpletrace.py trace-events trace-* == 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" + qemu_vmalloc(size_t size, void *ptr) "size %zu ptr %p" + qemu_vfree(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: #include "trace.h" /* needed for trace event prototype */ - - void *qemu_malloc(size_t size) + + void *qemu_vmalloc(size_t size) { void *ptr; - if (!size && !allow_zero_malloc()) { - abort(); + size_t align = QEMU_VMALLOC_ALIGN; + + if (size < align) { + align = getpagesize(); } - ptr = oom_check(malloc(size ? size : 1)); - trace_qemu_malloc(size, ptr); /* <-- trace event */ + ptr = qemu_memalign(align, size); + trace_qemu_vmalloc(size, ptr); return ptr; } === 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: @@ -74,10 +77,7 @@ Trace events should use types as follows: 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"". +respectively. This ensures portability between 32- and 64-bit platforms. === Hints for adding new trace events === @@ -98,17 +98,45 @@ portability macros, ensure they are preceded and followed by double quotes: 4. Name trace events after their function. If there are multiple trace events in one function, append a unique distinguisher at the end of the name. -5. Declare trace events with the "disable" keyword. Some trace events can - produce a lot of output and users are typically only interested in a subset - of trace events. Marking trace events disabled by default saves the user - from having to manually disable noisy trace events. +== Generic interface and monitor commands == + +You can programmatically query and control the state of trace events through a +backend-agnostic interface provided by the header "trace/control.h". + +Note that some of the backends do not provide an implementation for some parts +of this interface, in which case QEMU will just print a warning (please refer to +header "trace/control.h" to see which routines are backend-dependent). + +The state of events can also be queried and modified through monitor commands: + +* info trace-events + View available trace events and their state. State 1 means enabled, state 0 + means disabled. + +* trace-event NAME on|off + Enable/disable a given trace event or a group of events (using wildcards). + +The "-trace events=" command line argument can be used to enable the +events listed in from the very beginning of the program. This file must +contain one event name per line. + +If a line in the "-trace events=" file begins with a '-', the trace event +will be disabled instead of enabled. This is useful when a wildcard was used +to enable an entire family of events but one noisy event needs to be disabled. + +Wildcard matching is supported in both the monitor command "trace-event" and the +events list file. That means you can enable/disable the events having a common +prefix in a batch. For example, virtio-blk trace events could be enabled using +the following monitor command: + + trace-event virtio_blk_* on == 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 @@ -126,6 +154,17 @@ The "nop" backend generates empty trace event functions so that the compiler can optimize out trace events completely. This is the default and imposes no performance penalty. +Note that regardless of the selected trace backend, events with the "disable" +property will be generated with the "nop" backend. + +=== 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 @@ -133,52 +172,39 @@ source tree. It may not be as powerful as platform-specific or third-party trace backends but it is portable. This is the recommended trace backend unless you have specific needs for more advanced backends. -=== Stderr === - -The "stderr" backend sends trace events directly to standard error output -during emulation. +The "simple" backend currently does not capture string arguments, it simply +records the char* pointer value instead of the string that is pointed to. -==== Monitor commands ==== +=== Ftrace === -* info trace - Display the contents of trace buffer. This command dumps the trace buffer - with simple formatting. For full pretty-printing, use the simpletrace.py - script on a binary trace file. +The "ftrace" backend writes trace data to ftrace marker. This effectively +sends trace events to ftrace ring buffer, and you can compare qemu trace +data and kernel(especially kvm.ko when using KVM) trace data. - The trace buffer is written into until full. The full trace buffer is - flushed and emptied. This means the 'info trace' will display few or no - entries if the buffer has just been flushed. +if you use KVM, enable kvm events in ftrace: -* info trace-events - View available trace events and their state. State 1 means enabled, state 0 - means disabled. + # echo 1 > /sys/kernel/debug/tracing/events/kvm/enable -* trace-event NAME on|off - Enable/disable a given trace event. +After running qemu by root user, you can get the trace: -* trace-file on|off|flush|set - Enable/disable/flush the trace file or set the trace file name. + # cat /sys/kernel/debug/tracing/trace -==== Enabling/disabling trace events programmatically ==== +Restriction: "ftrace" backend is restricted to Linux only. -The st_change_trace_event_state() function can be used to enable or disable trace -events at runtime inside QEMU: +==== Monitor commands ==== - #include "trace.h" - - st_change_trace_event_state("virtio_irq", true); /* enable */ - [...] - st_change_trace_event_state("virtio_irq", false); /* disable */ +* trace-file on|off|flush|set + Enable/disable/flush the trace file or set the trace file name. ==== 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 + ./scripts/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. @@ -187,3 +213,61 @@ 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-name x86_64 \ + qemu.stp + +== Trace event properties == + +Each event in the "trace-events" file can be prefixed with a space-separated +list of zero or more of the following event properties. + +=== "disable" === + +If a specific trace event is going to be invoked a huge number of times, this +might have a noticeable performance impact even when the event is +programmatically disabled. + +In this case you should declare such event with the "disable" property. This +will effectively disable the event at compile time (by using the "nop" backend), +thus having no performance impact at all on regular builds (i.e., unless you +edit the "trace-events" file). + +In addition, there might be cases where relatively complex computations must be +performed to generate values that are only used as arguments for a trace +function. In these cases you can use the macro 'TRACE_${EVENT_NAME}_ENABLED' to +guard such computations and avoid its compilation when the event is disabled: + + #include "trace.h" /* needed for trace event prototype */ + + void *qemu_vmalloc(size_t size) + { + void *ptr; + size_t align = QEMU_VMALLOC_ALIGN; + + if (size < align) { + align = getpagesize(); + } + ptr = qemu_memalign(align, size); + if (TRACE_QEMU_VMALLOC_ENABLED) { /* preprocessor macro */ + void *complex; + /* some complex computations to produce the 'complex' value */ + trace_qemu_vmalloc(size, ptr, complex); + } + return ptr; + } + +You can check both if the event has been disabled and is dynamically enabled at +the same time using the 'trace_event_get_state' routine (see header +"trace/control.h" for more information).