tools/perf/Documentation/perf-diff.txt

   1 perf-diff(1)
   2 ============
   3
   4 NAME
   5 ----
   6 perf-diff - Read perf.data files and display the differential profile
   7
   8 SYNOPSIS
   9 --------
  10 [verse]
  11 'perf diff' [baseline file] [data file1] [[data file2] ... ]
  12
  13 DESCRIPTION
  14 -----------
  15 This command displays the performance difference amongst two or more perf.data
  16 files captured via perf record.
  17
  18 If no parameters are passed it will assume perf.data.old and perf.data.
  19
  20 The differential profile is displayed only for events matching both
  21 specified perf.data files.
  22
  23 If no parameters are passed the samples will be sorted by dso and symbol.
  24 As the perf.data files could come from different binaries, the symbols addresses
  25 could vary. So perf diff is based on the comparison of the files and
  26 symbols name.
  27
  28 OPTIONS
  29 -------
  30 -D::
  31 --dump-raw-trace::
  32         Dump raw trace in ASCII.
  33
  34 --kallsyms=<file>::
  35         kallsyms pathname
  36
  37 -m::
  38 --modules::
  39         Load module symbols. WARNING: use only with -k and LIVE kernel
  40
  41 -d::
  42 --dsos=::
  43         Only consider symbols in these dsos. CSV that understands
  44         file://filename entries.  This option will affect the percentage
  45         of the Baseline/Delta column.  See --percentage for more info.
  46
  47 -C::
  48 --comms=::
  49         Only consider symbols in these comms. CSV that understands
  50         file://filename entries.  This option will affect the percentage
  51         of the Baseline/Delta column.  See --percentage for more info.
  52
  53 -S::
  54 --symbols=::
  55         Only consider these symbols. CSV that understands
  56         file://filename entries.  This option will affect the percentage
  57         of the Baseline/Delta column.  See --percentage for more info.
  58
  59 -s::
  60 --sort=::
  61         Sort by key(s): pid, comm, dso, symbol, cpu, parent, srcline.
  62         Please see description of --sort in the perf-report man page.
  63
  64 -t::
  65 --field-separator=::
  66
  67         Use a special separator character and don't pad with spaces, replacing
  68         all occurrences of this separator in symbol names (and other output)
  69         with a '.' character, that thus it's the only non valid separator.
  70
  71 -v::
  72 --verbose::
  73         Be verbose, for instance, show the raw counts in addition to the
  74         diff.
  75
  76 -f::
  77 --force::
  78        Don't complain, do it.
  79
  80 --symfs=<directory>::
  81         Look for files with symbols relative to this directory.
  82
  83 -b::
  84 --baseline-only::
  85         Show only items with match in baseline.
  86
  87 -c::
  88 --compute::
  89         Differential computation selection - delta,ratio,wdiff (default is delta).
  90         See COMPARISON METHODS section for more info.
  91
  92 -p::
  93 --period::
  94         Show period values for both compared hist entries.
  95
  96 -F::
  97 --formula::
  98         Show formula for given computation.
  99
 100 -o::
 101 --order::
 102        Specify compute sorting column number.
 103
 104 --percentage::
 105         Determine how to display the overhead percentage of filtered entries.
 106         Filters can be applied by --comms, --dsos and/or --symbols options.
 107
 108         "relative" means it's relative to filtered entries only so that the
 109         sum of shown entries will be always 100%.  "absolute" means it retains
 110         the original value before and after the filter is applied.
 111
 112 COMPARISON
 113 ----------
 114 The comparison is governed by the baseline file. The baseline perf.data
 115 file is iterated for samples. All other perf.data files specified on
 116 the command line are searched for the baseline sample pair. If the pair
 117 is found, specified computation is made and result is displayed.
 118
 119 All samples from non-baseline perf.data files, that do not match any
 120 baseline entry, are displayed with empty space within baseline column
 121 and possible computation results (delta) in their related column.
 122
 123 Example files samples:
 124 - file A with samples f1, f2, f3, f4,    f6
 125 - file B with samples     f2,     f4, f5
 126 - file C with samples f1, f2,         f5
 127
 128 Example output:
 129   x - computation takes place for pair
 130   b - baseline sample percentage
 131
 132 - perf diff A B C
 133
 134   baseline/A compute/B compute/C  samples
 135   ---------------------------------------
 136   b                    x          f1
 137   b          x         x          f2
 138   b                               f3
 139   b          x                    f4
 140   b                               f6
 141              x         x          f5
 142
 143 - perf diff B A C
 144
 145   baseline/B compute/A compute/C  samples
 146   ---------------------------------------
 147   b          x         x          f2
 148   b          x                    f4
 149   b                    x          f5
 150              x         x          f1
 151              x                    f3
 152              x                    f6
 153
 154 - perf diff C B A
 155
 156   baseline/C compute/B compute/A  samples
 157   ---------------------------------------
 158   b                    x          f1
 159   b          x         x          f2
 160   b          x                    f5
 161                        x          f3
 162              x         x          f4
 163                        x          f6
 164
 165 COMPARISON METHODS
 166 ------------------
 167 delta
 168 ~~~~~
 169 If specified the 'Delta' column is displayed with value 'd' computed as:
 170
 171   d = A->period_percent - B->period_percent
 172
 173 with:
 174   - A/B being matching hist entry from data/baseline file specified
 175     (or perf.data/perf.data.old) respectively.
 176
 177   - period_percent being the % of the hist entry period value within
 178     single data file
 179
 180   - with filtering by -C, -d and/or -S, period_percent might be changed
 181     relative to how entries are filtered.  Use --percentage=absolute to
 182     prevent such fluctuation.
 183
 184 ratio
 185 ~~~~~
 186 If specified the 'Ratio' column is displayed with value 'r' computed as:
 187
 188   r = A->period / B->period
 189
 190 with:
 191   - A/B being matching hist entry from data/baseline file specified
 192     (or perf.data/perf.data.old) respectively.
 193
 194   - period being the hist entry period value
 195
 196 wdiff:WEIGHT-B,WEIGHT-A
 197 ~~~~~~~~~~~~~~~~~~~~~~~
 198 If specified the 'Weighted diff' column is displayed with value 'd' computed as:
 199
 200    d = B->period * WEIGHT-A - A->period * WEIGHT-B
 201
 202   - A/B being matching hist entry from data/baseline file specified
 203     (or perf.data/perf.data.old) respectively.
 204
 205   - period being the hist entry period value
 206
 207   - WEIGHT-A/WEIGHT-B being user supplied weights in the the '-c' option
 208     behind ':' separator like '-c wdiff:1,2'.
 209     - WEIGHT-A being the weight of the data file
 210     - WEIGHT-B being the weight of the baseline data file
 211
 212 SEE ALSO
 213 --------
 214 linkperf:perf-record[1], linkperf:perf-report[1]