1PERF-DIFF(1)                      perf Manual                     PERF-DIFF(1)
2
3
4

NAME

6       perf-diff - Read perf.data files and display the differential profile
7

SYNOPSIS

9       perf diff [baseline file] [data file1] [[data file2] ... ]
10

DESCRIPTION

12       This command displays the performance difference amongst two or more
13       perf.data files captured via perf record.
14
15       If no parameters are passed it will assume perf.data.old and perf.data.
16
17       The differential profile is displayed only for events matching both
18       specified perf.data files.
19
20       If no parameters are passed the samples will be sorted by dso and
21       symbol. As the perf.data files could come from different binaries, the
22       symbols addresses could vary. So perf diff is based on the comparison
23       of the files and symbols name.
24

OPTIONS

26       -D, --dump-raw-trace
27           Dump raw trace in ASCII.
28
29       --kallsyms=<file>
30           kallsyms pathname
31
32       -m, --modules
33           Load module symbols. WARNING: use only with -k and LIVE kernel
34
35       -d, --dsos=
36           Only consider symbols in these dsos. CSV that understands
37           file://filename entries. This option will affect the percentage of
38           the Baseline/Delta column. See --percentage for more info.
39
40       -C, --comms=
41           Only consider symbols in these comms. CSV that understands
42           file://filename entries. This option will affect the percentage of
43           the Baseline/Delta column. See --percentage for more info.
44
45       -S, --symbols=
46           Only consider these symbols. CSV that understands file://filename
47           entries. This option will affect the percentage of the
48           Baseline/Delta column. See --percentage for more info.
49
50       -s, --sort=
51           Sort by key(s): pid, comm, dso, symbol, cpu, parent, srcline.
52           Please see description of --sort in the perf-report man page.
53
54       -t, --field-separator=
55           Use a special separator character and don’t pad with spaces,
56           replacing all occurrences of this separator in symbol names (and
57           other output) with a .  character, that thus it’s the only non
58           valid separator.
59
60       -v, --verbose
61           Be verbose, for instance, show the raw counts in addition to the
62           diff.
63
64       -q, --quiet
65           Do not show any warnings or messages. (Suppress -v)
66
67       -f, --force
68           Don’t do ownership validation.
69
70       --symfs=<directory>
71           Look for files with symbols relative to this directory.
72
73       -b, --baseline-only
74           Show only items with match in baseline.
75
76       -c, --compute
77           Differential computation selection - delta, ratio, wdiff, cycles,
78           delta-abs (default is delta-abs). Default can be changed using
79           diff.compute config option. See COMPARISON METHODS section for more
80           info.
81
82       --cycles-hist
83           Report a histogram and the standard deviation for cycles data. It
84           can help us to judge if the reported cycles data is noisy or not.
85           This option should be used with -c cycles.
86
87       -p, --period
88           Show period values for both compared hist entries.
89
90       -F, --formula
91           Show formula for given computation.
92
93       -o, --order
94           Specify compute sorting column number. 0 means sorting by baseline
95           overhead and 1 (default) means sorting by computed value of column
96           1 (data from the first file other base baseline). Values more than
97           1 can be used only if enough data files are provided. The default
98           value can be set using the diff.order config option.
99
100       --percentage
101           Determine how to display the overhead percentage of filtered
102           entries. Filters can be applied by --comms, --dsos and/or --symbols
103           options.
104
105               "relative" means it's relative to filtered entries only so that the
106               sum of shown entries will be always 100%.  "absolute" means it retains
107               the original value before and after the filter is applied.
108
109       --time
110           Analyze samples within given time window. It supports time percent
111           with multiple time ranges. Time string is a%/n,b%/m,...  or
112           a%-b%,c%-%d,....
113
114               For example:
115
116               Select the second 10% time slice to diff:
117
118               perf diff --time 10%/2
119
120               Select from 0% to 10% time slice to diff:
121
122               perf diff --time 0%-10%
123
124               Select the first and the second 10% time slices to diff:
125
126               perf diff --time 10%/1,10%/2
127
128               Select from 0% to 10% and 30% to 40% slices to diff:
129
130               perf diff --time 0%-10%,30%-40%
131
132               It also supports analyzing samples within a given time window
133               <start>,<stop>. Times have the format seconds.nanoseconds. If 'start'
134               is not given (i.e. time string is ',x.y') then analysis starts at
135               the beginning of the file. If stop time is not given (i.e. time
136               string is 'x.y,') then analysis goes to the end of the file.
137               Multiple ranges can be separated by spaces, which requires the argument
138               to be quoted e.g. --time "1234.567,1234.789 1235,"
139               Time string is'a1.b1,c1.d1:a2.b2,c2.d2'. Use ':' to separate timestamps
140               for different perf.data files.
141
142               For example, we get the timestamp information from 'perf script'.
143
144               perf script -i perf.data.old
145                 mgen 13940 [000]  3946.361400: ...
146
147               perf script -i perf.data
148                 mgen 13940 [000]  3971.150589 ...
149
150               perf diff --time 3946.361400,:3971.150589,
151
152               It analyzes the perf.data.old from the timestamp 3946.361400 to
153               the end of perf.data.old and analyzes the perf.data from the
154               timestamp 3971.150589 to the end of perf.data.
155
156       --cpu
157           Only diff samples for the list of CPUs provided. Multiple CPUs can
158           be provided as a comma-separated list with no space: 0,1. Ranges of
159           CPUs are specified with -: 0-2. Default is to report samples on all
160           CPUs.
161
162       --pid=
163           Only diff samples for given process ID (comma separated list).
164
165       --tid=
166           Only diff samples for given thread ID (comma separated list).
167
168       --stream
169           Enable hot streams comparison. Stream can be a callchain which is
170           aggregated by the branch records from samples.
171

