Outil de monitoring d’API : disponibilité, temps de réponse et validation depuis 300+ emplacements

La surveillance d’API REST ressemble superficiellement à la surveillance de disponibilité, mais c’est un métier différent. Une API est consommée par du code, pas par des personnes, et le code est intransigeant d’une façon qu’un navigateur ne l’est pas. Un visiteur humain tolère une page qui s’affiche un peu de travers ; une intégration qui reçoit un champ du mauvais type casse tout simplement. La surveillance d’API doit donc vérifier plus de couches que « le serveur a-t-il répondu », et HostTracker les vérifie dans l’ordre, en échouant à la première qui ne tient pas.

Les couches un à trois sont ce que fournit une vérification de disponibilité ordinaire. Les couches quatre et cinq sont ce qui en fait de la surveillance d’API - et ce sont les couches où vivent réellement la plupart des incidents d’API.

Avant que quoi que ce soit puisse être validé, le moniteur doit effectuer la requête que votre API attend. La surface de requête complète est disponible sur un moniteur d’API :

La façon la plus expressive de valider une réponse consiste à écrire des règles pour elle. Chaque règle tient sur une ligne, les règles se combinent avec ET, et un moniteur peut en porter jusqu’à vingt. Voici le socle de départ vérifié pour une API JSON :

status isOk
header("Content-Type") contains "json"
body.json.path("$.count") gt 0
time lt 5s

Quatre lignes, qui couvrent à elles quatre les couches qui comptent : l’endpoint a répondu avec un 2xx, il a répondu en JSON plutôt qu’avec une page d’erreur, le payload contient un vrai résultat plutôt qu’un résultat vide, et tout cela dans le budget de temps imparti. Parmi les règles utiles individuellement issues du même catalogue : body.json.path("$.status") eq "ok" pour le verdict de santé propre à une API, body.json.path("$.error") absent pour un membre d’erreur apparaissant dans une réponse par ailleurs réussie, body.json.path("$.version") eq "2.4.1" pour détecter un retour en arrière involontaire, redirects.count eq 0 pour un endpoint qui doit répondre directement, et cert.days.left gt 14 pour le certificat sur la même connexion.

De quoi une règle peut parler

Les règles lisent des sujets dans la réponse et les comparent. Ces sujets couvrent le code de statut ; le temps de réponse total et ses composantes connexion, TLS, DNS, en-têtes et corps ; le corps brut ainsi que sa taille et un hachage de celui-ci ; des requêtes structurées dans le payload en JSON, XML, HTML ou YAML ; les en-têtes de réponse pris individuellement ; l’URL finale et l’URL d’origine et leurs composantes ; la chaîne de redirection, saut par saut ; les jours restants du certificat, son émetteur et ses noms ; le protocole TLS et le chiffrement négociés ; les adresses renvoyées par le DNS ; et Set-Cookie. Les comparaisons vont de l’évident - égal, inférieur à, supérieur à - jusqu’à contains, startsWith, endsWith, matches pour une expression régulière, containsAny et containsAll pour un ensemble, in pour une liste de valeurs acceptables, et exists, isNumber et unique.

Il existe aussi un axe de détection de changement : une règle peut comparer la valeur de cette exécution à celle de la précédente, ce qui permet de vérifier qu’un compteur ne recule jamais ou qu’un hachage du corps n’a pas changé - le type de règle qui détecte un retour en arrière silencieux ou une modification de contenu non autorisée, plutôt qu’une panne.

À côté du langage de règles existe un chemin plus simple, à valeur unique, présent depuis longtemps dans la surveillance d’API ici et qui suffit souvent à une vérification. Vous indiquez au moniteur comment analyser le corps, comment y sélectionner une valeur, et ce que cette valeur doit être :

• Analyser en JSON, et le sélecteur est une expression JSONPath.
• Analyser en XML, et le sélecteur est une expression XPath - ce qui rend simple la vérification de SOAP et des autres services XML.
• Le traiter comme du texte brut, et le sélecteur est une expression régulière multiligne et insensible à la casse.

