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