tests/vm-trace/README.txt

   1 vm-trace is a tool utilizing the ftrace infrastructure in Linux kernel to
   2 measure VM preemption latencies.  For more info about ftrace, see
   3 Documentation/trace/ftrace.txt.  See include/linux/ring_buffer.h and
   4 include/linux/ftrace_event.h for data structures used by ftrace.
   5
   6 The tool enables 2 trace points in KVM driver:
   7 kvm_exit defined in vmx_vcpu_run() (see arch/x86/kvm/vmx.c), and
   8 kvm_entry defined in vcpu_enter_guest() (see arch/x86/kvm/x86.c).
   9
  10 It then spawns a thread to extract trace data from the kernel ftrace ring
  11 buffer using the splice() system call.  Once the tracing duration has elapsed,
  12 vm-trace calculates VM exit-entry latencies based on the timestamps of the
  13 events.  (A future improvement could be to spawn another thread to process the
  14 trace on the fly to improve vm-trace's performance.)
  15
  16 To take a trace, do the following:
  17
  18 1. Run qemu-kvm to start guest VM
  19 2. Bind each qemu-kvm vCPU thread to an isolated pCPU
  20 3. Start desired workload on the guest
  21 4. Run vm-trace on the host:
  22    vm-trace -p cpu_to_trace -c cpu_to_collect_trace -s duration_in_seconds
  23
  24 cpu_to_trace is one of the pCPUs from step 2 above that you want to trace.
  25 vm-trace does not support tracing multiple pCPUs.
  26
  27 cpu_to_collect_trace is the CPU used to read and save the trace data.
  28 If the host system is NUMA, make sure to assign a CPU in the same NUMA node
  29 as cpu_to_trace to cpu_to_collect_trace.
  30
  31 A binary file named trace.bin will be saved in the current working directory.
  32 Be aware that, depending on the tracing duration and type of workload running
  33 on the guest, the file can become quite large.
  34
  35 vm-trace requires root privileges.
  36
  37 Some statistics of the events will be displayed similar to the following:
  38
  39   Number of VM events = 21608832
  40   Average VM Exit-Entry latency = 1us
  41   Maximum VM Exit-Entry latency = 5us
  42   Maximum cumulative latency within 1ms = 12us
  43
  44 trace.bin will be overwritten each time vm-trace is run in this mode,
  45 so rename/copy the file if you want to keep it.
  46
  47 To process a previously collected trace file, run:
  48   vm-trace -f trace_file [-v]
  49
  50 If -v is specified, all events in the trace file will be displayed.
  51 This is helpful for identifying cause of long latency.