PERF-KVM(1)

📦
version 7.3.1 · 41 versions
, in arch rolling

💅 PERF-KVM(1) — the perf manual, kvm edition 💅

okay bestie, sit down, grab a boba, because we're diving into perf-kvm, aka the tool to trace/measure kvm guest os. yes that's the whole NAME section, she's short but she's iconic ✨

🌸 SYNOPSIS 🌸

like, here's the vibe of how you actually call her:

perf kvm [--host] [--guest] [--guestmount=<path>
        [--guestkallsyms=<path> --guestmodules=<path> | --guestvmlinux=<path>]]
        {top|record|report|diff|buildid-list} [<options>]
perf kvm [--host] [--guest] [--guestkallsyms=<path> --guestmodules=<path>
        | --guestvmlinux=<path>] {top|record|report|diff|buildid-list|stat} [<options>]
'perf kvm stat [record|report|live] [<options>]

periodt, those are the three shapes she comes in 🫶

💖 DESCRIPTION 💖

so there are, like, a couple of variants of perf kvm, and each one is doing her own main character thing:

  • 'perf kvm [options] top <command>' — generates and displays a performance counter profile of guest os in realtime, of an arbitrary workload. live numbers, live vibes 🔥
  • 'perf kvm record <command>' — records the performance counter profile of an arbitrary workload and saves it into a perf data file. and here's the tea: 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. and if you want to record data into perf.data.host, please input --host --no-guest. the behaviors are shown as following, no cap:
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. it's giving "read back what you wrote" 💅
  • 'perf kvm diff' — to displays the performance difference amongst two perf.data files captured via perf record. comparison era 🦋
  • '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. literally so useful. BUT — 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. don't skip this step bestie 🙈
  • 'perf kvm stat <command>' — 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 <command>' records kvm events and the events between start and end <command>. 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). live updating stats?? we love to see it ✨

🎀 OPTIONS 🎀

  • -i, --input=<path> — Input file name, for the report, diff and buildid-list subcommands.
  • -o, --output=<path> — Output file name, for the record subcommand. Doesn’t work with report, just redirect the output to a file when using report. (yes that's the workaround, she said what she said 💅)
  • --host — Collect host side performance profile.
  • --guest — Collect guest side performance profile.
  • --guestmount=<path> — Guest OS root file system mount directory. Users mount guest OS root directories under <path> 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=<path> — Guest OS /proc/kallsyms file copy. perf reads it to get guest kernel symbols. Users copy it out from guest OS.
  • --guestmodules=<path> — Guest OS /proc/modules file copy. perf reads it to get guest kernel module information. Users copy it out from guest OS.
  • --guestvmlinux=<path> — 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=<value> — analyze events which occur on this vcpu. (default: all vcpus)
  • --event=<value> — event to be analyzed. Possible values: vmexit, mmio (x86 only), ioport (x86 only). (default: vmexit)
  • -k, --key=<value> — 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). (and yes, precent_time is spelled exactly like that in the original — keep it, she's quirky like that 😭)
  • -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=<value> — analyze events which occur on this vcpu. (default: all vcpus)
  • --event=<value> — event to be analyzed. Possible values: vmexit, mmio (x86 only), ioport (x86 only). (default: vmexit)
  • -k, --key=<value> — Sorting key. Possible values: sample (default, sort by samples number), time (sort by average time). (heads up — live mode's key list is shorter than report mode's, that's not a typo, that's just how she is 🧚)
  • --duration=<value> — 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. literally the "bestie please don't hang forever" option 🫶

⭐ SEE ALSO ⭐

perf-top(1), perf-record(1), perf-report(1), perf-diff(1), perf-buildid-list(1), perf-stat(1)

go read those next, iykyk 💜

and that's the whole page, bestie — mwah 💋 this iconic little number comes from perf, dated 10/31/2026, and it's filed under PERF-KVM(1). go forth and trace your guests 👑✨

📦 where this page comes from