Le prédicat appliqué à la valeur sélectionnée couvre égal et différent, inférieur et supérieur sous forme stricte ou inclusive, l’appartenance à une liste de valeurs acceptables ou son exclusion, l’appartenance à une plage numérique ou son exclusion, et un test pour vérifier que la valeur est nulle ou totalement absente.

Chaque panne de ce tableau renvoie un HTTP 200. C’est là tout le problème de surveiller une API sur son seul code de statut : le transport a réussi, donc le transport rapporte un succès.

Cette dernière ligne mérite d’être mise en place délibérément. Un second moniteur qui n’envoie aucun identifiant et vérifie un 401 est le moyen le moins coûteux de découvrir qu’une couche d’autorisation a été accidentellement désactivée - une panne qu’aucune quantité de tests positifs ne fera jamais apparaître.

Les moniteurs d’API s’exécutent depuis le parc public de points de contrôle de HostTracker - plus de 300 points de contrôle répartis dans 158 villes - et vous choisissez les emplacements utilisés par un moniteur donné. La géographie compte davantage pour une API que pour un site web : un endpoint desservi par un CDN ou un équilibreur de charge géo-routé peut être sain à Francfort et en échec à São Paulo, et une vérification depuis un seul emplacement n’a aucun moyen de le voir. Il en va de même pour le DNS - un enregistrement périmé ou mal configuré se propage souvent de façon inégale, ce qui ressemble à une panne intermittente de l’intérieur et à une panne régionale de l’extérieur.

S’exécuter depuis de nombreux endroits soulève un risque évident : plus de points de contrôle, plus d’occasions pour un chemin réseau instable de crier au loup. HostTracker gère cela avec un quorum de confirmation. Lorsqu’un point de contrôle signale un échec, la vérification est répétée depuis d’autres points de contrôle indépendants, et le changement d’état n’est confirmé que lorsqu’ils sont d’accord - par défaut, un verdict majoritaire parmi jusqu’à sept agents, avec un minimum de trois. Vous pouvez rendre cela plus strict, en exigeant qu’un nombre défini d’agents signale l’échec ou un accord complet entre eux, pour un endpoint où une fausse alerte est pire qu’une alerte lente.

Une fois confirmée, l’alerte suit le délai choisi par chaque contact - immédiatement, ou après 3, 5, 15, 30 ou 60 minutes, ou 3, 6, 12 ou 24 heures d’échec continu - sur les neuf canaux de notification : e-mail, SMS, appel vocal, webhook, Slack, notification push et les messageries Telegram, Discord et Viber. Le canal webhook est ce qui permet aux alertes d’atteindre un outil de gestion d’incidents ou de discussion d’équipe.

La vérification est une requête HTTP configurable associée à une analyse de la réponse, ce à quoi elle s’adapte en découle directement.

• Les API REST et JSON sont le cas de tous les jours, et la surveillance d’API REST est ce que la plupart des comptes configurent en premier : un GET ou un POST, des en-têtes pour l’identifiant, et des règles JSONPath ou d’assertion sur le payload.
• GraphQL fonctionne comme un POST avec la requête dans le corps, puis un JSONPath dans data - et il vaut la peine de vérifier que le membre errors est absent, puisque GraphQL est connu pour répondre 200 avec des erreurs à l’intérieur.
• Les services SOAP et XML sont un POST avec l’enveloppe comme corps et XPath comme sélecteur, ce qui accède à la réponse exactement comme le prévoit la spécification.
• Les récepteurs de webhooks et endpoints de rappel peuvent être vérifiés pour leur joignabilité et pour la réponse qu’ils donnent à une requête bien formée - précieux, car un récepteur qui a discrètement cessé d’accepter les livraisons ne produit aucune erreur nulle part dans votre propre système.
• Les endpoints de santé et de disponibilité (health/readiness) sont la cible la plus précieuse de toutes si vous en avez : votre application sait déjà si ses dépendances sont saines, et une assertion sur ce verdict transforme sa propre connaissance en alerte.

