Commit | Line | Data |
---|---|---|
a1645ce1 | 1 | perf-kvm(1) |
cfadf9d4 | 2 | =========== |
a1645ce1 ZY |
3 | |
4 | NAME | |
5 | ---- | |
6 | perf-kvm - Tool to trace/measure kvm guest os | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
11 | 'perf kvm' [--host] [--guest] [--guestmount=<path> | |
12 | [--guestkallsyms=<path> --guestmodules=<path> | --guestvmlinux=<path>]] | |
13 | {top|record|report|diff|buildid-list} | |
14 | 'perf kvm' [--host] [--guest] [--guestkallsyms=<path> --guestmodules=<path> | |
bcf6edcd | 15 | | --guestvmlinux=<path>] {top|record|report|diff|buildid-list|stat} |
9a6d3166 | 16 | 'perf kvm stat [record|report|live] [<options>] |
a1645ce1 ZY |
17 | |
18 | DESCRIPTION | |
19 | ----------- | |
20 | There are a couple of variants of perf kvm: | |
21 | ||
22 | 'perf kvm [options] top <command>' to generates and displays | |
23 | a performance counter profile of guest os in realtime | |
24 | of an arbitrary workload. | |
25 | ||
5c0ef0ab | 26 | 'perf kvm record <command>' to record the performance counter profile |
a1645ce1 ZY |
27 | of an arbitrary workload and save it into a perf data file. If both |
28 | --host and --guest are input, the perf data file name is perf.data.kvm. | |
29 | If there is no --host but --guest, the file name is perf.data.guest. | |
30 | If there is no --guest but --host, the file name is perf.data.host. | |
31 | ||
32 | 'perf kvm report' to display the performance counter profile information | |
33 | recorded via perf kvm record. | |
34 | ||
35 | 'perf kvm diff' to displays the performance difference amongst two perf.data | |
36 | files captured via perf record. | |
37 | ||
38 | 'perf kvm buildid-list' to display the buildids found in a perf data file, | |
39 | so that other tools can be used to fetch packages with matching symbol tables | |
ed086d5b DY |
40 | for use by perf report. As buildid is read from /sys/kernel/notes in os, then |
41 | if you want to list the buildid for guest, please make sure your perf data file | |
42 | was captured with --guestmount in perf kvm record. | |
a1645ce1 | 43 | |
bcf6edcd XG |
44 | 'perf kvm stat <command>' to run a command and gather performance counter |
45 | statistics. | |
46 | Especially, perf 'kvm stat record/report' generates a statistical analysis | |
47 | of KVM events. Currently, vmexit, mmio and ioport events are supported. | |
48 | 'perf kvm stat record <command>' records kvm events and the events between | |
49 | start and end <command>. | |
50 | And this command produces a file which contains tracing results of kvm | |
51 | events. | |
52 | ||
53 | 'perf kvm stat report' reports statistical data which includes events | |
54 | handled time, samples, and so on. | |
55 | ||
9a6d3166 DA |
56 | 'perf kvm stat live' reports statistical data in a live mode (similar to |
57 | record + report but with statistical data updated live at a given display | |
58 | rate). | |
59 | ||
a1645ce1 ZY |
60 | OPTIONS |
61 | ------- | |
5c0ef0ab SB |
62 | -i:: |
63 | --input=:: | |
64 | Input file name. | |
65 | -o:: | |
66 | --output:: | |
67 | Output file name. | |
a1645ce1 | 68 | --host=:: |
cfadf9d4 | 69 | Collect host side performance profile. |
a1645ce1 | 70 | --guest=:: |
cfadf9d4 | 71 | Collect guest side performance profile. |
a1645ce1 ZY |
72 | --guestmount=<path>:: |
73 | Guest os root file system mount directory. Users mounts guest os | |
74 | root directories under <path> by a specific filesystem access method, | |
75 | typically, sshfs. For example, start 2 guest os. The one's pid is 8888 | |
76 | and the other's is 9999. | |
77 | #mkdir ~/guestmount; cd ~/guestmount | |
78 | #sshfs -o allow_other,direct_io -p 5551 localhost:/ 8888/ | |
79 | #sshfs -o allow_other,direct_io -p 5552 localhost:/ 9999/ | |
80 | #perf kvm --host --guest --guestmount=~/guestmount top | |
81 | --guestkallsyms=<path>:: | |
82 | Guest os /proc/kallsyms file copy. 'perf' kvm' reads it to get guest | |
83 | kernel symbols. Users copy it out from guest os. | |
84 | --guestmodules=<path>:: | |
85 | Guest os /proc/modules file copy. 'perf' kvm' reads it to get guest | |
86 | kernel module information. Users copy it out from guest os. | |
87 | --guestvmlinux=<path>:: | |
88 | Guest os kernel vmlinux. | |
89 | ||
bcf6edcd XG |
90 | STAT REPORT OPTIONS |
91 | ------------------- | |
92 | --vcpu=<value>:: | |
93 | analyze events which occures on this vcpu. (default: all vcpus) | |
94 | ||
9a6d3166 DA |
95 | --event=<value>:: |
96 | event to be analyzed. Possible values: vmexit, mmio, ioport. | |
bcf6edcd XG |
97 | (default: vmexit) |
98 | -k:: | |
99 | --key=<value>:: | |
100 | Sorting key. Possible values: sample (default, sort by samples | |
101 | number), time (sort by average time). | |
9a6d3166 DA |
102 | -p:: |
103 | --pid=:: | |
104 | Analyze events only for given process ID(s) (comma separated list). | |
105 | ||
106 | STAT LIVE OPTIONS | |
107 | ----------------- | |
108 | -d:: | |
109 | --display:: | |
110 | Time in seconds between display updates | |
111 | ||
112 | -m:: | |
113 | --mmap-pages=:: | |
27050f53 JO |
114 | Number of mmap data pages (must be a power of two) or size |
115 | specification with appended unit character - B/K/M/G. The | |
116 | size is rounded up to have nearest pages power of two value. | |
9a6d3166 DA |
117 | |
118 | -a:: | |
119 | --all-cpus:: | |
120 | System-wide collection from all CPUs. | |
121 | ||
122 | -p:: | |
123 | --pid=:: | |
124 | Analyze events only for given process ID(s) (comma separated list). | |
125 | ||
126 | --vcpu=<value>:: | |
127 | analyze events which occures on this vcpu. (default: all vcpus) | |
128 | ||
129 | ||
130 | --event=<value>:: | |
131 | event to be analyzed. Possible values: vmexit, mmio, ioport. | |
132 | (default: vmexit) | |
133 | ||
134 | -k:: | |
135 | --key=<value>:: | |
136 | Sorting key. Possible values: sample (default, sort by samples | |
137 | number), time (sort by average time). | |
138 | ||
139 | --duration=<value>:: | |
140 | Show events other than HLT that take longer than duration usecs. | |
bcf6edcd | 141 | |
a1645ce1 ZY |
142 | SEE ALSO |
143 | -------- | |
cfadf9d4 | 144 | linkperf:perf-top[1], linkperf:perf-record[1], linkperf:perf-report[1], |
bcf6edcd XG |
145 | linkperf:perf-diff[1], linkperf:perf-buildid-list[1], |
146 | linkperf:perf-stat[1] |