Detect high-contention DB queries via profiling calls. More...

Inherits LoggerAwareInterface.

Collaboration diagram for Wikimedia\Rdbms\TransactionProfiler:

Public Member Functions
	__construct ()

	getExpectation (string $event)
	Get the expectation associated with a specific event name.

	isSilenced (string $event)
	Check whether an event currently has its expectations silenced.

	recordConnection ( $server, $db, bool $isPrimaryWithReplicas)
	Mark a DB as having been connected to with a new handle.

	recordQueryCompletion ( $query, float $sTime, bool $isWrite, ?int $rowCount, string $trxId, ?string $serverName=null)
	Register the name and time of a method for slow DB trx detection.

	redefineExpectations (array $expects, string $fname)
	Clear all expectations and hit counters and set new performance expectations.

	resetExpectations ()
	Reset all performance expectations and hit counters.

	setExpectation (string $event, $limit, string $fname)
	Set performance expectations.

	setExpectations (array $expects, string $fname)
	Set one or multiple performance expectations.

	setLogger (LoggerInterface $logger)

	setMockTime (&$time)

	setRequestMethod (?string $method)

	setStatsFactory (StatsFactory $statsFactory)
	Set statsFactory.

	silenceForScope (string $type=self::EXPECTATION_ANY)
	Temporarily ignore expectations until the returned object goes out of scope.

	transactionWritingIn ( $server, $db, string $id, float $startTime)
	Mark a DB as in a transaction with one or more writes pending.

	transactionWritingOut ( $server, $db, string $id, float $writeTime, int $affected)
	Mark a DB as no longer in a transaction.

Public Attributes
const	EXPECTATION_ANY = 'any'
	Any type of expectation.

const	EXPECTATION_REPLICAS_ONLY = 'replicas-only'
	Any expectations about replica usage never occurring.

Detailed Description

Detect high-contention DB queries via profiling calls.

This class is meant to work with an IDatabase object, which manages queries.

Access: internal: For use by Database only

Since: 1.24

Definition at line 26 of file TransactionProfiler.php.

Constructor & Destructor Documentation

◆ __construct()

Wikimedia\Rdbms\TransactionProfiler::__construct ( )

Definition at line 93 of file TransactionProfiler.php.

References Wikimedia\Rdbms\TransactionProfiler\setLogger().

Member Function Documentation

◆ getExpectation()

Wikimedia\Rdbms\TransactionProfiler::getExpectation ( string $event )

Get the expectation associated with a specific event name.

This will return the value of the expectation even if the event is silenced.

Use this to check if a specific event is allowed before performing it, such as checking if the request will allow writes before performing them and instead deferring the writes to outside the request.

Since: 1.44

Parameters

string $event Event name. Valid event names are defined in {

See also: self::EVENT_NAMES}

Returns: float|int Maximum event count, event value, or total event value depending on the type of event.

Exceptions

InvalidArgumentException If the provided event name is not one in {

See also: self::EVENT_NAMES}

Definition at line 273 of file TransactionProfiler.php.

◆ isSilenced()

Wikimedia\Rdbms\TransactionProfiler::isSilenced ( string $event )

Check whether an event currently has its expectations silenced.

This method lets PHPUnit tests observe whether self::silenceForScope was called by the subject under test, and that it is still in-scope.

