'\" t
.\" Title: perf-diff
.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 2022-10-27
.\" Manual: perf Manual
.\" Source: perf
.\" Language: English
.\"
.TH "PERF\-DIFF" "1" "2022\-10\-27" "perf" "perf Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
perf-diff \- Read perf\&.data files and display the differential profile
.SH "SYNOPSIS"
.sp
.nf
\fIperf diff\fR [baseline file] [data file1] [[data file2] \&... ]
.fi
.SH "DESCRIPTION"
.sp
This command displays the performance difference amongst two or more perf\&.data files captured via perf record\&.
.sp
If no parameters are passed it will assume perf\&.data\&.old and perf\&.data\&.
.sp
The differential profile is displayed only for events matching both specified perf\&.data files\&.
.sp
If no parameters are passed the samples will be sorted by dso and symbol\&. As the perf\&.data files could come from different binaries, the symbols addresses could vary\&. So perf diff is based on the comparison of the files and symbols name\&.
.SH "OPTIONS"
.PP
\-D, \-\-dump\-raw\-trace
.RS 4
Dump raw trace in ASCII\&.
.RE
.PP
\-\-kallsyms=
.RS 4
kallsyms pathname
.RE
.PP
\-m, \-\-modules
.RS 4
Load module symbols\&. WARNING: use only with \-k and LIVE kernel
.RE
.PP
\-d, \-\-dsos=
.RS 4
Only consider symbols in these dsos\&. CSV that understands
\m[blue]\fBfile://filename\fR\m[]
entries\&. This option will affect the percentage of the Baseline/Delta column\&. See \-\-percentage for more info\&.
.RE
.PP
\-C, \-\-comms=
.RS 4
Only consider symbols in these comms\&. CSV that understands
\m[blue]\fBfile://filename\fR\m[]
entries\&. This option will affect the percentage of the Baseline/Delta column\&. See \-\-percentage for more info\&.
.RE
.PP
\-S, \-\-symbols=
.RS 4
Only consider these symbols\&. CSV that understands
\m[blue]\fBfile://filename\fR\m[]
entries\&. This option will affect the percentage of the Baseline/Delta column\&. See \-\-percentage for more info\&.
.RE
.PP
\-s, \-\-sort=
.RS 4
Sort by key(s): pid, comm, dso, symbol, cpu, parent, srcline\&. Please see description of \-\-sort in the perf\-report man page\&.
.RE
.PP
\-t, \-\-field\-separator=
.RS 4
Use a special separator character and don\(cqt pad with spaces, replacing all occurrences of this separator in symbol names (and other output) with a
\fI\&.\fR
character, that thus it\(cqs the only non valid separator\&.
.RE
.PP
\-v, \-\-verbose
.RS 4
Be verbose, for instance, show the raw counts in addition to the diff\&.
.RE
.PP
\-q, \-\-quiet
.RS 4
Do not show any warnings or messages\&. (Suppress \-v)
.RE
.PP
\-f, \-\-force
.RS 4
Don\(cqt do ownership validation\&.
.RE
.PP
\-\-symfs=
.RS 4
Look for files with symbols relative to this directory\&.
.RE
.PP
\-b, \-\-baseline\-only
.RS 4
Show only items with match in baseline\&.
.RE
.PP
\-c, \-\-compute
.RS 4
Differential computation selection \- delta, ratio, wdiff, cycles, delta\-abs (default is delta\-abs)\&. Default can be changed using diff\&.compute config option\&. See COMPARISON METHODS section for more info\&.
.RE
.PP
\-\-cycles\-hist
.RS 4
Report a histogram and the standard deviation for cycles data\&. It can help us to judge if the reported cycles data is noisy or not\&. This option should be used with
\fI\-c cycles\fR\&.
.RE
.PP
\-p, \-\-period
.RS 4
Show period values for both compared hist entries\&.
.RE
.PP
\-F, \-\-formula
.RS 4
Show formula for given computation\&.
.RE
.PP
\-o, \-\-order
.RS 4
Specify compute sorting column number\&. 0 means sorting by baseline overhead and 1 (default) means sorting by computed value of column 1 (data from the first file other base baseline)\&. Values more than 1 can be used only if enough data files are provided\&. The default value can be set using the diff\&.order config option\&.
.RE
.PP
\-\-percentage
.RS 4
Determine how to display the overhead percentage of filtered entries\&. Filters can be applied by \-\-comms, \-\-dsos and/or \-\-symbols options\&.
.sp
.if n \{\
.RS 4
.\}
.nf
"relative" means it\*(Aqs relative to filtered entries only so that the
sum of shown entries will be always 100%\&. "absolute" means it retains
the original value before and after the filter is applied\&.
.fi
.if n \{\
.RE
.\}
.RE
.PP
\-\-time
.RS 4
Analyze samples within given time window\&. It supports time percent with multiple time ranges\&. Time string is
\fIa%/n,b%/m,\&...\fR
or
\fIa%\-b%,c%\-%d,\&...\fR\&.
.sp
.if n \{\
.RS 4
.\}
.nf
For example:
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
Select the second 10% time slice to diff:
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
perf diff \-\-time 10%/2
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
Select from 0% to 10% time slice to diff:
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
perf diff \-\-time 0%\-10%
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
Select the first and the second 10% time slices to diff:
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
perf diff \-\-time 10%/1,10%/2
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
Select from 0% to 10% and 30% to 40% slices to diff:
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
perf diff \-\-time 0%\-10%,30%\-40%
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
It also supports analyzing samples within a given time window
,\&. Times have the format seconds\&.nanoseconds\&. If \*(Aqstart\*(Aq
is not given (i\&.e\&. time string is \*(Aq,x\&.y\*(Aq) then analysis starts at
the beginning of the file\&. If stop time is not given (i\&.e\&. time
string is \*(Aqx\&.y,\*(Aq) then analysis goes to the end of the file\&.
Multiple ranges can be separated by spaces, which requires the argument
to be quoted e\&.g\&. \-\-time "1234\&.567,1234\&.789 1235,"
Time string is\*(Aqa1\&.b1,c1\&.d1:a2\&.b2,c2\&.d2\*(Aq\&. Use \*(Aq:\*(Aq to separate timestamps
for different perf\&.data files\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
For example, we get the timestamp information from \*(Aqperf script\*(Aq\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
perf script \-i perf\&.data\&.old
mgen 13940 [000] 3946\&.361400: \&.\&.\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
perf script \-i perf\&.data
mgen 13940 [000] 3971\&.150589 \&.\&.\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
perf diff \-\-time 3946\&.361400,:3971\&.150589,
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
It analyzes the perf\&.data\&.old from the timestamp 3946\&.361400 to
the end of perf\&.data\&.old and analyzes the perf\&.data from the
timestamp 3971\&.150589 to the end of perf\&.data\&.
.fi
.if n \{\
.RE
.\}
.RE
.PP
\-\-cpu
.RS 4
Only diff samples for the list of CPUs provided\&. Multiple CPUs can be provided as a comma\-separated list with no space: 0,1\&. Ranges of CPUs are specified with \-: 0\-2\&. Default is to report samples on all CPUs\&.
.RE
.PP
\-\-pid=
.RS 4
Only diff samples for given process ID (comma separated list)\&.
.RE
.PP
\-\-tid=
.RS 4
Only diff samples for given thread ID (comma separated list)\&.
.RE
.PP
\-\-stream
.RS 4
Enable hot streams comparison\&. Stream can be a callchain which is aggregated by the branch records from samples\&.
.RE
.SH "COMPARISON"
.sp
The comparison is governed by the baseline file\&. The baseline perf\&.data file is iterated for samples\&. All other perf\&.data files specified on the command line are searched for the baseline sample pair\&. If the pair is found, specified computation is made and result is displayed\&.
.sp
All samples from non\-baseline perf\&.data files, that do not match any baseline entry, are displayed with empty space within baseline column and possible computation results (delta) in their related column\&.
.sp
Example files samples: \- file A with samples f1, f2, f3, f4, f6 \- file B with samples f2, f4, f5 \- file C with samples f1, f2, f5
.sp
Example output: x \- computation takes place for pair b \- baseline sample percentage
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
perf diff A B C
.sp
.if n \{\
.RS 4
.\}
.nf
baseline/A compute/B compute/C samples
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
b x f1
b x x f2
b f3
b x f4
b f6
x x f5
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
perf diff B A C
.sp
.if n \{\
.RS 4
.\}
.nf
baseline/B compute/A compute/C samples
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
b x x f2
b x f4
b x f5
x x f1
x f3
x f6
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
perf diff C B A
.sp
.if n \{\
.RS 4
.\}
.nf
baseline/C compute/B compute/A samples
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
b x f1
b x x f2
b x f5
x f3
x x f4
x f6
.fi
.if n \{\
.RE
.\}
.RE
.SH "COMPARISON METHODS"
.SS "delta"
.sp
If specified the \fIDelta\fR column is displayed with value \fId\fR computed as:
.sp
.if n \{\
.RS 4
.\}
.nf
d = A\->period_percent \- B\->period_percent
.fi
.if n \{\
.RE
.\}
.sp
with: \- A/B being matching hist entry from data/baseline file specified (or perf\&.data/perf\&.data\&.old) respectively\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
period_percent being the % of the hist entry period value within single data file
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
with filtering by \-C, \-d and/or \-S, period_percent might be changed relative to how entries are filtered\&. Use \-\-percentage=absolute to prevent such fluctuation\&.
.RE
.SS "delta\-abs"
.sp
Same as \*(Aqdelta` method, but sort the result with the absolute values\&.
.SS "ratio"
.sp
If specified the \fIRatio\fR column is displayed with value \fIr\fR computed as:
.sp
.if n \{\
.RS 4
.\}
.nf
r = A\->period / B\->period
.fi
.if n \{\
.RE
.\}
.sp
with: \- A/B being matching hist entry from data/baseline file specified (or perf\&.data/perf\&.data\&.old) respectively\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
period being the hist entry period value
.RE
.SS "wdiff:WEIGHT\-B,WEIGHT\-A"
.sp
If specified the \fIWeighted diff\fR column is displayed with value \fId\fR computed as:
.sp
.if n \{\
.RS 4
.\}
.nf
d = B\->period * WEIGHT\-A \- A\->period * WEIGHT\-B
.fi
.if n \{\
.RE
.\}
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A/B being matching hist entry from data/baseline file specified (or perf\&.data/perf\&.data\&.old) respectively\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
period being the hist entry period value
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
WEIGHT\-A/WEIGHT\-B being user supplied weights in the the
\fI\-c\fR
option behind
\fI:\fR
separator like
\fI\-c wdiff:1,2\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
WEIGHT\-A being the weight of the data file
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
WEIGHT\-B being the weight of the baseline data file
.RE
.SS "cycles"
.sp
If specified the \fI[Program Block Range] Cycles Diff\fR column is displayed\&. It displays the cycles difference of same program basic block amongst two perf\&.data\&. The program basic block is the code between two branches\&.
.sp
\fI[Program Block Range]\fR indicates the range of a program basic block\&. Source line is reported if it can be found otherwise uses symbol+offset instead\&.
.SH "SEE ALSO"
.sp
\fBperf-record\fR(1), \fBperf-report\fR(1)