src/docs/user/field/xhprof.diviner

   1 @title Using XHProf
   2 @group fieldmanual
   3
   4 Describes how to install and use XHProf, a PHP profiling tool.
   5
   6 Overview
   7 ========
   8
   9 XHProf is a profiling tool which will let you understand application
  10 performance in Phabricator.
  11
  12 After you install XHProf, you can use it from the web UI and the CLI to
  13 generate detailed performance profiles. It is the most powerful tool available
  14 for understanding application performance and identifying and fixing slow code.
  15
  16 Installing XHProf
  17 =================
  18
  19 You are likely to have the most luck building XHProf from source:
  20
  21   $ git clone https://github.com/phacility/xhprof.git
  22
  23 From any source distribution of the extension, build and install it like this:
  24
  25   $ cd xhprof/
  26   $ cd extension/
  27   $ phpize
  28   $ ./configure
  29   $ make
  30   $ sudo make install
  31
  32 You may also need to add `extension=xhprof.so` to your php.ini.
  33
  34 You can also try using PECL to install it, but this may not work well with
  35 recent versions of PHP:
  36
  37   $ pecl install xhprof
  38
  39 Once you've installed it, `php -i` should report it as installed (you may
  40 see a different version number, which is fine):
  41
  42   $ php -i | grep xhprof
  43   ...
  44   xhprof => 0.9.2
  45   ...
  46
  47
  48 Using XHProf: Web UI
  49 ====================
  50
  51 To profile a web page, activate DarkConsole and navigate to the XHProf tab.
  52 Use the **Profile Page** button to generate a profile.
  53
  54 For instructions on activating DarkConsole, see @{article:Using DarkConsole}.
  55
  56
  57 Using XHProf: CLI
  58 =================
  59
  60 From the command line, use the `--xprofile <filename>` flag to generate a
  61 profile of any script.
  62
  63 You can then upload this file to Phabricator (using `arc upload` may be easiest)
  64 and view it in the web UI.
  65
  66
  67 Analyzing Profiles
  68 ==================
  69
  70 Understanding profiles is as much art as science, so be warned that you may not
  71 make much headway. Even if you aren't able to conclusively read a profile
  72 yourself, you can attach profiles when submitting bug reports to the upstream
  73 and we can look at them. This may yield new insight.
  74
  75 When looking at profiles, the "Wall Time (Inclusive)" column is usually the
  76 most important. This shows the total amount of time spent in a function or
  77 method and all of its children. Usually, to improve the performance of a page,
  78 we're trying to find something that's slow and make it not slow: this column
  79 can help identify which things are slowest.
  80
  81 The "Wall Time (Exclusive)" column shows time spent in a function or method,
  82 excluding time spent in its children. This can give you hint about whether the
  83 call itself is slow or it's just making calls to other things that are slow.
  84
  85 You can also get a sense of this by clicking a call to see its children, and
  86 seeing if the bulk of runtime is spent in a child call. This tends to indicate
  87 that you're looking at a problem which is deeper in the stack, and you need
  88 to go down further to identify and understand it.
  89
  90 Conversely, if the "Wall Time (Exclusive)" column is large, or the children
  91 of a call are all cheap, there's probably something expensive happening in the
  92 call itself.
  93
  94 The "Count" column can also sometimes tip you off that something is amiss, if
  95 a method which shouldn't be called very often is being called a lot.
  96
  97 Some general thing to look for -- these aren't smoking guns, but are unusual
  98 and can lead to finding a performance issue:
  99
 100   - Is a low-level utility method like `phutil_utf8ize()` or `array_merge()`
 101     taking more than a few percent of the page runtime?
 102   - Do any methods (especially high-level methods) have >10,00 calls?
 103   - Are we spending more than 100ms doing anything which isn't loading data
 104     or rendering data?
 105   - Does anything look suspiciously expensive or out of place?
 106   - Is the profile for the slow page a lot different than the profile for a
 107     fast page?
 108
 109 Some performance problems are obvious and will jump out of a profile; others
 110 may require a more nuanced understanding of the codebase to sniff out which
 111 parts are suspicious. If you aren't able to make progress with a profile,
 112 report the issue upstream and attach the profile to your report.
 113
 114
 115 Next Steps
 116 ==========
 117
 118 Continue by:
 119
 120   - enabling DarkConsole with @{article:Using DarkConsole}; or
 121   - understanding and reporting performance problems with
 122     @{article:Troubleshooting Performance Problems}.