Handbuch:Maxlag-Parameter

maxlag is something that can be added to any Action API query. When set, the API query will ask the server if it is too busy. If it is, the API query will return an error instead of processing the API request. The error message will include the number of seconds behind it is, and this information can be used to determine how long to wait before retrying the query. The idea is to pause bot edits during times of high server load, to give human edits priority. This is an optional but recommended parameter, and many major bot frameworks such as pywikibot implement it by default.

Wenn du MediaWiki auf einem replizierten Datenbankcluster (wie Wikimedia) betreibst, können hohe Bearbeitungsraten zu Verzögerungen beim Replikatserver führen. Eine Möglichkeit, um dies zu minimieren, ist alle Bots und Wartungstätigkeiten automatisch zu stoppen, wenn die Verzögerung einen bestimmten Wert übersteigt. In MediaWiki 1.10 wurde der Maxlag-Parameter eingeführt, der dies für Client-seitige Skripte ermöglicht. In 1.27 wurde es aktualisiert und funktioniert nur für api.php-Abfragen.

Der Maxlag-Parameter kann über einen URL-Parameter oder über POST-Daten an api.php übergeben werden. Er ist eine ganze Zahl in Sekunden. Beispielsweise zeigt dieser Link Metadaten über die Seite "MediaWiki", es sei denn die Verzögerung ist größer als 1 Sekunde, während dieser (mit -1 am Ende) dir die aktuelle Verzögerung ohne Metadaten anzeigt.

Wenn die angegebene Verzögerung zum Zeitpunkt deiner Abfrage überstiegen wird, wird ein Statuscode 503 ausgegeben (oder 200 während API-Abfragen, siehe task T33156), der das folgende Format besitzt:

{
    "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"
    }
}

Die folgenden HTTP-Header sind gesetzt:

• Retry-After: eine empfohlene minimale Anzahl von Sekunden, die der Client abwarten soll, bevor er erneut versucht, die Abfrage auszuführen
• X-Database-Lag: Die Verzögerung in Sekunden des am stärksten verzögerten Replikats

Die folgende Nutzung wird für Wikimedia-Wikis empfohlen:

• Nutze maxlag=5 (5 Sekunden). Dies ist ein angemessener nicht aggressiver Wert, der als Standardwert im Pywikibot gesetzt ist. Höhere Werte bedeuten ein aggressiveres Verhalten, niedrige Werte sind freundlicher.
• Pausiere dein Skript für mindestens 5 Sekunden, wenn du einen Fehler aufgrund einer Verzögerung erhältst, ehe du es erneut versuchst. Achte darauf, nicht in eine besetzte Schleife zu geraten.
• Es ist möglich, dass du mit diesem Wert bei hoher Datenbankauslastung nur einen langsamen Arbeitszyklus erreichst. Das ist in Ordnung, warte einfach auf Zeiten, in denen die Auslastung niedriger ist. Wir geben Menschen Priorität, wenn die Auslastung hoch ist, da wir ihre Zeit nicht verschwenden wollen, indem wir ihre Bearbeitungen ablehnen.

• Ungewöhnlich hohe oder anhaltende Verzögerungen sollten in #wikimedia-tech ^connect auf irc.freenode.net gemeldet werden.

• Interaktive Aufgaben (bei denen ein Benutzer auf das Ergebnis wartet) können auf den Maxlag-Parameter verzichten. Nicht interaktive Aufgaben sollten ihn immer nutzen. Siehe auch API:Etikette#Der Parameter maxlag.

See also API:Etiquette#The maxlag parameter.

Beachte, dass auch Caching-Layer (Varnish oder Squid) aufgrund eines Timeouts des Upstream-Servers eine Fehlermeldung mit einem Statuscode 503 generieren können. Clients sollten diese Fehler unterschiedlich behandeln, da sie dauerhaft auftreten können, wenn du versuchst, umfangreiche und lange andauernde Befehle auszuführen. Das Wiederholen des Befehls, der ein Timeout verursacht hat, würde zu einer starken Ausnutzung der Server-Ressourcen führen und könnte deinen Client in eine Endlosschleife laufen lassen. Du kannst auf folgende Arten zwischen Caching-Layer-Fehlern und MediaWiki-Verzögerungen unterscheiden:

• Der X-Database-Lag-Header ist charakteristisch für Replikationsverzögerungs-Fehler in MediaWiki
• Bei Varnish-Fehlern gibt es kein Retry-After
• Bei Squid-Fehlern sollte der X-Squid-Error-Header vorhanden sein
• Der Antwortkörper bei Replikationsverzögerungs-Fehlern passt zum regulären Ausdruck /Waiting for [^ ]*: [0-9.-]+ seconds? lagged/

Für Testzwecke kannst du die Software absichtlich dazu bringen, eine Abfrage abzulehnen, indem du einen negativen Wert übergibst, wie in der folgenden URL: //www.mediawiki.org/w/api.php?action=query&titles=MediaWiki&format=json&maxlag=-1.