View source for Manual:Maxlag parameter

<languages />
<translate><!--T:1--> If you are running MediaWiki on a replicated database cluster (like Wikimedia is), then high edit rates may cause the replica servers to lag.</translate>
<translate><!--T:2--> One way to mitigate replication lag is to have all bots and maintenance tasks automatically stop whenever lag goes above a certain value.</translate>
<translate><!--T:3--> In MediaWiki 1.10, the maxlag parameter was introduced which allows the same thing to be done in client-side scripts.</translate>
<translate><!--T:26--> Since 1.27, it only applies to <tvar|api><code>api.php</code></> requests.</translate>

<translate><!--T:4--> The maxlag parameter can be passed to api.php through a URL parameter or POST data. It is an integer number of seconds.</translate>
<translate><!--T:5--> For example, [<tvar|maxlag-1>{{SERVER}}/w/api.php?action=query&titles=MediaWiki&format=json&maxlag=1</> this link] shows metadata about the page "MediaWiki" unless the lag is greater than 1 second while [<tvar|maxlag-2>{{SERVER}}/w/api.php?action=query&titles=MediaWiki&format=json&maxlag=-1</> this one] (with -1 at the end) shows you the actual lag without metadata.</translate>

<translate>
<!--T:6-->
If the specified lag is exceeded at the time of the request, the API returns an error (with 200 status code, see <tvar|1>{{task|T33156}}</>) like the following:
</translate>

<syntaxhighlight lang="php">
{
    "error": {
        "code": "maxlag",
        "info": "Waiting for $host: $lag seconds lagged",
        "host": $host,
        "lag": $lag,
        "*": "See https://www.mediawiki.org/w/api.php for API usage"
    }
}
</syntaxhighlight>

<translate>
<!--T:7-->
The following HTTP headers are set:

<!--T:9-->
* '''Retry-After''': a recommended minimum number of seconds that the client should wait before retrying</translate> 
<translate>
<!--T:10-->
* '''X-Database-Lag''': The number of seconds of lag of the most lagged replica

<!--T:11-->
Recommended usage for '''Wikimedia wikis''' is as follows:

<!--T:12-->
* Use maxlag=5 (5 seconds). This is an appropriate non-aggressive value, set as default value on [[<tvar|pywikibot>Special:MyLanguage/Pywikibot</>|Pywikibot]]. Higher values mean more aggressive behaviour, lower values are nicer.</translate>
<translate>
<!--T:13-->
* If you get a lag error, pause your script for at least 5 seconds before trying again. Be careful not to go into a busy loop.</translate>
<translate>
<!--T:14-->
* It's possible that with this value, you may get a low duty cycle at times of high database load. That's OK, just let it wait for off-peak. We give humans priority at times of high load because we don't want to waste their time by rejecting their edits.</translate>
<translate>
<!--T:15-->
* Unusually high or persistent lag should be reported to <tvar|irc-channel>{{irc|wikimedia-tech}}</> on [[<tvar|mw-irc>Special:MyLanguage/MediaWiki on IRC</>|IRC]].</translate>
<translate>
<!--T:27-->
* Interactive tasks (where a user is waiting for the result) may omit the maxlag parameter. Noninteractive tasks should always use it.</translate> <translate><!--T:28--> See also [[<tvar|1>Special:MyLanguage/API:Etiquette#The maxlag parameter</>|API:Etiquette#The maxlag parameter]].</translate>

<translate><!--T:16--> Note that the caching layer (Varnish or squid) may also generate error messages with a 503 status code, due to timeout of an upstream server.</translate>
<translate><!--T:17--> Clients should treat these errors differently, because they may occur consistently when you try to perform a long-running expensive operation.</translate>
<translate><!--T:18--> Repeating the operation on timeout would use excessive server resources and may leave your client in an infinite loop.</translate>
<translate><!--T:19--> You can distinguish between cache-layer errors and MediaWiki lag conditions using any of the following:</translate>

<translate>
<!--T:20-->
* X-Database-Lag header is distinctive to replication lag errors in MediaWiki</translate>
<translate>
<!--T:21-->
* No Retry-After in Varnish errors</translate>
<translate>
<!--T:22-->
* X-Squid-Error header should be present in squid errors</translate>
<translate>
<!--T:23-->
* The response body in replication lag errors will match the regex <tvar|regex><code>/Waiting for [^ ]*: [0-9.-]+ seconds? lagged/</code></>

<!--T:24-->
For testing purposes, you may intentionally make the software refuse a request by passing a negative value, such as in the following URL: [<tvar|maxlag>{{SERVER}}/w/api.php?action=query&titles=MediaWiki&format=json&maxlag=-1 {{SERVER}}/w/api.php?action=query&titles=MediaWiki&format=json&maxlag=-1</>].
</translate>

[[Category:MediaWiki development{{#translation:}}]]