diff options
Diffstat (limited to 'docs/tracing.txt')
| -rw-r--r-- | docs/tracing.txt | 73 |
1 files changed, 47 insertions, 26 deletions
diff --git a/docs/tracing.txt b/docs/tracing.txt index c99a0f27cf..4b27ab0c2a 100644 --- a/docs/tracing.txt +++ b/docs/tracing.txt @@ -12,13 +12,14 @@ for debugging, profiling, and observing execution. ./configure --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: @@ -38,7 +39,7 @@ 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 *ptr; @@ -103,10 +104,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. +5. If specific trace events are going to be called a huge number of times, this + might have a noticeable performance impact even when the trace events are + programmatically disabled. In this case you should declare the trace event + with the "disable" property, which will effectively disable it at compile + time (using the "nop" backend). + +== Generic interface and monitor commands == + +You can programmatically query and control the dynamic state of trace events +through a backend-agnostic interface: + +* trace_print_events + +* trace_event_set_state + Enables or disables trace events at runtime inside QEMU. + The function returns "true" if the state of the event has been successfully + changed, or "false" otherwise: + + #include "trace/control.h" + + trace_event_set_state("virtio_irq", true); /* enable */ + [...] + trace_event_set_state("virtio_irq", false); /* disable */ + +Note that some of the backends do not provide an implementation for this +interface, in which case QEMU will just print a warning. + +This functionality is also provided 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. + +The "-trace events=<file>" command line argument can be used to enable the +events listed in <file> from the very beginning of the program. This file must +contain one event name per line. == Trace backends == @@ -131,6 +167,9 @@ 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 @@ -157,27 +196,9 @@ unless you have specific needs for more advanced backends. flushed and emptied. This means the 'info trace' will display few or no entries if the buffer has just been flushed. -* 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. - * trace-file on|off|flush|set <path> Enable/disable/flush the trace file or set the trace file name. -==== Enabling/disabling trace events programmatically ==== - -The st_change_trace_event_state() function can be used to enable or disable trace -events at runtime inside QEMU: - - #include "trace.h" - - st_change_trace_event_state("virtio_irq", true); /* enable */ - [...] - st_change_trace_event_state("virtio_irq", false); /* disable */ - ==== Analyzing trace files ==== The "simple" backend produces binary trace files that can be formatted with the |