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