Příručka:Parametr Maxlag

maxlag je něco, co lze přidat do libovolného dotazu v Action API. Po nastavení se dotaz API zeptá serveru, zda je příliš zaneprázdněn. Pokud ano, dotaz API vrátí chybu namísto zpracování požadavku API. Chybová zpráva bude zahrnovat počet sekund za ní, a tyto informace lze použít k určení, jak dlouho čekáte před opakováním dotazu. Cílem je pozastavit operace robotů v době vysokého zatížení serveru, aby priorita lidských operací poskytla. Jedná se o volitelný, ale doporučený parametr a mnoho hlavních bot rámců, jako je pywikibot, jej implementují ve výchozím nastavení.

Pokud používáte MediaWiki na replikovaném databázovém klastru (jako je Wikimedie), pak vysoká míra provozu (zejména úpravy) mohou způsobit, že servery repliky zpožďují. Jedním ze způsobů, jak zmírnit zpoždění replikace, je automaticky zastavit všechny roboty a údržby, kdykoli zpoždění překročí určitou hodnotu. V MediaWiki 1.10 byl zaveden parametr maxlag, který umožňuje totéž provádět ve skriptech na straně klienta. Od 1.27 se vztahuje pouze na požadavky api.php.

Parametr maxlag může být předán na api.php pomocí parametru URL nebo údajů o POST. Je to celé číslo sekund. Například tento odkaz ukazuje metadata na stránce "MediaWiki", pokud není zpoždění větší než 1 sekunda, zatímco tento (s -1 na konci) vám ukazuje skutečné zpoždění bez metadat.

Pokud je zadané zpoždění překročeno v době požadavku, API vrátí chybu (se stavovým kódem 200, viz T33156) jako následující:

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

Jsou nastaveny následující záhlaví HTTP:

• Retry-After – doporučený minimální počet sekund, který by měl klient počkat před opakováním
• X-Database-Lag – počet sekund zpoždění nejvíce zaostávající repliky

Doporučené použití pro wikiny Wikimedie je následující:

• Použijte maxlag=5 (5 sekund). Toto je vhodná neagresivní hodnota, která je nastavena jako výchozí hodnota na Pywikibot. Vyšší hodnoty znamenají agresivnější chování, nižší hodnoty jsou hezčí.
• Pokud dostanete chybu zpoždění, pozastavte svůj skript po dobu nejméně 5 sekund, než to zkusíte znovu. Dávejte pozor, abyste nešli do rušné smyčky.
• Je možné, že s touto hodnotou můžete získat nízký cyklus v době vysokého načítání databáze. To je v pořádku, jen počkejte mimo vrchol. Dáváme lidem prioritu v době vysokého zatížení, protože nechceme ztrácet čas odmítnutím jejich úprav.
• Neobvykle vysoké nebo trvalé zpoždění by mělo být nahlášeno na #wikimedia-tech ^{připojit se} na IRC.
• Interaktivní úkoly (kde uživatel čeká na výsledek) mohou vynechat parametr maxlag. Neinteraktivní úkoly by jej měly vždy používat. Viz také API:Etiketa#Parametr Maxlag.

Všimněte si, že vrstva mezipaměti (Varnish nebo Squid ) může také generovat chybové zprávy se stavovým kódem 503 v důsledku časového limitu upstream serveru. Klienti by měli s těmito chybami zacházet jinak, protože se mohou vyskytnout důsledně, když se pokusíte provést dlouhodobý drahý provoz. Opakování operace na časovém limitu by použilo nadměrné zdroje serveru a může opustit vašeho klienta v nekonečné smyčce. Můžete rozlišovat mezi chybami mezipaměti a podmínkami zpoždění MediaWiki pomocí kterékoli z následujících:

• Hlavička X-Database-Lag je charakteristická pro chyby zpoždění replikace v MediaWiki
• Žádné Retry-After v chybách Varnish
• Záhlaví X-Squid-Error by mělo být přítomno v chybách Squid
• Tělo odpovědi v chybách zpoždění replikace bude odpovídat regexu /Waiting for [^ ]*: [0-9.-]+ seconds? lagged/

Pro účely testování můžete software úmyslně odmítnout žádost o předání záporné hodnoty, například v následující adrese URL: //www.mediawiki.org/w/api.php?action=query&titles=MediaWiki&format=json&maxlag=-1.