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.
  37
  38 -C::
  39 --comms=::
  40         Only consider symbols in these comms. CSV that understands
  41         file://filename entries.
  42
  43 -S::
  44 --symbols=::
  45         Only consider these symbols. CSV that understands
  46         file://filename entries.
  47
  48 -s::
  49 --sort=::
  50         Sort by key(s): pid, comm, dso, symbol.
  51
  52 -t::
  53 --field-separator=::
  54
  55         Use a special separator character and don't pad with spaces, replacing
  56         all occurrences of this separator in symbol names (and other output)
  57         with a '.' character, that thus it's the only non valid separator.
  58
  59 -v::
  60 --verbose::
  61         Be verbose, for instance, show the raw counts in addition to the
  62         diff.
  63
  64 -f::
  65 --force::
  66        Don't complain, do it.
  67
  68 --symfs=<directory>::
  69         Look for files with symbols relative to this directory.
  70
  71 -b::
  72 --baseline-only::
  73         Show only items with match in baseline.
  74
  75 -c::
  76 --compute::
  77         Differential computation selection - delta,ratio,wdiff (default is delta).
  78         See COMPARISON METHODS section for more info.
  79
  80 -p::
  81 --period::
  82         Show period values for both compared hist entries.
  83
  84 -F::
  85 --formula::
  86         Show formula for given computation.
  87
  88 -o::
  89 --order::
  90        Specify compute sorting column number.
  91
  92 COMPARISON
  93 ----------
  94 The comparison is governed by the baseline file. The baseline perf.data
  95 file is iterated for samples. All other perf.data files specified on
  96 the command line are searched for the baseline sample pair. If the pair
  97 is found, specified computation is made and result is displayed.
  98
  99 All samples from non-baseline perf.data files, that do not match any
 100 baseline entry, are displayed with empty space within baseline column
 101 and possible computation results (delta) in their related column.
 102
 103 Example files samples:
 104 - file A with samples f1, f2, f3, f4,    f6
 105 - file B with samples     f2,     f4, f5
 106 - file C with samples f1, f2,         f5
 107
 108 Example output:
 109   x - computation takes place for pair
 110   b - baseline sample percentage
 111
 112 - perf diff A B C
 113
 114   baseline/A compute/B compute/C  samples
 115   ---------------------------------------
 116   b                    x          f1
 117   b          x         x          f2
 118   b                               f3
 119   b          x                    f4
 120   b                               f6
 121              x         x          f5
 122
 123 - perf diff B A C
 124
 125   baseline/B compute/A compute/C  samples
 126   ---------------------------------------
 127   b          x         x          f2
 128   b          x                    f4
 129   b                    x          f5
 130              x         x          f1
 131              x                    f3
 132              x                    f6
 133
 134 - perf diff C B A
 135
 136   baseline/C compute/B compute/A  samples
 137   ---------------------------------------
 138   b                    x          f1
 139   b          x         x          f2
 140   b          x                    f5
 141                        x          f3
 142              x         x          f4
 143                        x          f6
 144
 145 COMPARISON METHODS
 146 ------------------
 147 delta
 148 ~~~~~
 149 If specified the 'Delta' column is displayed with value 'd' computed as:
 150
 151   d = A->period_percent - B->period_percent
 152
 153 with:
 154   - A/B being matching hist entry from data/baseline file specified
 155     (or perf.data/perf.data.old) respectively.
 156
 157   - period_percent being the % of the hist entry period value within
 158     single data file
 159
 160 ratio
 161 ~~~~~
 162 If specified the 'Ratio' column is displayed with value 'r' computed as:
 163
 164   r = A->period / B->period
 165
 166 with:
 167   - A/B being matching hist entry from data/baseline file specified
 168     (or perf.data/perf.data.old) respectively.
 169
 170   - period being the hist entry period value
 171
 172 wdiff:WEIGHT-B,WEIGHT-A
 173 ~~~~~~~~~~~~~~~~~~~~~~~
 174 If specified the 'Weighted diff' column is displayed with value 'd' computed as:
 175
 176    d = B->period * WEIGHT-A - A->period * WEIGHT-B
 177
 178   - A/B being matching hist entry from data/baseline file specified
 179     (or perf.data/perf.data.old) respectively.
 180
 181   - period being the hist entry period value
 182
 183   - WEIGHT-A/WEIGHT-B being user suplied weights in the the '-c' option
 184     behind ':' separator like '-c wdiff:1,2'.
 185     - WIEGHT-A being the weight of the data file
 186     - WIEGHT-B being the weight of the baseline data file
 187
 188 SEE ALSO
 189 --------
 190 linkperf:perf-record[1]