--- name: "perf-kvm" section: "1" platform: "linux" package: "perf" version: "7.3.1-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/perf-kvm" --- # perf-kvm(1) Tool to trace/measure kvm guest os ## NAME perf-kvm - Tool to trace/measure kvm guest os ## SYNOPSIS ``` perf kvm [--host] [--guest] [--guestmount= [--guestkallsyms= --guestmodules= | --guestvmlinux=]] {top|record|report|diff|buildid-list} [] perf kvm [--host] [--guest] [--guestkallsyms= --guestmodules= | --guestvmlinux=] {top|record|report|diff|buildid-list|stat} [] 'perf kvm stat [record|report|live] [] ``` ## DESCRIPTION There are a couple of variants of perf kvm: ``` 'perf kvm [options] top ' to generates and displays a performance counter profile of guest os in realtime of an arbitrary workload. ``` ``` 'perf kvm record ' to record the performance counter profile of an arbitrary workload and save it into a perf data file. We set the default behavior of perf kvm as --guest, so if neither --host nor --guest is input, the perf data file name is perf.data.guest. If --host is input, the perf data file name is perf.data.kvm. If you want to record data into perf.data.host, please input --host --no-guest. The behaviors are shown as following: Default('') -> perf.data.guest --host -> perf.data.kvm --guest -> perf.data.guest --host --guest -> perf.data.kvm --host --no-guest -> perf.data.host ``` ``` 'perf kvm report' to display the performance counter profile information recorded via perf kvm record. ``` ``` 'perf kvm diff' to displays the performance difference amongst two perf.data files captured via perf record. ``` ``` 'perf kvm buildid-list' to display the buildids found in a perf data file, so that other tools can be used to fetch packages with matching symbol tables for use by perf report. As buildid is read from /sys/kernel/notes in os, then if you want to list the buildid for guest, please make sure your perf data file was captured with --guestmount in perf kvm record. ``` ``` 'perf kvm stat ' to run a command and gather performance counter statistics. Especially, perf 'kvm stat record/report' generates a statistical analysis of KVM events. Currently, vmexit, mmio (x86 only) and ioport (x86 only) events are supported. 'perf kvm stat record ' records kvm events and the events between start and end . And this command produces a file which contains tracing results of kvm events. ``` ``` 'perf kvm stat report' reports statistical data which includes events handled sample, percent_sample, time, percent_time, max_t, min_t, mean_t. ``` ``` 'perf kvm stat live' reports statistical data in a live mode (similar to record + report but with statistical data updated live at a given display rate). ``` ## OPTIONS - \-i, --input=\ Input file name, for the *report*, *diff* and *buildid-list* subcommands. - \-o, --output=\ Output file name, for the *record* subcommand. Doesn’t work with *report*, just redirect the output to a file when using *report*. - \--host Collect host side performance profile. - \--guest Collect guest side performance profile. - \--guestmount=\ Guest OS root file system mount directory. Users mount guest OS root directories under \ by a specific filesystem access method, typically, sshfs. For example, start 2 guest OS, one’s pid is 8888 and the other’s is 9999: ``` $ mkdir ~/guestmount $ cd ~/guestmount $ sshfs -o allow_other,direct_io -p 5551 localhost:/ 8888/ $ sshfs -o allow_other,direct_io -p 5552 localhost:/ 9999/ $ perf kvm --host --guest --guestmount=~/guestmount top ``` - \--guestkallsyms=\ Guest OS /proc/kallsyms file copy. perf reads it to get guest kernel symbols. Users copy it out from guest OS. - \--guestmodules=\ Guest OS /proc/modules file copy. perf reads it to get guest kernel module information. Users copy it out from guest OS. - \--guestvmlinux=\ Guest OS kernel vmlinux. - \--guest-code Indicate that guest code can be found in the hypervisor process, which is a common case for KVM test programs. - \--stdio Use the stdio interface. - \-v, --verbose Be more verbose (show counter open errors, etc). ## STAT REPORT OPTIONS - \--vcpu=\ analyze events which occur on this vcpu. (default: all vcpus) - \--event=\ event to be analyzed. Possible values: vmexit, mmio (x86 only), ioport (x86 only). (default: vmexit) - \-k, --key=\ Sorting key. Possible values: sample (default, sort by samples number), percent\_sample (sort by sample percentage), time (sort by average time), precent\_time (sort by time percentage), max\_t (sort by maximum time), min\_t (sort by minimum time), mean\_t (sort by mean time). \-p, --pid= Analyze events only for given process ID(s) (comma separated list). ## STAT LIVE OPTIONS - \-d, --display Time in seconds between display updates \-m, --mmap-pages= Number of mmap data pages (must be a power of two) or size specification in bytes with appended unit character - B/K/M/G. The size is rounded up to the nearest power-of-two page value. - \-a, --all-cpus System-wide collection from all CPUs. \-p, --pid= Analyze events only for given process ID(s) (comma separated list). - \--vcpu=\ analyze events which occur on this vcpu. (default: all vcpus) - \--event=\ event to be analyzed. Possible values: vmexit, mmio (x86 only), ioport (x86 only). (default: vmexit) - \-k, --key=\ Sorting key. Possible values: sample (default, sort by samples number), time (sort by average time). - \--duration=\ Show events other than HLT (x86 only) or Wait state (s390 only) that take longer than duration usecs. - \--proc-map-timeout When processing pre-existing threads /proc/XXX/mmap, it may take a long time, because the file may be huge. A time out is needed in such cases. This option sets the time out limit. The default value is 500 ms. ## SEE ALSO [**perf-top**(1)](/perf-top/1.md), [**perf-record**(1)](/perf-record/1.md), [**perf-report**(1)](/perf-report/1.md), [**perf-diff**(1)](/perf-diff/1.md), [**perf-buildid-list**(1)](/perf-buildid-list/1.md), [**perf-stat**(1)](/perf-stat/1.md)