0001 perf-kvm(1)
0002 ===========
0003
0004 NAME
0005 ----
0006 perf-kvm - Tool to trace/measure kvm guest os
0007
0008 SYNOPSIS
0009 --------
0010 [verse]
0011 'perf kvm' [--host] [--guest] [--guestmount=<path>
0012 [--guestkallsyms=<path> --guestmodules=<path> | --guestvmlinux=<path>]]
0013 {top|record|report|diff|buildid-list} [<options>]
0014 'perf kvm' [--host] [--guest] [--guestkallsyms=<path> --guestmodules=<path>
0015 | --guestvmlinux=<path>] {top|record|report|diff|buildid-list|stat} [<options>]
0016 'perf kvm stat [record|report|live] [<options>]
0017
0018 DESCRIPTION
0019 -----------
0020 There are a couple of variants of perf kvm:
0021
0022 'perf kvm [options] top <command>' to generates and displays
0023 a performance counter profile of guest os in realtime
0024 of an arbitrary workload.
0025
0026 'perf kvm record <command>' to record the performance counter profile
0027 of an arbitrary workload and save it into a perf data file. We set the
0028 default behavior of perf kvm as --guest, so if neither --host nor --guest
0029 is input, the perf data file name is perf.data.guest. If --host is input,
0030 the perf data file name is perf.data.kvm. If you want to record data into
0031 perf.data.host, please input --host --no-guest. The behaviors are shown as
0032 following:
0033 Default('') -> perf.data.guest
0034 --host -> perf.data.kvm
0035 --guest -> perf.data.guest
0036 --host --guest -> perf.data.kvm
0037 --host --no-guest -> perf.data.host
0038
0039 'perf kvm report' to display the performance counter profile information
0040 recorded via perf kvm record.
0041
0042 'perf kvm diff' to displays the performance difference amongst two perf.data
0043 files captured via perf record.
0044
0045 'perf kvm buildid-list' to display the buildids found in a perf data file,
0046 so that other tools can be used to fetch packages with matching symbol tables
0047 for use by perf report. As buildid is read from /sys/kernel/notes in os, then
0048 if you want to list the buildid for guest, please make sure your perf data file
0049 was captured with --guestmount in perf kvm record.
0050
0051 'perf kvm stat <command>' to run a command and gather performance counter
0052 statistics.
0053 Especially, perf 'kvm stat record/report' generates a statistical analysis
0054 of KVM events. Currently, vmexit, mmio (x86 only) and ioport (x86 only)
0055 events are supported. 'perf kvm stat record <command>' records kvm events
0056 and the events between start and end <command>.
0057 And this command produces a file which contains tracing results of kvm
0058 events.
0059
0060 'perf kvm stat report' reports statistical data which includes events
0061 handled time, samples, and so on.
0062
0063 'perf kvm stat live' reports statistical data in a live mode (similar to
0064 record + report but with statistical data updated live at a given display
0065 rate).
0066
0067 OPTIONS
0068 -------
0069 -i::
0070 --input=<path>::
0071 Input file name, for the 'report', 'diff' and 'buildid-list' subcommands.
0072 -o::
0073 --output=<path>::
0074 Output file name, for the 'record' subcommand. Doesn't work with 'report',
0075 just redirect the output to a file when using 'report'.
0076 --host::
0077 Collect host side performance profile.
0078 --guest::
0079 Collect guest side performance profile.
0080
0081 :GMEXAMPLECMD: kvm --host --guest
0082 :GMEXAMPLESUBCMD: top
0083 include::guest-files.txt[]
0084
0085 -v::
0086 --verbose::
0087 Be more verbose (show counter open errors, etc).
0088
0089 STAT REPORT OPTIONS
0090 -------------------
0091 --vcpu=<value>::
0092 analyze events which occur on this vcpu. (default: all vcpus)
0093
0094 --event=<value>::
0095 event to be analyzed. Possible values: vmexit, mmio (x86 only),
0096 ioport (x86 only). (default: vmexit)
0097 -k::
0098 --key=<value>::
0099 Sorting key. Possible values: sample (default, sort by samples
0100 number), time (sort by average time).
0101 -p::
0102 --pid=::
0103 Analyze events only for given process ID(s) (comma separated list).
0104
0105 STAT LIVE OPTIONS
0106 -----------------
0107 -d::
0108 --display::
0109 Time in seconds between display updates
0110
0111 -m::
0112 --mmap-pages=::
0113 Number of mmap data pages (must be a power of two) or size
0114 specification with appended unit character - B/K/M/G. The
0115 size is rounded up to have nearest pages power of two value.
0116
0117 -a::
0118 --all-cpus::
0119 System-wide collection from all CPUs.
0120
0121 -p::
0122 --pid=::
0123 Analyze events only for given process ID(s) (comma separated list).
0124
0125 --vcpu=<value>::
0126 analyze events which occur on this vcpu. (default: all vcpus)
0127
0128
0129 --event=<value>::
0130 event to be analyzed. Possible values: vmexit,
0131 mmio (x86 only), ioport (x86 only).
0132 (default: vmexit)
0133
0134 -k::
0135 --key=<value>::
0136 Sorting key. Possible values: sample (default, sort by samples
0137 number), time (sort by average time).
0138
0139 --duration=<value>::
0140 Show events other than HLT (x86 only) or Wait state (s390 only)
0141 that take longer than duration usecs.
0142
0143 --proc-map-timeout::
0144 When processing pre-existing threads /proc/XXX/mmap, it may take
0145 a long time, because the file may be huge. A time out is needed
0146 in such cases.
0147 This option sets the time out limit. The default value is 500 ms.
0148
0149 SEE ALSO
0150 --------
0151 linkperf:perf-top[1], linkperf:perf-record[1], linkperf:perf-report[1],
0152 linkperf:perf-diff[1], linkperf:perf-buildid-list[1],
0153 linkperf:perf-stat[1]
