Manuel:Paramètre maxlag

This page is a translated version of the page Manual:Maxlag parameter and the translation is 100% complete.

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.

Si vous utilisez MediaWiki sur un cluster de base de données répliquée (tel que Wikimedia), alors un taux de modifications élevé peut se traduire par une latence sur les serveurs répliqués. Un moyen de limiter le ralentissement de réplication est d’avoir tous les robots et toutes les tâches de maintenance qui s’arrêtent automatiquement si le ralentissement dépasse une certaine valeur. Dans MediaWiki 1.10, le paramètre maxlag a été introduit. Il permet que la même chose soit faite dans les scripts du côté client. Depuis la 1.27, il ne s'applique qu'aux requêtes api.php.

Le paramètre maxlag peut être passé à api.php via un paramètre d’URL ou une donnée POST. Il s'agit d’un nombre entier de secondes. Par exemple, ce lien montre des métadonnées concernant la page « MediaWiki » à moins que la latence soit supérieure à 1 seconde tandis que celui-là (avec -1 à la fin) vous montre la latence actuelle sans métadonnées.

Si le ralentissement indiqué est dépassé au moment de la requête, l'API renvoie une erreur (avec le code d'état 200, voir tâche T33156) similaire à :

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

Les en-têtes HTTP suivants sont réglés :

  • Retry-After : un nombre minimum de secondes recommandé que le client doit attendre avant de réessayer ;
  • X-Database-Lag : nombre de secondes de latence du réplicat le plus ralenti.

L'usage recommandé pour les wikis de Wikimedia est le suivant :

  • Utiliser maxlag=5 (5 secondes). Il s’agit d’une valeur appropriée non-agressive, réglée par défaut pour Pywikibot. Des valeurs plus élevées induisent un comportement plus agressif, des valeurs plus faibles sont plus agréables.
  • Si vous obtenez une erreur de latence, mettez en pause votre script pour au moins 5 secondes avant de réessayer. Prenez soin de ne pas entrer dans une boucle d’occupation infinie.
  • Il est possible qu’avec cette valeur vous obteniez un court délai d’attente lorsque la base de données subit une forte activité. C’est normal, laissez la requête attendre simplement une baisse d’activité. En période de forte activité, nous donnons la priorité aux humains parce que nous ne voulons pas faire perdre leur temps en rejetant leurs modifications.
  • Une latence inhabituellement élevée ou persistante doit être signalée sur #wikimedia-tech connecter de IRC.
  • Les tâches interactives (où un utilisateur attend le résultat) peuvent omettre le paramètre maxlag. Les tâches non-interactives doivent toujours l'utiliser. Voir aussi le paramètre maxlag.

Notez qu’un serveur frontal de cache (Varnish ou squid) peut également générer des messages d’erreur avec un code de statut 503, à cause du dépassement de leur délai maximal d’attente d’un serveur en amont. Les clients doivent traiter ces erreurs différemment, parce qu’elles peuvent survenir de façon systématique lorsque vous tentez une opération intensive longue à s'exécuter. La répétition automatique de l’opération suite à un dépassement de délai provoquerait un usage excessif des ressources du serveur et pourrait conduire votre client à entrer dans une boucle d’attente infinie. Vous pouvez distinguer les erreurs provenant d’un frontal de cache et les conditions normales de latence de MediaWiki en utilisant un des moyens suivants :

  • l’en-tête X-Database-Lag est distinctif des erreurs de latence des réplications dans MediaWiki
  • l’en-tête Retry-After est absent dans les erreurs provenant d’un frontal Varnish
  • l’en-tête X-Squid-Error doit être présent dans les erreurs provenant d’un frontal squid
  • le corps de la réponse dans les messages d’erreur de latence de réplication vérifie l’expression régulière /Waiting for [^ ]*: [0-9.-]+ seconds? lagged/

Afin d’effectuer des tests, vous pouvez intentionnellement faire en sorte que le logiciel refuse d’exécuter une requête en passant une valeur négative, comme dans l’URL suivante : //www.mediawiki.org/w/api.php?action=query&titles=MediaWiki&format=json&maxlag=-1.