This returns true if self::silenceForScope was called, the returned ScopedCallback has not gone out of scope, and the expectation was zero (for self::EXPECTATION_REPLICAS_ONLY.

Access: internal: For use in PHPUnit tests

Parameters

string $event Event name, as defined in {

See also: self::EVENT_NAMES}

Returns: bool Whether the given event is currently ignoring expectations.

Exceptions

InvalidArgumentException If the event name is not one in {

See also: self::EVENT_NAMES}

Definition at line 178 of file TransactionProfiler.php.

◆ recordConnection()

Wikimedia\Rdbms\TransactionProfiler::recordConnection	(		$server,
			$db,
		bool	$isPrimaryWithReplicas )

Mark a DB as having been connected to with a new handle.

Note that there can be multiple connections to a single DB.

Parameters

string	$server	DB server
string \| null	$db	DB name
bool	$isPrimaryWithReplicas	If the server is the primary and there are replicas

Definition at line 290 of file TransactionProfiler.php.

◆ recordQueryCompletion()

Wikimedia\Rdbms\TransactionProfiler::recordQueryCompletion	(		$query,
		float	$sTime,
		bool	$isWrite,
		?int	$rowCount,
		string	$trxId,
		?string	$serverName = null )

Register the name and time of a method for slow DB trx detection.

This assumes that all queries are synchronous (non-overlapping)

Parameters

string \| GeneralizedSql	$query	Function name or generalized SQL
float	$sTime	Starting UNIX wall time
bool	$isWrite	Whether this is a write query
int \| null	$rowCount	Number of affected/read rows
string	$trxId	Transaction id
string \| null	$serverName	db host name like db1234

Definition at line 349 of file TransactionProfiler.php.

◆ redefineExpectations()

Wikimedia\Rdbms\TransactionProfiler::redefineExpectations	(	array	$expects,
		string	$fname )

Clear all expectations and hit counters and set new performance expectations.

Use this to apply a totally different set of expectations for a different part of the request, such as during "post-send" (execution after HTTP response completion)

Parameters

array $expects Map of (event name => limit), {

See also: self::EVENT_NAMES}

Parameters

string $fname

Since: 1.33

Definition at line 253 of file TransactionProfiler.php.

◆ resetExpectations()

Wikimedia\Rdbms\TransactionProfiler::resetExpectations ( )

Reset all performance expectations and hit counters.

Use this for unit testing or before applying a totally different set of expectations for a different part of the request, such as during "post-send" (execution after HTTP response completion)

Since: 1.25

Definition at line 239 of file TransactionProfiler.php.

◆ setExpectation()

Wikimedia\Rdbms\TransactionProfiler::setExpectation	(	string	$event,
			$limit,
		string	$fname )

Set performance expectations.

With conflicting expectations, the most narrow ones will be used

Parameters

string $event Event name, {

See also: self::EVENT_NAMES}

Parameters

float \| int	$limit	Maximum event count, event value, or total event value
string	$fname	Caller

Since: 1.25

Definition at line 199 of file TransactionProfiler.php.

◆ setExpectations()

Wikimedia\Rdbms\TransactionProfiler::setExpectations	(	array	$expects,
		string	$fname )

Set one or multiple performance expectations.

With conflicting expectations, the most narrow ones will be used

Use this to initialize expectations or make them stricter mid-request

Parameters

array $expects Map of (event name => limit), {

See also: self::EVENT_NAMES}

Parameters

string $fname

Since: 1.26

Definition at line 224 of file TransactionProfiler.php.

◆ setLogger()

Wikimedia\Rdbms\TransactionProfiler::setLogger ( LoggerInterface $logger )

Definition at line 105 of file TransactionProfiler.php.

Referenced by Wikimedia\Rdbms\TransactionProfiler\__construct().

◆ setMockTime()

Wikimedia\Rdbms\TransactionProfiler::setMockTime ( & $time )

Parameters

float | null &$time Mock UNIX timestamp for testing

Definition at line 606 of file TransactionProfiler.php.

◆ setRequestMethod()

Wikimedia\Rdbms\TransactionProfiler::setRequestMethod ( ?string $method )

Parameters

?string $method HTTP method; null for CLI mode

Returns: void

Definition at line 123 of file TransactionProfiler.php.

◆ setStatsFactory()

Wikimedia\Rdbms\TransactionProfiler::setStatsFactory ( StatsFactory $statsFactory )

Set statsFactory.

Parameters

StatsFactory $statsFactory

Returns: void

Definition at line 115 of file TransactionProfiler.php.

◆ silenceForScope()

Wikimedia\Rdbms\TransactionProfiler::silenceForScope ( string $type = self::EXPECTATION_ANY )

Temporarily ignore expectations until the returned object goes out of scope.

During this time, violation of expectations will not be logged and counters for expectations (e.g. "conns") will not be incremented.

This will suppress warnings about event counters which have a limit of zero. The main use case is too avoid warnings about primary connections/writes and warnings about getting any primary/replica connections at all.

Parameters

string $type Class EXPECTATION_* constant [default: TransactionProfiler::EXPECTATION_ANY]

Definition at line 140 of file TransactionProfiler.php.

◆ transactionWritingIn()

Wikimedia\Rdbms\TransactionProfiler::transactionWritingIn	(		$server,
			$db,
		string	$id,
		float	$startTime )

Mark a DB as in a transaction with one or more writes pending.

Note that there can be multiple connections to a single DB.

Parameters

string	$server	DB server
string \| null	$db	DB name
string	$id	ID string of transaction
float	$startTime	UNIX timestamp

Definition at line 320 of file TransactionProfiler.php.

◆ transactionWritingOut()

Wikimedia\Rdbms\TransactionProfiler::transactionWritingOut	(		$server,
			$db,
		string	$id,
		float	$writeTime,
		int	$affected )

Mark a DB as no longer in a transaction.

This will check if locks are possibly held for longer than needed and log any affected transactions to a special DB log. Note that there can be multiple connections to a single DB.

Parameters

string	$server	DB server
string \| null	$db	DB name
string	$id	ID string of transaction
float	$writeTime	Time spent in write queries
int	$affected	Number of rows affected by writes

Definition at line 423 of file TransactionProfiler.php.

Member Data Documentation

◆ EXPECTATION_ANY

const Wikimedia\Rdbms\TransactionProfiler::EXPECTATION_ANY = 'any'

Any type of expectation.

Definition at line 89 of file TransactionProfiler.php.

◆ EXPECTATION_REPLICAS_ONLY

const Wikimedia\Rdbms\TransactionProfiler::EXPECTATION_REPLICAS_ONLY = 'replicas-only'

Any expectations about replica usage never occurring.

Definition at line 91 of file TransactionProfiler.php.

The documentation for this class was generated from the following file:

includes/libs/Rdbms/TransactionProfiler.php

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ getExpectation()

◆ isSilenced()

◆ recordConnection()

◆ recordQueryCompletion()

◆ redefineExpectations()

◆ resetExpectations()

◆ setExpectation()

◆ setExpectations()

◆ setLogger()

◆ setMockTime()

◆ setRequestMethod()

◆ setStatsFactory()

◆ silenceForScope()

◆ transactionWritingIn()

◆ transactionWritingOut()

Member Data Documentation

◆ EXPECTATION_ANY

◆ EXPECTATION_REPLICAS_ONLY