Manuel:Paramètre maxlag

maxlag est une notion que vous pouvez ajouter à n'importe quelle requête à l'API Action. Lorsqu'elle est positionnée, la requête à l'API va demander au serveur s'il est trop occupé. Si c'est le cas, elle renverra une erreur au lieu de traiter la requête. Le message d'erreur comprendra le nombre de secondes d'indisponibilté, et cette information pourra être utilisée pour déterminer combien de temps il faudra attendre avant de retenter l'opération. L'idée est de suspendre les modifications initiées par les robots pendant les périodes de grande charge du serveur, afin de donner la priorité aux modifications humaines. C'est un paramètre facultatif mais recommandé et beaucoup d'environnements majeurs où il y a des robots tels que pywikibot, l'implémentent par défaut.

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 (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.