Посібник:Параметр Maxlag

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.

Якщо ви використовуєте MediaWiki в кластері реплікованих баз даних (наприклад, у Вікімедіа), то висока швидкість редагування може призвести до затримки серверів-реплік. Одним із способів зменшення затримки реплікації є автоматичне зупинення всіх ботів і завдань обслуговування щоразу, коли затримка перевищує певне значення. У MediaWiki 1.10 був представлений параметр maxlag, який дозволяє робити те саме в клієнтських сценаріях. Починаючи з версії 1.27, це стосується лише запитів api.php.

Параметр maxlag може передаватися до api.php через параметр URL або дані POST. Він задається цілим числом секунд. Наприклад, це посилання показує метадані про сторінку «MediaWiki», тільки якщо затримка перевищує 1 секунду, тоді як це (з -1 у кінці) показує фактичну затримку без метаданих.

Якщо під час запиту перевищено вказане відставання, API повертає помилку (з кодом статусу 200, див. завдання T33156) на кшталт:

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

Встановлено такі заголовки HTTP:

• Retry-After: рекомендована мінімальна кількість секунд, яку клієнт повинен почекати, перш ніж повторити спробу
• X-Database-Lag: кількість секунд затримки найбільш відсталої репліки

Рекомендоване використання для вікі Вікімедіа:

• Використовуйте maxlag=5 (5 секунд). Це відповідне неагресивне значення, встановлене як значення за замовчуванням у Pywikibot. Вищі значення означають агресивнішу поведінку, нижчі значення — прийнятнішу.
• Якщо ви отримали помилку затримки (lag error), призупиніть сценарій принаймні на 5 секунд, перш ніж повторити спробу. Будьте обережні, щоб не потрапити в цикл активного очікування.
• Можливо, що з цим значенням ви можете отримати повільний робочий цикл під час великого завантаження бази даних. Це нормально, просто перечекайте пік. Ми надаємо людям пріоритет під час великих навантажень, оскільки ми не хочемо тратити їхній час, відкидаючи їхні редагування.
• Про незвично високу або постійну затримку треба повідомити #wikimedia-tech ^connect на IRC.
• В інтерактивних завданнях (коли користувач чекає на результат) параметр maxlag може бути опущений. Неінтерактивні завдання завжди повинні його використовувати. Див. також API:Etiquette/uk#Параметр_maxlag.

Зауважте, що рівень кешування (Varnish або squid) також може генерувати повідомлення про помилки з кодом стану 503 через блокування за часом вищого сервера. Клієнти повинні по-різному ставитися до цих помилок, оскільки вони можуть виникати постійно, коли ви намагаєтесь виконати довготривалу затратну операцію. Повторення операції з тайм-аутом буде використовувати надмірні ресурси сервера і може залишити вашого клієнта в нескінченному циклі. Ви можете розрізняти помилки шару кешу та умови затримки MediaWiki, використовуючи будь-що з наведеного нижче:

• Заголовок X-Database-Lag відрізняється від помилок затримки реплікації в MediaWiki
• Немає помилок «Повторна спроба» в лаку
• Заголовок X-Squid-Error має бути присутнім у помилках squid
• Тіло відповіді в помилках затримки реплікації буде відповідати регулярному виразу /Waiting for [^ ]*: [0-9.-]+ seconds? lagged/

Для цілей тестування ви можете навмисно розробити програмне забезпечення, що відмовляється від запиту, передаючи від'ємне значення, наприклад, у такій URL-адресі: //www.mediawiki.org/w/api.php?action=query&titles=MediaWiki&format=json&maxlag=-1.