includes/profiler/Profiler.php

   1 <?php
   2 /**
   3  * Base class for profiling.
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  * @ingroup Profiler
  22  * @defgroup Profiler Profiler
  23  */
  24
  25 /**
  26  * Profiler base class that defines the interface and some trivial
  27  * functionality
  28  *
  29  * @ingroup Profiler
  30  */
  31 abstract class Profiler {
  32         /** @var string|bool Profiler ID for bucketing data */
  33         protected $profileID = false;
  34         /** @var bool Whether MediaWiki is in a SkinTemplate output context */
  35         protected $templated = false;
  36         /** @var array All of the params passed from $wgProfiler */
  37         protected $params = array();
  38
  39         /** @var TransactionProfiler */
  40         protected $trxProfiler;
  41
  42         /**
  43          * @var array Mapping of output type to class name
  44          */
  45         private static $outputTypes = array(
  46                 'db' => 'ProfilerOutputDb',
  47                 'text' => 'ProfilerOutputText',
  48                 'udp' => 'ProfilerOutputUdp',
  49         );
  50
  51         // @codingStandardsIgnoreStart PSR2.Classes.PropertyDeclaration.Underscore
  52         /** @var Profiler Do not call this outside Profiler and ProfileSection */
  53         public static $__instance = null;
  54         // @codingStandardsIgnoreEnd
  55
  56         /**
  57          * @param array $params
  58          */
  59         public function __construct( array $params ) {
  60                 if ( isset( $params['profileID'] ) ) {
  61                         $this->profileID = $params['profileID'];
  62                 }
  63                 $this->params = $params;
  64                 $this->trxProfiler = new TransactionProfiler();
  65         }
  66
  67         /**
  68          * Singleton
  69          * @return Profiler
  70          */
  71         final public static function instance() {
  72                 if ( self::$__instance === null ) {
  73                         global $wgProfiler;
  74                         if ( is_array( $wgProfiler ) ) {
  75                                 $class = isset( $wgProfiler['class'] ) ? $wgProfiler['class'] : 'ProfilerStub';
  76                                 $factor = isset( $wgProfiler['sampling'] ) ? $wgProfiler['sampling'] : 1;
  77                                 if ( PHP_SAPI === 'cli' || mt_rand( 0, $factor - 1 ) != 0 ) {
  78                                         $class = 'ProfilerStub';
  79                                 }
  80                                 self::$__instance = new $class( $wgProfiler );
  81                         } else {
  82                                 self::$__instance = new ProfilerStub( array() );
  83                         }
  84                 }
  85                 return self::$__instance;
  86         }
  87
  88         /**
  89          * Replace the current profiler with $profiler if no non-stub profiler is set
  90          *
  91          * @param Profiler $profiler
  92          * @throws MWException
  93          * @since 1.25
  94          */
  95         final public static function replaceStubInstance( Profiler $profiler ) {
  96                 if ( self::$__instance && !( self::$__instance instanceof ProfilerStub ) ) {
  97                         throw new MWException( 'Could not replace non-stub profiler instance.' );
  98                 } else {
  99                         self::$__instance = $profiler;
 100                 }
 101         }
 102
 103         /**
 104          * Return whether this a stub profiler
 105          *
 106          * @return bool
 107          */
 108         abstract public function isStub();
 109
 110         /**
 111          * @param string $id
 112          */
 113         public function setProfileID( $id ) {
 114                 $this->profileID = $id;
 115         }
 116
 117         /**
 118          * @return string
 119          */
 120         public function getProfileID() {
 121                 if ( $this->profileID === false ) {
 122                         return wfWikiID();
 123                 } else {
 124                         return $this->profileID;
 125                 }
 126         }
 127
 128         /**
 129          * Called by wfProfieIn()
 130          *
 131          * @param string $functionname
 132          */
 133         abstract public function profileIn( $functionname );
 134
 135         /**
 136          * Called by wfProfieOut()
 137          *
 138          * @param string $functionname
 139          */
 140         abstract public function profileOut( $functionname );
 141
 142         /**
 143          * Mark the start of a custom profiling frame (e.g. DB queries).
 144          * The frame ends when the result of this method falls out of scope.
 145          *
 146          * @param string $section
 147          * @return ScopedCallback|null
 148          * @since 1.25
 149          */
 150         abstract public function scopedProfileIn( $section );
 151
 152         /**
 153          * @param ScopedCallback $section
 154          */
 155         public function scopedProfileOut( ScopedCallback &$section ) {
 156                 $section = null;
 157         }
 158
 159         /**
 160          * @return TransactionProfiler
 161          * @since 1.25
 162          */
 163         public function getTransactionProfiler() {
 164                 return $this->trxProfiler;
 165         }
 166
 167         /**
 168          * Close opened profiling sections
 169          */
 170         abstract public function close();
 171
 172         /**
 173          * Log the data to some store or even the page output
 174          *
 175          * @throws MWException
 176          * @since 1.25
 177          */
 178         public function logData() {
 179                 $output = isset( $this->params['output'] ) ? $this->params['output'] : null;
 180
 181                 if ( !$output || $this->isStub() ) {
 182                         // return early when no output classes defined or we're a stub
 183                         return;
 184                 }
 185
 186                 if ( !is_array( $output ) ) {
 187                         $output = array( $output );
 188                 }
 189
 190                 foreach ( $output as $outType ) {
 191                         if ( !isset( self::$outputTypes[$outType] ) ) {
 192                                 throw new MWException( "'$outType' is an invalid output type" );
 193                         }
 194                         $class = self::$outputTypes[$outType];
 195
 196                         /** @var ProfilerOutput $profileOut */
 197                         $profileOut = new $class( $this, $this->params );
 198                         if ( $profileOut->canUse() ) {
 199                                 $profileOut->log( $this->getFunctionStats() );
 200                         }
 201                 }
 202         }
 203
 204         /**
 205          * Get the content type sent out to the client.
 206          * Used for profilers that output instead of store data.
 207          * @return string
 208          * @since 1.25
 209          */
 210         public function getContentType() {
 211                 foreach ( headers_list() as $header ) {
 212                         if ( preg_match( '#^content-type: (\w+/\w+);?#i', $header, $m ) ) {
 213                                 return $m[1];
 214                         }
 215                 }
 216                 return null;
 217         }
 218
 219         /**
 220          * Mark this call as templated or not
 221          *
 222          * @param bool $t
 223          */
 224         public function setTemplated( $t ) {
 225                 $this->templated = $t;
 226         }
 227
 228         /**
 229          * Was this call as templated or not
 230          *
 231          * @return bool
 232          */
 233         public function getTemplated() {
 234                 return $this->templated;
 235         }
 236
 237         /**
 238          * Get the aggregated inclusive profiling data for each method
 239          *
 240          * The percent time for each time is based on the current "total" time
 241          * used is based on all methods so far. This method can therefore be
 242          * called several times in between several profiling calls without the
 243          * delays in usage of the profiler skewing the results. A "-total" entry
 244          * is always included in the results.
 245          *
 246          * When a call chain involves a method invoked within itself, any
 247          * entries for the cyclic invocation should be be demarked with "@".
 248          * This makes filtering them out easier and follows the xhprof style.
 249          *
 250          * @return array List of method entries arrays, each having:
 251          *   - name    : method name
 252          *   - calls   : the number of invoking calls
 253          *   - real    : real time ellapsed (ms)
 254          *   - %real   : percent real time
 255          *   - cpu     : CPU time ellapsed (ms)
 256          *   - %cpu    : percent CPU time
 257          *   - memory  : memory used (bytes)
 258          *   - %memory : percent memory used
 259          * @since 1.25
 260          */
 261         abstract public function getFunctionStats();
 262
 263         /**
 264          * Returns a profiling output to be stored in debug file
 265          *
 266          * @return string
 267          */
 268         abstract public function getOutput();
 269 }