includes/libs/Xhprof.php

   1 <?php
   2 /**
   3  * This program is free software; you can redistribute it and/or modify
   4  * it under the terms of the GNU General Public License as published by
   5  * the Free Software Foundation; either version 2 of the License, or
   6  * (at your option) any later version.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along
  14  * with this program; if not, write to the Free Software Foundation, Inc.,
  15  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  16  * http://www.gnu.org/copyleft/gpl.html
  17  *
  18  * @file
  19  */
  20
  21 /**
  22  * Convenience class for working with XHProf
  23  * <https://github.com/phacility/xhprof>. XHProf can be installed as a PECL
  24  * package for use with PHP5 (Zend PHP) and is built-in to HHVM 3.3.0.
  25  *
  26  * @author Bryan Davis <bd808@wikimedia.org>
  27  * @copyright © 2014 Bryan Davis and Wikimedia Foundation.
  28  * @since 1.25
  29  */
  30 class Xhprof {
  31
  32         /**
  33          * @var array $config
  34          */
  35         protected $config;
  36
  37         /**
  38          * Hierarchical profiling data returned by xhprof.
  39          * @var array $hieraData
  40          */
  41         protected $hieraData;
  42
  43         /**
  44          * Per-function inclusive data.
  45          * @var array $inclusive
  46          */
  47         protected $inclusive;
  48
  49         /**
  50          * Per-function inclusive and exclusive data.
  51          * @var array $complete
  52          */
  53         protected $complete;
  54
  55         /**
  56          * Configuration data can contain:
  57          * - flags:   Optional flags to add additional information to the
  58          *            profiling data collected.
  59          *            (XHPROF_FLAGS_NO_BUILTINS, XHPROF_FLAGS_CPU,
  60          *            XHPROF_FLAGS_MEMORY)
  61          * - exclude: Array of function names to exclude from profiling.
  62          * - include: Array of function names to include in profiling.
  63          * - sort:    Key to sort per-function reports on.
  64          *
  65          * Note: When running under HHVM, xhprof will always behave as though the
  66          * XHPROF_FLAGS_NO_BUILTINS flag has been used unless the
  67          * Eval.JitEnableRenameFunction option is enabled for the HHVM process.
  68          *
  69          * @param array $config
  70          */
  71         public function __construct( array $config = array() ) {
  72                 $this->config = array_merge(
  73                         array(
  74                                 'flags' => 0,
  75                                 'exclude' => array(),
  76                                 'include' => null,
  77                                 'sort' => 'wt',
  78                         ),
  79                         $config
  80                 );
  81
  82                 xhprof_enable( $this->config['flags'], array(
  83                         'ignored_functions' => $this->config['exclude']
  84                 ) );
  85         }
  86
  87         /**
  88          * Stop collecting profiling data.
  89          *
  90          * Only the first invocation of this method will effect the internal
  91          * object state. Subsequent calls will return the data collected by the
  92          * initial call.
  93          *
  94          * @return array Collected profiling data (possibly cached)
  95          */
  96         public function stop() {
  97                 if ( $this->hieraData === null ) {
  98                         $this->hieraData = $this->pruneData( xhprof_disable() );
  99                 }
 100                 return $this->hieraData;
 101         }
 102
 103         /**
 104          * Load raw data from a prior run for analysis.
 105          * Stops any existing data collection and clears internal caches.
 106          *
 107          * Any 'include' filters configured for this Xhprof instance will be
 108          * enforced on the data as it is loaded. 'exclude' filters will however
 109          * not be enforced as they are an XHProf intrinsic behavior.
 110          *
 111          * @param array $data
 112          * @see getRawData()
 113          */
 114         public function loadRawData( array $data ) {
 115                 $this->stop();
 116                 $this->inclusive = null;
 117                 $this->complete = null;
 118                 $this->hieraData = $this->pruneData( $data );
 119         }
 120
 121         /**
 122          * Get raw data collected by xhprof.
 123          *
 124          * If data collection has not been stopped yet this method will halt
 125          * collection to gather the profiling data.
 126          *
 127          * Each key in the returned array is an edge label for the call graph in
 128          * the form "caller==>callee". There is once special case edge labled
 129          * simply "main()" which represents the global scope entry point of the
 130          * application.
 131          *
 132          * XHProf will collect different data depending on the flags that are used:
 133          * - ct:    Number of matching events seen.
 134          * - wt:    Inclusive elapsed wall time for this event in microseconds.
 135          * - cpu:   Inclusive elapsed cpu time for this event in microseconds.
 136          *          (XHPROF_FLAGS_CPU)
 137          * - mu:    Delta of memory usage from start to end of callee in bytes.
 138          *          (XHPROF_FLAGS_MEMORY)
 139          * - pmu:   Delta of peak memory usage from start to end of callee in
 140          *          bytes. (XHPROF_FLAGS_MEMORY)
 141          * - alloc: Delta of amount memory requested from malloc() by the callee,
 142          *          in bytes. (XHPROF_FLAGS_MALLOC)
 143          * - free:  Delta of amount of memory passed to free() by the callee, in
 144          *          bytes. (XHPROF_FLAGS_MALLOC)
 145          *
 146          * @return array
 147          * @see stop()
 148          * @see getInclusiveMetrics()
 149          * @see getCompleteMetrics()
 150          */
 151         public function getRawData() {
 152                 return $this->stop();
 153         }
 154
 155         /**
 156          * Convert an xhprof data key into an array of ['parent', 'child']
 157          * function names.
 158          *
 159          * The resulting array is left padded with nulls, so a key
 160          * with no parent (eg 'main()') will return [null, 'function'].
 161          *
 162          * @return array
 163          */
 164         public static function splitKey( $key ) {
 165                 return array_pad( explode( '==>', $key, 2 ), -2, null );
 166         }
 167
 168         /**
 169          * Remove data for functions that are not included in the 'include'
 170          * configuration array.
 171          *
 172          * @param array $data Raw xhprof data
 173          * @return array
 174          */
 175         protected function pruneData( $data ) {
 176                 if ( !$this->config['include'] ) {
 177                         return $data;
 178                 }
 179
 180                 $want = array_fill_keys( $this->config['include'], true );
 181                 $want['main()'] = true;
 182
 183                 $keep = array();
 184                 foreach ( $data as $key => $stats ) {
 185                         list( $parent, $child ) = self::splitKey( $key );
 186                         if ( isset( $want[$parent] ) || isset( $want[$child] ) ) {
 187                                 $keep[$key] = $stats;
 188                         }
 189                 }
 190                 return $keep;
 191         }
 192
 193         /**
 194          * Get the inclusive metrics for each function call. Inclusive metrics
 195          * for given function include the metrics for all functions that were
 196          * called from that function during the measurement period.
 197          *
 198          * If data collection has not been stopped yet this method will halt
 199          * collection to gather the profiling data.
 200          *
 201          * See getRawData() for a description of the metric that are returned for
 202          * each funcition call. The values for the wt, cpu, mu and pmu metrics are
 203          * arrays with these values:
 204          * - total: Cumulative value
 205          * - min: Minimum value
 206          * - mean: Mean (average) value
 207          * - max: Maximum value
 208          * - variance: Variance (spread) of the values
 209          *
 210          * @return array
 211          * @see getRawData()
 212          * @see getCompleteMetrics()
 213          */
 214         public function getInclusiveMetrics() {
 215                 if ( $this->inclusive === null ) {
 216                         // Make sure we have data to work with
 217                         $this->stop();
 218
 219                         $main = $this->hieraData['main()'];
 220                         $hasCpu = isset( $main['cpu'] );
 221                         $hasMu = isset( $main['mu'] );
 222                         $hasAlloc = isset( $main['alloc'] );
 223
 224                         $this->inclusive = array();
 225                         foreach ( $this->hieraData as $key => $stats ) {
 226                                 list( $parent, $child ) = self::splitKey( $key );
 227                                 if ( !isset( $this->inclusive[$child] ) ) {
 228                                         $this->inclusive[$child] = array(
 229                                                 'ct' => 0,
 230                                                 'wt' => new RunningStat(),
 231                                         );
 232                                         if ( $hasCpu ) {
 233                                                 $this->inclusive[$child]['cpu'] = new RunningStat();
 234                                         }
 235                                         if ( $hasMu ) {
 236                                                 $this->inclusive[$child]['mu'] = new RunningStat();
 237                                                 $this->inclusive[$child]['pmu'] = new RunningStat();
 238                                         }
 239                                         if ( $hasAlloc ) {
 240                                                 $this->inclusive[$child]['alloc'] = new RunningStat();
 241                                                 $this->inclusive[$child]['free'] = new RunningStat();
 242                                         }
 243                                 }
 244
 245                                 $this->inclusive[$child]['ct'] += $stats['ct'];
 246                                 foreach ( $stats as $stat => $value ) {
 247                                         if ( $stat === 'ct' ) {
 248                                                 continue;
 249                                         }
 250
 251                                         if ( !isset( $this->inclusive[$child][$stat] ) ) {
 252                                                 // Ignore unknown stats
 253                                                 continue;
 254                                         }
 255
 256                                         for ( $i = 0; $i < $stats['ct']; $i++ ) {
 257                                                 $this->inclusive[$child][$stat]->push(
 258                                                         $value / $stats['ct']
 259                                                 );
 260                                         }
 261                                 }
 262                         }
 263
 264                         // Convert RunningStat instances to static arrays and add
 265                         // percentage stats.
 266                         foreach ( $this->inclusive as $func => $stats ) {
 267                                 foreach ( $stats as $name => $value ) {
 268                                         if ( $value instanceof RunningStat ) {
 269                                                 $total = $value->m1 * $value->n;
 270                                                 $percent = ( isset( $main[$name] ) && $main[$name] )
 271                                                         ? 100 * $total / $main[$name]
 272                                                         : 0;
 273                                                 $this->inclusive[$func][$name] = array(
 274                                                         'total' => $total,
 275                                                         'min' => $value->min,
 276                                                         'mean' => $value->m1,
 277                                                         'max' => $value->max,
 278                                                         'variance' => $value->m2,
 279                                                         'percent' => $percent,
 280                                                 );
 281                                         }
 282                                 }
 283                         }
 284
 285                         uasort( $this->inclusive, self::makeSortFunction(
 286                                 $this->config['sort'], 'total'
 287                         ) );
 288                 }
 289                 return $this->inclusive;
 290         }
 291
 292         /**
 293          * Get the inclusive and exclusive metrics for each function call.
 294          *
 295          * If data collection has not been stopped yet this method will halt
 296          * collection to gather the profiling data.
 297          *
 298          * In addition to the normal data contained in the inclusive metrics, the
 299          * metrics have an additional 'exclusive' measurement which is the total
 300          * minus the totals of all child function calls.
 301          *
 302          * @return array
 303          * @see getRawData()
 304          * @see getInclusiveMetrics()
 305          */
 306         public function getCompleteMetrics() {
 307                 if ( $this->complete === null ) {
 308                         // Start with inclusive data
 309                         $this->complete = $this->getInclusiveMetrics();
 310
 311                         foreach ( $this->complete as $func => $stats ) {
 312                                 foreach ( $stats as $stat => $value ) {
 313                                         if ( $stat === 'ct' ) {
 314                                                 continue;
 315                                         }
 316                                         // Initialize exclusive data with inclusive totals
 317                                         $this->complete[$func][$stat]['exclusive'] = $value['total'];
 318                                 }
 319                                 // Add sapce for call tree information to be filled in later
 320                                 $this->complete[$func]['calls'] = array();
 321                                 $this->complete[$func]['subcalls'] = array();
 322                         }
 323
 324                         foreach ( $this->hieraData as $key => $stats ) {
 325                                 list( $parent, $child ) = self::splitKey( $key );
 326                                 if ( $parent !== null ) {
 327                                         // Track call tree information
 328                                         $this->complete[$child]['calls'][$parent] = $stats;
 329                                         $this->complete[$parent]['subcalls'][$child] = $stats;
 330                                 }
 331
 332                                 if ( isset( $this->complete[$parent] ) ) {
 333                                         // Deduct child inclusive data from exclusive data
 334                                         foreach ( $stats as $stat => $value ) {
 335                                                 if ( $stat === 'ct' ) {
 336                                                         continue;
 337                                                 }
 338
 339                                                 if ( !isset( $this->complete[$parent][$stat] ) ) {
 340                                                         // Ignore unknown stats
 341                                                         continue;
 342                                                 }
 343
 344                                                 $this->complete[$parent][$stat]['exclusive'] -= $value;
 345                                         }
 346                                 }
 347                         }
 348
 349                         uasort( $this->complete, self::makeSortFunction(
 350                                 $this->config['sort'], 'exclusive'
 351                         ) );
 352                 }
 353                 return $this->complete;
 354         }
 355
 356         /**
 357          * Get a list of all callers of a given function.
 358          *
 359          * @param string $function Function name
 360          * @return array
 361          * @see getEdges()
 362          */
 363         public function getCallers( $function ) {
 364                 $edges = $this->getCompleteMetrics();
 365                 if ( isset( $edges[$function]['calls'] ) ) {
 366                         return array_keys( $edges[$function]['calls'] );
 367                 } else {
 368                         return array();
 369                 }
 370         }
 371
 372         /**
 373          * Get a list of all callees from a given function.
 374          *
 375          * @param string $function Function name
 376          * @return array
 377          * @see getEdges()
 378          */
 379         public function getCallees( $function ) {
 380                 $edges = $this->getCompleteMetrics();
 381                 if ( isset( $edges[$function]['subcalls'] ) ) {
 382                         return array_keys( $edges[$function]['subcalls'] );
 383                 } else {
 384                         return array();
 385                 }
 386         }
 387
 388         /**
 389          * Find the critical path for the given metric.
 390          *
 391          * @param string $metric Metric to find critical path for
 392          * @return array
 393          */
 394         public function getCriticalPath( $metric = 'wt' ) {
 395                 $this->stop();
 396                 $func = 'main()';
 397                 $path = array(
 398                         $func => $this->hieraData[$func],
 399                 );
 400                 while ( $func ) {
 401                         $callees = $this->getCallees( $func );
 402                         $maxCallee = null;
 403                         $maxCall = null;
 404                         foreach ( $callees as $callee ) {
 405                                 $call = "{$func}==>{$callee}";
 406                                 if ( $maxCall === null ||
 407                                         $this->hieraData[$call][$metric] >
 408                                                 $this->hieraData[$maxCall][$metric]
 409                                 ) {
 410                                         $maxCallee = $callee;
 411                                         $maxCall = $call;
 412                                 }
 413                         }
 414                         if ( $maxCall !== null ) {
 415                                 $path[$maxCall] = $this->hieraData[$maxCall];
 416                         }
 417                         $func = $maxCallee;
 418                 }
 419                 return $path;
 420         }
 421
 422         /**
 423          * Make a closure to use as a sort function. The resulting function will
 424          * sort by descending numeric values (largest value first).
 425          *
 426          * @param string $key Data key to sort on
 427          * @param string $sub Sub key to sort array values on
 428          * @return Closure
 429          */
 430         public static function makeSortFunction( $key, $sub ) {
 431                 return function ( $a, $b ) use ( $key, $sub ) {
 432                         if ( isset( $a[$key] ) && isset( $b[$key] ) ) {
 433                                 // Descending sort: larger values will be first in result.
 434                                 // Assumes all values are numeric.
 435                                 // Values for 'main()' will not have sub keys
 436                                 $valA = is_array( $a[$key] ) ? $a[$key][$sub] : $a[$key];
 437                                 $valB = is_array( $b[$key] ) ? $b[$key][$sub] : $b[$key];
 438                                 return $valB - $valA;
 439                         } else {
 440                                 // Sort datum with the key before those without
 441                                 return isset( $a[$key] ) ? -1 : 1;
 442                         }
 443                 };
 444         }
 445 }