docs/performance/profiling_with_xperf.md

   1 # Profiling with xperf
   2
   3 Xperf is part of the Microsoft Windows Performance Toolkit, and has
   4 functionality similar to that of Shark, oprofile, and (for some things)
   5 dtrace/Instruments. For stack walking, Windows Vista or higher is
   6 required; I haven't tested it at all on XP.
   7
   8 This page applies to xperf version **4.8.7701 or newer**. To see your
   9 xperf version, either run '`xperf`' on a command line with no
  10 arguments, or start '`xperfview`' and look at Help -\> About
  11 Performance Analyzer. (Note that it's not the first version number in
  12 the About window; that's the Windows version.)
  13
  14 If you have an older version, you will experience bugs, especially
  15 around symbol loading for local builds.
  16
  17 ## Installation
  18
  19 For all versions, the tools are part of the latest [Windows 7 SDK (SDK
  20 Version
  21 7.1)](http://www.microsoft.com/downloads/details.aspx?FamilyID=6b6c21d2-2006-4afa-9702-529fa782d63b&displaylang=en "http://www.microsoft.com/downloads/details.aspx?FamilyID=6b6c21d2-2006-4afa-9702-529fa782d63b&displaylang=en"){.external}.
  22 Use the web installer to install at least the \"Win32 Development
  23 Tools\". Once the SDK installs, execute either `wpt_x86.msi` or
  24 `wpt_x64.msi` in the `Redist/Windows Performance Toolkit `folder of the
  25 SDK's install location (typically Program Files/Microsoft
  26 SDKs/Windows/v7.1/Redist/Windows Performance Toolkit) to actually
  27 install the Windows Performance Toolkit tools.
  28
  29 It might already be installed by the Windows SDK. Check if C:\\Program
  30 Files\\Microsoft Windows Performance Toolkit already exists.
  31
  32 For 64-bit Windows 7 or Vista, you'll need to do a registry tweak and
  33 then restart to enable stack walking:\
  34 \
  35 `REG ADD "HKLM\System\CurrentControlSet\Control\Session Manager\Memory Management" -v DisablePagingExecutive -d 0x1 -t REG_DWORD -f`
  36
  37 ## Symbol Server Setup
  38
  39 With the latest versions of the Windows Performance Toolkit, you can
  40 modify the symbol path directly from within the program via the Trace
  41 menu. Just make sure you set the symbol paths before enabling \"Load
  42 Symbols\" and before opening a summary view. You can also modify the
  43 `_NT_SYMBOL_PATH` and `_NT_SYMCACHE_PATH` environment variables to make
  44 these changes permanent.
  45
  46 The standard symbol path that includes both Mozilla's and Microsoft's
  47 symbol server configuration is as follows:
  48
  49 `_NT_SYMCACHE_PATH: C:\symbols  _NT_SYMBOL_PATH: srv*c:\symbols*http://msdl.microsoft.com/download/symbols;srv*c:\symbols*http://symbols.mozilla.org/firefox/`
  50
  51 To add symbols **from your own builds**, add
  52 `C:\path\to\objdir\dist\bin` to `_NT_SYMBOL_PATH`. As with all Windows
  53 paths, the symbol path uses semicolons (`;`) as separators.
  54
  55 Make sure you select the Trace -\> Load Symbols menu option in the
  56 Windows Performance Analyzer (xperfview).
  57
  58 There seems to be a bug in xperf and symbols; it is very sensitive to
  59 when the symbol path is edited. If you change it within the program,
  60 you'll have to close all summary tables and reopen them for it to pick
  61 up the new symbol path data.
  62
  63 You'll have to agree to a EULA for the Microsoft symbols \-- if you're
  64 not prompted for this, then something isn't configured right in your
  65 symbol path. (Again, make sure that the directories exist; if they
  66 don't, it's a silent error.)
  67
  68 ## Quick Start
  69
  70 All these tools will live, by default, in C:\\Program Files\\Microsoft
  71 Windows Performance Toolkit. Either run these commands from there, or
  72 add the directory to your path. You will need to use an elevated command
  73 prompt to start or stop profiling.
  74
  75 Start recording data:
  76
  77 `xperf -on latency -stackwalk profile`
  78
  79 \"Latency\" is a special provider name that turns on a few predefined
  80 kernel providers; run \"xperf -providers k\" to view a full list of
  81 providers and groups. You can combine providers, e.g., \"xperf -on
  82 DiagEasy+FILE_IO\". \"-stackwalk profile\" tells xperf to capture a
  83 stack for each PROFILE event; you could also do \"-stackwalk
  84 profile+file_io\" to capture a stack on each cpu profile tick and each
  85 file io completion event.
  86
  87 Stop:
  88
  89 `xperf -d out.etl`
  90
  91 View:
  92
  93 `xperfview out.etl`
  94
  95 The MSDN
  96 \"[Quickstart](http://msdn.microsoft.com/en-us/library/ff190971%28v=VS.85%29.aspx){.external}\"
  97 page goes over this in more detail, and also has good explanations of
  98 how to use xperfview. I'm not going to repeat it here, because I'd be
  99 using essentially the same screenshots, so go look there.
 100
 101 The 'stack' view will give results similar to shark.
 102
 103 ## Heap Profiling
 104
 105 xperf has good tools for heap allocation profiling, but they have one
 106 major limitation: you can't build with jemalloc and get heap events
 107 generated. The stock windows CRT allocator is horrible about
 108 fragmentation, and causes memory usage to rise drastically even if only
 109 a small fraction of that memory is in use. However, even despite this,
 110 it's a useful way to track allocations/deallocations.
 111
 112 ### Capturing Heap Data
 113
 114 The \"-heap\" option is used to set up heap tracing. Firefox generates
 115 lots of events, so you may want to play with the
 116 BufferSize/MinBuffers/MaxBuffers options as well to ensure that you
 117 don't get dropped events. Also, when recording the stack, I've found
 118 that a heap trace is often missing module information (I believe this is
 119 a bug in xperf). It's possible to get around that by doing a
 120 simultaneous capture of non-heap data.
 121
 122 To start a trace session, launching a new Firefox instance:
 123
 124 `xperf -on base  xperf -start heapsession -heap -PidNewProcess "./firefox.exe -P test -no-remote" -stackwalk HeapAlloc+HeapRealloc -BufferSize 512 -MinBuffers 128 -MaxBuffers 512`
 125
 126 To stop a session and merge the resulting files:
 127
 128 `xperf -stop heapsession -d heap.etl  xperf -d main.etl  xperf -merge main.etl heap.etl result.etl`
 129
 130 \"result.etl\" will contain your merged data; you can delete main.etl
 131 and heap.etl. Note that it's possible to capture even more data for the
 132 non-heap profile; for example, you might want to be able to correlate
 133 heap events with performance data, so you can do
 134 \"`xperf -on base -stackwalk profile`\".
 135
 136 In the viewer, when summary data is viewed for heap events (Heap
 137 Allocations Outstanding, etc. all lead to the same summary graphs), 3
 138 types of allocations are listed \-- AIFI, AIFO, AOFI. This is shorthand
 139 for \"Allocated Inside, Freed Inside\", \"Allocated Inside, Freed
 140 Outside\", \"Allocated Outside, Freed Inside\". These refer to the time
 141 range that was selected for the summary graph; for example, something
 142 that's in the AOFI category was allocated before the start of the
 143 selected time range, but the free event happened inside.
 144
 145 ## Tips
 146
 147 -   In the summary views, the yellow bar can be dragged left and right
 148     to change the grouping \-- for example, drag it to the left of the
 149     Module column to have grouping happen only by process (stuff that's
 150     to the left), so that you get symbols in order of weight, regardless
 151     of what module they're in.
 152 -   Dragging the columns around will change grouping in various ways;
 153     experiment to get the data that you're looking for. Also experiment
 154     with turning columns on and off; removing a column will allow data
 155     to be aggregated without considering that column's contributions.
 156 -   Disabling all but one core will make the numbers add up to 100%.
 157     This can be done by running 'msconfig' and going to Advance
 158     Options from the \"Boot\" tab.
 159
 160 ## Building Firefox
 161
 162 To get good data from a Firefox build, it is important to build with the
 163 following options in your mozconfig:
 164
 165 `export CFLAGS="-Oy-"  export CXXFLAGS="-Oy-"`
 166
 167 This disables frame-pointer optimization which lets xperf do a much
 168 better job unwinding the stack. Traces can be captured fine without this
 169 option (for example, from nightlies), but the stack information will not
 170 be useful.
 171
 172 `ac_add_options --enable-debug-symbols`
 173
 174 This gives us symbols.
 175
 176 ## For More Information
 177
 178 Microsoft's [documentation for xperf](http://msdn.microsoft.com/en-us/library/ff191077.aspx "http://msdn.microsoft.com/en-us/library/ff191077.aspx")
 179 is pretty good; there is a lot of depth to this tool, and you should
 180 look there for more details.