3 * Base class for profiling.
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.
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.
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
22 * @defgroup Profiler Profiler
26 * Profiler base class that defines the interface and some trivial
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 /** @var IContextSource Current request context */
39 protected $context = null;
41 /** @var TransactionProfiler */
42 protected $trxProfiler;
45 * @var array Mapping of output type to class name
47 private static $outputTypes = array(
48 'db' => 'ProfilerOutputDb',
49 'text' => 'ProfilerOutputText',
50 'udp' => 'ProfilerOutputUdp',
51 'dump' => 'ProfilerOutputDump',
52 'stats' => 'ProfilerOutputStats',
56 private static $instance = null;
59 * @param array $params
61 public function __construct( array $params ) {
62 if ( isset( $params['profileID'] ) ) {
63 $this->profileID
= $params['profileID'];
65 $this->params
= $params;
66 $this->trxProfiler
= new TransactionProfiler();
73 final public static function instance() {
74 if ( self
::$instance === null ) {
75 global $wgProfiler, $wgProfileLimit;
78 'class' => 'ProfilerStub',
80 'threshold' => $wgProfileLimit,
83 if ( is_array( $wgProfiler ) ) {
84 $params = array_merge( $params, $wgProfiler );
87 $inSample = mt_rand( 0, $params['sampling'] - 1 ) === 0;
88 if ( PHP_SAPI
=== 'cli' ||
!$inSample ) {
89 $params['class'] = 'ProfilerStub';
92 if ( !is_array( $params['output'] ) ) {
93 $params['output'] = array( $params['output'] );
96 self
::$instance = new $params['class']( $params );
98 return self
::$instance;
102 * Replace the current profiler with $profiler if no non-stub profiler is set
104 * @param Profiler $profiler
105 * @throws MWException
108 final public static function replaceStubInstance( Profiler
$profiler ) {
109 if ( self
::$instance && !( self
::$instance instanceof ProfilerStub
) ) {
110 throw new MWException( 'Could not replace non-stub profiler instance.' );
112 self
::$instance = $profiler;
119 public function setProfileID( $id ) {
120 $this->profileID
= $id;
126 public function getProfileID() {
127 if ( $this->profileID
=== false ) {
130 return $this->profileID
;
135 * Sets the context for this Profiler
137 * @param IContextSource $context
140 public function setContext( $context ) {
141 $this->context
= $context;
145 * Gets the context for this Profiler
147 * @return IContextSource
150 public function getContext() {
151 if ( $this->context
) {
152 return $this->context
;
154 wfDebug( __METHOD__
. " called and \$context is null. " .
155 "Return RequestContext::getMain(); for sanity\n" );
156 return RequestContext
::getMain();
160 // Kept BC for now, remove when possible
161 public function profileIn( $functionname ) {}
162 public function profileOut( $functionname ) {}
165 * Mark the start of a custom profiling frame (e.g. DB queries).
166 * The frame ends when the result of this method falls out of scope.
168 * @param string $section
169 * @return ScopedCallback|null
172 abstract public function scopedProfileIn( $section );
175 * @param ScopedCallback $section
177 public function scopedProfileOut( ScopedCallback
&$section = null ) {
182 * @return TransactionProfiler
185 public function getTransactionProfiler() {
186 return $this->trxProfiler
;
190 * Close opened profiling sections
192 abstract public function close();
195 * Get all usable outputs.
197 * @throws MWException
198 * @return array Array of ProfilerOutput instances.
201 private function getOutputs() {
203 foreach ( $this->params
['output'] as $outputType ) {
204 if ( !isset( self
::$outputTypes[$outputType] ) ) {
205 throw new MWException( "'$outputType' is an invalid output type" );
207 $outputClass = self
::$outputTypes[$outputType];
208 $outputInstance = new $outputClass( $this, $this->params
);
209 if ( $outputInstance->canUse() ) {
210 $outputs[] = $outputInstance;
217 * Log the data to some store or even the page output
221 public function logData() {
222 $request = $this->getContext()->getRequest();
224 $timeElapsed = $request->getElapsedTime();
225 $timeElapsedThreshold = $this->params
['threshold'];
226 if ( $timeElapsed <= $timeElapsedThreshold ) {
230 $outputs = $this->getOutputs();
235 $stats = $this->getFunctionStats();
236 foreach ( $outputs as $output ) {
237 $output->log( $stats );
242 * Get the content type sent out to the client.
243 * Used for profilers that output instead of store data.
247 public function getContentType() {
248 foreach ( headers_list() as $header ) {
249 if ( preg_match( '#^content-type: (\w+/\w+);?#i', $header, $m ) ) {
257 * Mark this call as templated or not
261 public function setTemplated( $t ) {
262 $this->templated
= $t;
266 * Was this call as templated or not
270 public function getTemplated() {
271 return $this->templated
;
275 * Get the aggregated inclusive profiling data for each method
277 * The percent time for each time is based on the current "total" time
278 * used is based on all methods so far. This method can therefore be
279 * called several times in between several profiling calls without the
280 * delays in usage of the profiler skewing the results. A "-total" entry
281 * is always included in the results.
283 * When a call chain involves a method invoked within itself, any
284 * entries for the cyclic invocation should be be demarked with "@".
285 * This makes filtering them out easier and follows the xhprof style.
287 * @return array List of method entries arrays, each having:
288 * - name : method name
289 * - calls : the number of invoking calls
290 * - real : real time ellapsed (ms)
291 * - %real : percent real time
292 * - cpu : CPU time ellapsed (ms)
293 * - %cpu : percent CPU time
294 * - memory : memory used (bytes)
295 * - %memory : percent memory used
296 * - min_real : min real time in a call (ms)
297 * - max_real : max real time in a call (ms)
300 abstract public function getFunctionStats();
303 * Returns a profiling output to be stored in debug file
307 abstract public function getOutput();