COMPARISON

173       The comparison is governed by the baseline file. The baseline perf.data
174       file is iterated for samples. All other perf.data files specified on
175       the command line are searched for the baseline sample pair. If the pair
176       is found, specified computation is made and result is displayed.
177
178       All samples from non-baseline perf.data files, that do not match any
179       baseline entry, are displayed with empty space within baseline column
180       and possible computation results (delta) in their related column.
181
182       Example files samples: - file A with samples f1, f2, f3, f4, f6 - file
183       B with samples f2, f4, f5 - file C with samples f1, f2, f5
184
185       Example output: x - computation takes place for pair b - baseline
186       sample percentage
187
188       •   perf diff A B C
189
190               baseline/A compute/B compute/C  samples
191               ---------------------------------------
192               b                    x          f1
193               b          x         x          f2
194               b                               f3
195               b          x                    f4
196               b                               f6
197                          x         x          f5
198
199       •   perf diff B A C
200
201               baseline/B compute/A compute/C  samples
202               ---------------------------------------
203               b          x         x          f2
204               b          x                    f4
205               b                    x          f5
206                          x         x          f1
207                          x                    f3
208                          x                    f6
209
210       •   perf diff C B A
211
212               baseline/C compute/B compute/A  samples
213               ---------------------------------------
214               b                    x          f1
215               b          x         x          f2
216               b          x                    f5
217                                    x          f3
218                          x         x          f4
219                                    x          f6
220

COMPARISON METHODS

222   delta
223       If specified the Delta column is displayed with value d computed as:
224
225           d = A->period_percent - B->period_percent
226
227       with: - A/B being matching hist entry from data/baseline file specified
228       (or perf.data/perf.data.old) respectively.
229
230       •   period_percent being the % of the hist entry period value within
231           single data file
232
233       •   with filtering by -C, -d and/or -S, period_percent might be changed
234           relative to how entries are filtered. Use --percentage=absolute to
235           prevent such fluctuation.
236
237   delta-abs
238       Same as 'delta` method, but sort the result with the absolute values.
239
240   ratio
241       If specified the Ratio column is displayed with value r computed as:
242
243           r = A->period / B->period
244
245       with: - A/B being matching hist entry from data/baseline file specified
246       (or perf.data/perf.data.old) respectively.
247
248       •   period being the hist entry period value
249
250   wdiff:WEIGHT-B,WEIGHT-A
251       If specified the Weighted diff column is displayed with value d
252       computed as:
253
254           d = B->period * WEIGHT-A - A->period * WEIGHT-B
255
256       •   A/B being matching hist entry from data/baseline file specified (or
257           perf.data/perf.data.old) respectively.
258
259       •   period being the hist entry period value
260
261       •   WEIGHT-A/WEIGHT-B being user supplied weights in the the -c option
262           behind : separator like -c wdiff:1,2.
263
264       •   WEIGHT-A being the weight of the data file
265
266       •   WEIGHT-B being the weight of the baseline data file
267
268   cycles
269       If specified the [Program Block Range] Cycles Diff column is displayed.
270       It displays the cycles difference of same program basic block amongst
271       two perf.data. The program basic block is the code between two
272       branches.
273
274       [Program Block Range] indicates the range of a program basic block.
275       Source line is reported if it can be found otherwise uses symbol+offset
276       instead.
277

SEE ALSO

279       perf-record(1), perf-report(1)
280
281
282
283perf                              11/28/2023                      PERF-DIFF(1)
Impressum