'\" t .\" Title: perf-kvm .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 2.0.16 .\" Date: 2022-01-03 .\" Manual: perf Manual .\" Source: perf .\" Language: English .\" .TH "PERF_5.16\-KVM" "1" "2022-01-03" "perf" "perf Manual" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 .nh .ad l .de URL \fI\\$2\fP <\\$1>\\$3 .. .als MTO URL .if \n[.g] \{\ . mso www.tmac . am URL . ad l . . . am MTO . ad l . . . LINKSTYLE blue R < > .\} .SH "NAME" perf-kvm \- Tool to trace/measure kvm guest os .SH "SYNOPSIS" .sp .nf \fIperf kvm\fP [\-\-host] [\-\-guest] [\-\-guestmount= [\-\-guestkallsyms= \-\-guestmodules= | \-\-guestvmlinux=]] {top|record|report|diff|buildid\-list} [] \fIperf kvm\fP [\-\-host] [\-\-guest] [\-\-guestkallsyms= \-\-guestmodules= | \-\-guestvmlinux=] {top|record|report|diff|buildid\-list|stat} [] \*(Aqperf kvm stat [record|report|live] [] .fi .br .SH "DESCRIPTION" .sp There are a couple of variants of perf kvm: .sp .if n .RS 4 .nf .fam C \*(Aqperf kvm [options] top \*(Aq to generates and displays a performance counter profile of guest os in realtime of an arbitrary workload. .fam .fi .if n .RE .sp .if n .RS 4 .nf .fam C \*(Aqperf kvm record \*(Aq 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(\*(Aq\*(Aq) \-> perf.data.guest \-\-host \-> perf.data.kvm \-\-guest \-> perf.data.guest \-\-host \-\-guest \-> perf.data.kvm \-\-host \-\-no\-guest \-> perf.data.host .fam .fi .if n .RE .sp .if n .RS 4 .nf .fam C \*(Aqperf kvm report\*(Aq to display the performance counter profile information recorded via perf kvm record. .fam .fi .if n .RE .sp .if n .RS 4 .nf .fam C \*(Aqperf kvm diff\*(Aq to displays the performance difference amongst two perf.data files captured via perf record. .fam .fi .if n .RE .sp .if n .RS 4 .nf .fam C \*(Aqperf kvm buildid\-list\*(Aq 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. .fam .fi .if n .RE .sp .if n .RS 4 .nf .fam C \*(Aqperf kvm stat \*(Aq to run a command and gather performance counter statistics. Especially, perf \*(Aqkvm stat record/report\*(Aq generates a statistical analysis of KVM events. Currently, vmexit, mmio (x86 only) and ioport (x86 only) events are supported. \*(Aqperf kvm stat record \*(Aq records kvm events and the events between start and end . And this command produces a file which contains tracing results of kvm events. .fam .fi .if n .RE .sp .if n .RS 4 .nf .fam C \*(Aqperf kvm stat report\*(Aq reports statistical data which includes events handled time, samples, and so on. .fam .fi .if n .RE .sp .if n .RS 4 .nf .fam C \*(Aqperf kvm stat live\*(Aq reports statistical data in a live mode (similar to record + report but with statistical data updated live at a given display rate). .fam .fi .if n .RE .SH "OPTIONS" .sp \-i, \-\-input= .RS 4 Input file name, for the \fIreport\fP, \fIdiff\fP and \fIbuildid\-list\fP subcommands. .RE .sp \-o, \-\-output= .RS 4 Output file name, for the \fIrecord\fP subcommand. Doesn\(cqt work with \fIreport\fP, just redirect the output to a file when using \fIreport\fP. .RE .sp \-\-host .RS 4 Collect host side performance profile. .RE .sp \-\-guest .RS 4 Collect guest side performance profile. .RE .sp \-\-guestmount= .RS 4 Guest os root file system mount directory. Users mounts guest os root directories under by a specific filesystem access method, typically, sshfs. For example, start 2 guest os. The one\(cqs pid is 8888 and the other\(cqs 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 .RE .sp \-\-guestkallsyms= .RS 4 Guest os /proc/kallsyms file copy. \fIperf\fP kvm\*(Aq reads it to get guest kernel symbols. Users copy it out from guest os. .RE .sp \-\-guestmodules= .RS 4 Guest os /proc/modules file copy. \fIperf\fP kvm\*(Aq reads it to get guest kernel module information. Users copy it out from guest os. .RE .sp \-\-guestvmlinux= .RS 4 Guest os kernel vmlinux. .RE .sp \-v, \-\-verbose .RS 4 Be more verbose (show counter open errors, etc). .RE .SH "STAT REPORT OPTIONS" .sp \-\-vcpu= .RS 4 analyze events which occur on this vcpu. (default: all vcpus) .RE .sp \-\-event= .RS 4 event to be analyzed. Possible values: vmexit, mmio (x86 only), ioport (x86 only). (default: vmexit) .RE .sp \-k, \-\-key= .RS 4 Sorting key. Possible values: sample (default, sort by samples number), time (sort by average time). .RE .sp \-p, \-\-pid= .RS 4 Analyze events only for given process ID(s) (comma separated list). .RE .SH "STAT LIVE OPTIONS" .sp \-d, \-\-display .RS 4 Time in seconds between display updates .RE .sp \-m, \-\-mmap\-pages= .RS 4 Number of mmap data pages (must be a power of two) or size specification with appended unit character \- B/K/M/G. The size is rounded up to have nearest pages power of two value. .RE .sp \-a, \-\-all\-cpus .RS 4 System\-wide collection from all CPUs. .RE .sp \-p, \-\-pid= .RS 4 Analyze events only for given process ID(s) (comma separated list). .RE .sp \-\-vcpu= .RS 4 analyze events which occur on this vcpu. (default: all vcpus) .RE .sp \-\-event= .RS 4 event to be analyzed. Possible values: vmexit, mmio (x86 only), ioport (x86 only). (default: vmexit) .RE .sp \-k, \-\-key= .RS 4 Sorting key. Possible values: sample (default, sort by samples number), time (sort by average time). .RE .sp \-\-duration= .RS 4 Show events other than HLT (x86 only) or Wait state (s390 only) that take longer than duration usecs. .RE .sp \-\-proc\-map\-timeout .RS 4 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. .RE .SH "SEE ALSO" .sp perf\-top(1), perf\-record(1), perf\-report(1), perf\-diff(1), perf\-buildid\-list(1), perf\-stat(1)