Ce qui ne convient pas, c’est une séquence - obtenir un jeton, l’utiliser, puis supprimer la ressource. Un moniteur d’API effectue une seule requête par exécution. Pour un véritable parcours en plusieurs étapes, la vérification transactionnelle pilotée par navigateur est l’outil adapté ; pour le temps de chargement d’une page plutôt que d’un endpoint, voir le suivi du temps d’accès navigateur et de chargement des pages.

1. Testez d’abord l’endpoint avec la vérification HTTP instantanée gratuite - sans connexion requise - afin de voir le statut, le chronométrage et la réponse contre lesquels vous êtes sur le point d’écrire des règles.
2. Ajoutez un moniteur et choisissez le type surveillance d’API. Définissez la méthode, et ajoutez les en-têtes ou le corps dont l’endpoint a besoin ; attribuez au moniteur son propre identifiant plutôt que de réutiliser celui d’une personne.
3. Écrivez les assertions. Commencez avec le socle de quatre lignes ci-dessus - statut, type de contenu, une valeur significative du payload, et un budget de temps de réponse - qui constitue un très bon point de départ par défaut pour presque toute API JSON.
4. Choisissez un intervalle entre une minute et 24 heures. Trois minutes est la valeur par défaut et un point de départ raisonnable ; réservez une minute aux endpoints dont la panne constitue un incident.
5. Choisissez les emplacements. Deux ou trois régions où vivent réellement vos consommateurs valent mieux qu’une seule, et c’est ce qui rend visible une panne régionale.
6. Ajoutez les contacts, et définissez le délai d’alerte de chacun. Tout le monde n’a pas besoin d’être informé dès la première minute.
7. Laissez tourner pendant une journée, puis consultez l’historique des temps de réponse avant de resserrer la règle de chronométrage. Un budget défini à partir de données réelles tient ; un budget défini au hasard finit par être mis en sourdine.

Ces deux approches se complètent et sont fréquemment confondues. Une plateforme d’observabilité ou d’APM instrumente votre code et vous indique ce qui s’est passé à l’intérieur d’une requête. La surveillance d’API externe se tient en dehors de votre infrastructure et vous indique ce que reçoit réellement un consommateur. Les deux méritent d’être mises en place ; aucune ne remplace l’autre.

Le schéma sur lequel se stabilisent la plupart des équipes est la surveillance externe pour la détection et la télémétrie interne pour le diagnostic : HostTracker vous indique qu’un endpoint est cassé, depuis où, et contre quelle règle, et votre propre traçage vous indique pourquoi. À côté de cela, un moniteur de requêtes de base de données explique souvent une API devenue lente, et la surveillance de la charge serveur explique l’hôte sur lequel elle tourne.

• Une seule requête par exécution. Pas d’échange de jeton, pas d’appels enchaînés. Pointez le moniteur vers un endpoint dont l’authentification n’expire pas, et utilisez une vérification transactionnelle lorsque ce que vous devez prouver est une séquence.
• Vingt règles d’assertion par moniteur. Amplement suffisant en pratique - le socle de quatre lignes couvre la plupart des endpoints - mais bon à savoir avant de planifier un test de contrat à cent règles.
• Le mode assertion remplace les anciens réglages de mot-clé et de statut. Les deux modèles ne peuvent pas être combinés sur un même moniteur ; choisissez le langage de règles ou l’ancien mode mot-clé, pas les deux.
• Pas de validation OpenAPI ou JSON-schema. Vous vérifiez des valeurs et des structures spécifiques, pas un document de schéma entier.
• Le corps de la requête a une limite de longueur, un très gros payload POST n’est donc pas la forme pour laquelle cette vérification est conçue.
• C’est de la surveillance, pas des tests. La bonne cible est un endpoint en lecture seule ou idempotent. Un moniteur qui modifie des données toutes les trois minutes depuis plusieurs emplacements finira par être la cause d’un incident plutôt que ce qui en détecte un.