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 | |
96d54169 | 61 | handled sample, percent_sample, time, percent_time, max_t, min_t, mean_t. |
bcf6edcd | 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>:: |
99744068 | 71 | Input file name, for the 'report', 'diff' and 'buildid-list' subcommands. |
5c0ef0ab | 72 | -o:: |
316bd98a | 73 | --output=<path>:: |
99744068 ACM |
74 | Output file name, for the 'record' subcommand. Doesn't work with 'report', |
75 | just redirect the output to a file when using 'report'. | |
316bd98a | 76 | --host:: |
cfadf9d4 | 77 | Collect host side performance profile. |
316bd98a | 78 | --guest:: |
cfadf9d4 | 79 | Collect guest side performance profile. |
53e76d35 AH |
80 | |
81 | :GMEXAMPLECMD: kvm --host --guest | |
82 | :GMEXAMPLESUBCMD: top | |
83 | include::guest-files.txt[] | |
84 | ||
96d54169 LY |
85 | --stdio:: Use the stdio interface. |
86 | ||
100b9073 DY |
87 | -v:: |
88 | --verbose:: | |
89 | Be more verbose (show counter open errors, etc). | |
a1645ce1 | 90 | |
bcf6edcd XG |
91 | STAT REPORT OPTIONS |
92 | ------------------- | |
93 | --vcpu=<value>:: | |
96355f2c | 94 | analyze events which occur on this vcpu. (default: all vcpus) |
bcf6edcd | 95 | |
9a6d3166 | 96 | --event=<value>:: |
3be8e2a0 AY |
97 | event to be analyzed. Possible values: vmexit, mmio (x86 only), |
98 | ioport (x86 only). (default: vmexit) | |
bcf6edcd XG |
99 | -k:: |
100 | --key=<value>:: | |
101 | Sorting key. Possible values: sample (default, sort by samples | |
96d54169 LY |
102 | number), percent_sample (sort by sample percentage), time |
103 | (sort by average time), precent_time (sort by time percentage), | |
104 | max_t (sort by maximum time), min_t (sort by minimum time), mean_t | |
105 | (sort by mean time). | |
9a6d3166 DA |
106 | -p:: |
107 | --pid=:: | |
108 | Analyze events only for given process ID(s) (comma separated list). | |
109 | ||
110 | STAT LIVE OPTIONS | |
111 | ----------------- | |
112 | -d:: | |
113 | --display:: | |
114 | Time in seconds between display updates | |
115 | ||
116 | -m:: | |
117 | --mmap-pages=:: | |
27050f53 JO |
118 | Number of mmap data pages (must be a power of two) or size |
119 | specification with appended unit character - B/K/M/G. The | |
120 | size is rounded up to have nearest pages power of two value. | |
9a6d3166 DA |
121 | |
122 | -a:: | |
123 | --all-cpus:: | |
124 | System-wide collection from all CPUs. | |
125 | ||
126 | -p:: | |
127 | --pid=:: | |
128 | Analyze events only for given process ID(s) (comma separated list). | |
129 | ||
130 | --vcpu=<value>:: | |
96355f2c | 131 | analyze events which occur on this vcpu. (default: all vcpus) |
9a6d3166 DA |
132 | |
133 | ||
134 | --event=<value>:: | |
3be8e2a0 AY |
135 | event to be analyzed. Possible values: vmexit, |
136 | mmio (x86 only), ioport (x86 only). | |
9a6d3166 DA |
137 | (default: vmexit) |
138 | ||
139 | -k:: | |
140 | --key=<value>:: | |
141 | Sorting key. Possible values: sample (default, sort by samples | |
142 | number), time (sort by average time). | |
143 | ||
144 | --duration=<value>:: | |
3be8e2a0 AY |
145 | Show events other than HLT (x86 only) or Wait state (s390 only) |
146 | that take longer than duration usecs. | |
bcf6edcd | 147 | |
9d9cad76 KL |
148 | --proc-map-timeout:: |
149 | When processing pre-existing threads /proc/XXX/mmap, it may take | |
150 | a long time, because the file may be huge. A time out is needed | |
151 | in such cases. | |
152 | This option sets the time out limit. The default value is 500 ms. | |
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] |