Руководство:Параметр 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 или данные ПУБЛИКАЦИИ. Это целое число секунд. Например, this link показывает метаданные о странице «MediaWiki», если задержка не превышает 1 секунды, в то время как this (с-1 в конце) показывает фактическую задержку без метаданные.

Если указанное отставание превышено во время запроса, возвращается код состояния 503 (или 200 во время запросов API, см. задача 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": количество секунд задержки самой запаздывающей реплики

Рекомендуемое использование для Wikimedia wikis следующее:

• Используйте maxlag=5 (5 секунд). Это подходящее неагрессивное значение, установленное в качестве значения по умолчанию для Pywikibot. Более высокие значения означают более агрессивное поведение, более низкие значения лучше.
• Если вы получаете ошибку задержки, сделайте паузу в вашем скрипте как минимум на 5 секунд, прежде чем пытаться снова. Будьте осторожны, чтобы не войти в занятую петлю.
• Возможно, что с этим значением вы можете получить низкий коэффициент заполнения в периоды высокой загрузки базы данных. Ничего страшного, просто дайте ему подождать до пика. Мы даем людям приоритет во времена высокой нагрузки, потому что мы не хотим тратить их время, отказываясь от их правок.
• О необычно высокой или постоянной задержке следует сообщать в $irc-канал на IRC.
• В интерактивных задачах (где пользователь ожидает результата) может отсутствовать параметр maxlag. Неинтерактивные задачи всегда должны использовать его. См. также API:Этикет#Параметр maxlag.

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

• Заголовок X-Database-Lag отличается от ошибок задержки репликации в MediaWiki
• Нет ошибок Retry-After в Varnish
• Заголовок X-Squid-Error должен присутствовать в ошибках squid
• Тело ответа при ошибках задержки репликации будет соответствовать регулярному выражению $регулярное выражение

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