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