0001 perf-diff(1)
0002 ============
0003
0004 NAME
0005 ----
0006 perf-diff - Read perf.data files and display the differential profile
0007
0008 SYNOPSIS
0009 --------
0010 [verse]
0011 'perf diff' [baseline file] [data file1] [[data file2] ... ]
0012
0013 DESCRIPTION
0014 -----------
0015 This command displays the performance difference amongst two or more perf.data
0016 files captured via perf record.
0017
0018 If no parameters are passed it will assume perf.data.old and perf.data.
0019
0020 The differential profile is displayed only for events matching both
0021 specified perf.data files.
0022
0023 If no parameters are passed the samples will be sorted by dso and symbol.
0024 As the perf.data files could come from different binaries, the symbols addresses
0025 could vary. So perf diff is based on the comparison of the files and
0026 symbols name.
0027
0028 OPTIONS
0029 -------
0030 -D::
0031 --dump-raw-trace::
0032 Dump raw trace in ASCII.
0033
0034 --kallsyms=<file>::
0035 kallsyms pathname
0036
0037 -m::
0038 --modules::
0039 Load module symbols. WARNING: use only with -k and LIVE kernel
0040
0041 -d::
0042 --dsos=::
0043 Only consider symbols in these dsos. CSV that understands
0044 file://filename entries. This option will affect the percentage
0045 of the Baseline/Delta column. See --percentage for more info.
0046
0047 -C::
0048 --comms=::
0049 Only consider symbols in these comms. CSV that understands
0050 file://filename entries. This option will affect the percentage
0051 of the Baseline/Delta column. See --percentage for more info.
0052
0053 -S::
0054 --symbols=::
0055 Only consider these symbols. CSV that understands
0056 file://filename entries. This option will affect the percentage
0057 of the Baseline/Delta column. See --percentage for more info.
0058
0059 -s::
0060 --sort=::
0061 Sort by key(s): pid, comm, dso, symbol, cpu, parent, srcline.
0062 Please see description of --sort in the perf-report man page.
0063
0064 -t::
0065 --field-separator=::
0066
0067 Use a special separator character and don't pad with spaces, replacing
0068 all occurrences of this separator in symbol names (and other output)
0069 with a '.' character, that thus it's the only non valid separator.
0070
0071 -v::
0072 --verbose::
0073 Be verbose, for instance, show the raw counts in addition to the
0074 diff.
0075
0076 -q::
0077 --quiet::
0078 Do not show any message. (Suppress -v)
0079
0080 -f::
0081 --force::
0082 Don't do ownership validation.
0083
0084 --symfs=<directory>::
0085 Look for files with symbols relative to this directory.
0086
0087 -b::
0088 --baseline-only::
0089 Show only items with match in baseline.
0090
0091 -c::
0092 --compute::
0093 Differential computation selection - delta, ratio, wdiff, cycles,
0094 delta-abs (default is delta-abs). Default can be changed using
0095 diff.compute config option. See COMPARISON METHODS section for
0096 more info.
0097
0098 --cycles-hist::
0099 Report a histogram and the standard deviation for cycles data.
0100 It can help us to judge if the reported cycles data is noisy or
0101 not. This option should be used with '-c cycles'.
0102
0103 -p::
0104 --period::
0105 Show period values for both compared hist entries.
0106
0107 -F::
0108 --formula::
0109 Show formula for given computation.
0110
0111 -o::
0112 --order::
0113 Specify compute sorting column number. 0 means sorting by baseline
0114 overhead and 1 (default) means sorting by computed value of column 1
0115 (data from the first file other base baseline). Values more than 1
0116 can be used only if enough data files are provided.
0117 The default value can be set using the diff.order config option.
0118
0119 --percentage::
0120 Determine how to display the overhead percentage of filtered entries.
0121 Filters can be applied by --comms, --dsos and/or --symbols options.
0122
0123 "relative" means it's relative to filtered entries only so that the
0124 sum of shown entries will be always 100%. "absolute" means it retains
0125 the original value before and after the filter is applied.
0126
0127 --time::
0128 Analyze samples within given time window. It supports time
0129 percent with multiple time ranges. Time string is 'a%/n,b%/m,...'
0130 or 'a%-b%,c%-%d,...'.
0131
0132 For example:
0133
0134 Select the second 10% time slice to diff:
0135
0136 perf diff --time 10%/2
0137
0138 Select from 0% to 10% time slice to diff:
0139
0140 perf diff --time 0%-10%
0141
0142 Select the first and the second 10% time slices to diff:
0143
0144 perf diff --time 10%/1,10%/2
0145
0146 Select from 0% to 10% and 30% to 40% slices to diff:
0147
0148 perf diff --time 0%-10%,30%-40%
0149
0150 It also supports analyzing samples within a given time window
0151 <start>,<stop>. Times have the format seconds.nanoseconds. If 'start'
0152 is not given (i.e. time string is ',x.y') then analysis starts at
0153 the beginning of the file. If stop time is not given (i.e. time
0154 string is 'x.y,') then analysis goes to the end of the file.
0155 Multiple ranges can be separated by spaces, which requires the argument
0156 to be quoted e.g. --time "1234.567,1234.789 1235,"
0157 Time string is'a1.b1,c1.d1:a2.b2,c2.d2'. Use ':' to separate timestamps
0158 for different perf.data files.
0159
0160 For example, we get the timestamp information from 'perf script'.
0161
0162 perf script -i perf.data.old
0163 mgen 13940 [000] 3946.361400: ...
0164
0165 perf script -i perf.data
0166 mgen 13940 [000] 3971.150589 ...
0167
0168 perf diff --time 3946.361400,:3971.150589,
0169
0170 It analyzes the perf.data.old from the timestamp 3946.361400 to
0171 the end of perf.data.old and analyzes the perf.data from the
0172 timestamp 3971.150589 to the end of perf.data.
0173
0174 --cpu:: Only diff samples for the list of CPUs provided. Multiple CPUs can
0175 be provided as a comma-separated list with no space: 0,1. Ranges of
0176 CPUs are specified with -: 0-2. Default is to report samples on all
0177 CPUs.
0178
0179 --pid=::
0180 Only diff samples for given process ID (comma separated list).
0181
0182 --tid=::
0183 Only diff samples for given thread ID (comma separated list).
0184
0185 --stream::
0186 Enable hot streams comparison. Stream can be a callchain which is
0187 aggregated by the branch records from samples.
0188
0189 COMPARISON
0190 ----------
0191 The comparison is governed by the baseline file. The baseline perf.data
0192 file is iterated for samples. All other perf.data files specified on
0193 the command line are searched for the baseline sample pair. If the pair
0194 is found, specified computation is made and result is displayed.
0195
0196 All samples from non-baseline perf.data files, that do not match any
0197 baseline entry, are displayed with empty space within baseline column
0198 and possible computation results (delta) in their related column.
0199
0200 Example files samples:
0201 - file A with samples f1, f2, f3, f4, f6
0202 - file B with samples f2, f4, f5
0203 - file C with samples f1, f2, f5
0204
0205 Example output:
0206 x - computation takes place for pair
0207 b - baseline sample percentage
0208
0209 - perf diff A B C
0210
0211 baseline/A compute/B compute/C samples
0212 ---------------------------------------
0213 b x f1
0214 b x x f2
0215 b f3
0216 b x f4
0217 b f6
0218 x x f5
0219
0220 - perf diff B A C
0221
0222 baseline/B compute/A compute/C samples
0223 ---------------------------------------
0224 b x x f2
0225 b x f4
0226 b x f5
0227 x x f1
0228 x f3
0229 x f6
0230
0231 - perf diff C B A
0232
0233 baseline/C compute/B compute/A samples
0234 ---------------------------------------
0235 b x f1
0236 b x x f2
0237 b x f5
0238 x f3
0239 x x f4
0240 x f6
0241
0242 COMPARISON METHODS
0243 ------------------
0244 delta
0245 ~~~~~
0246 If specified the 'Delta' column is displayed with value 'd' computed as:
0247
0248 d = A->period_percent - B->period_percent
0249
0250 with:
0251 - A/B being matching hist entry from data/baseline file specified
0252 (or perf.data/perf.data.old) respectively.
0253
0254 - period_percent being the % of the hist entry period value within
0255 single data file
0256
0257 - with filtering by -C, -d and/or -S, period_percent might be changed
0258 relative to how entries are filtered. Use --percentage=absolute to
0259 prevent such fluctuation.
0260
0261 delta-abs
0262 ~~~~~~~~~
0263 Same as 'delta` method, but sort the result with the absolute values.
0264
0265 ratio
0266 ~~~~~
0267 If specified the 'Ratio' column is displayed with value 'r' computed as:
0268
0269 r = A->period / B->period
0270
0271 with:
0272 - A/B being matching hist entry from data/baseline file specified
0273 (or perf.data/perf.data.old) respectively.
0274
0275 - period being the hist entry period value
0276
0277 wdiff:WEIGHT-B,WEIGHT-A
0278 ~~~~~~~~~~~~~~~~~~~~~~~
0279 If specified the 'Weighted diff' column is displayed with value 'd' computed as:
0280
0281 d = B->period * WEIGHT-A - A->period * WEIGHT-B
0282
0283 - A/B being matching hist entry from data/baseline file specified
0284 (or perf.data/perf.data.old) respectively.
0285
0286 - period being the hist entry period value
0287
0288 - WEIGHT-A/WEIGHT-B being user supplied weights in the the '-c' option
0289 behind ':' separator like '-c wdiff:1,2'.
0290 - WEIGHT-A being the weight of the data file
0291 - WEIGHT-B being the weight of the baseline data file
0292
0293 cycles
0294 ~~~~~~
0295 If specified the '[Program Block Range] Cycles Diff' column is displayed.
0296 It displays the cycles difference of same program basic block amongst
0297 two perf.data. The program basic block is the code between two branches.
0298
0299 '[Program Block Range]' indicates the range of a program basic block.
0300 Source line is reported if it can be found otherwise uses symbol+offset
0301 instead.
0302
0303 SEE ALSO
0304 --------
0305 linkperf:perf-record[1], linkperf:perf-report[1]
