Cet article décrit comment vous pouvez utiliser la fonctionnalité Custom Metrics (métriques personnalisées) pour capturer des données API. Il peut s’agir de l’API d’un partenaire technique que vous utilisez pour votre entreprise ou de votre propre API que vous avez créée pour le support de vos propres clients ou processus. Il peut même s’agir d’une API personnalisée que vous avez créée pour collecter ou exploiter des données commerciales internes ou d’une plate-forme. Les outils de test et les solutions de surveillance devraient être un élément essentiel des opérations de votre plate-forme afin de garantir le bon fonctionnement de vos API. Mais on peut faire bien plus pour mieux surveiller votre plateforme votre entreprise! Une surveillance personnalisée des données de l’API ne se contente pas de vérifier la disponibilité et d’effectuer la validation des données - elle capture les données produites par votre API et affiche la progression des données de la plateforme et de l’entreprise au fil du temps.
Un rappel sur la surveillance des API
Vous pouvez utiliser des outils de test tels que Postman, Insomnia, SoapUI ou Swagger UI pour tester vos API et inspecter les données pour les tests et le débogage ad hoc. Vous pouvez utiliser des outils de surveillance synthétiques (comme le API monitoring d’Uptrends) pour surveiller en continu la disponibilité et les temps de réponse. Et en plus - il vous faudrait configurer une validation de contenu approfondie de vos données JSON (à l’aide d’expressions JSON) ou XML (à l’aide de requêtes XPath) afin de vérifier que les données renvoyées par l’API répondent à vos attentes - sans erreurs et dans des limites acceptables. Cela permet de garantir que les processus qui dépendent de ces API continuent de fonctionner correctement et rapidement. Des processus comme vos applications mobiles, vos applications utilisateurs client ou vos processus métier de backend.
Suivi des données API
Imaginez que vous disposez d’une API REST d’un système de commerce électronique qui vend des produits. L’ensemble du catalogue de produits comprend plusieurs lignes de produits provenant de différents fournisseurs qui mettent à jour leur liste de produits plusieurs fois par jour. Vous avez des processus d’arrière-plan qui mettent à jour votre propre catalogue de produits dès que les mises à jour sont disponibles (en utilisant probablement l’API de vos fournisseurs également). Votre API produit est directement utilisée par votre boutique en ligne et votre application mobile.
Il est vital pour votre entreprise de vérifier que votre liste de produits contient le nombre attendu de produits et de catégories (au moins un certain minimum) . Vous avez probablement des rapports à ce sujet provenant de vos processus backend, mais le suivi basé sur vos données API vous permet d’obtenir les informations beaucoup plus rapidement.
C’est facile - vous pouvez créer un moniteur d’API multi-étapes (MSA) qui effectue un ou plusieurs appels à votre endpoint d’API de produit et qui renvoie des données au format JSON contenant le nombre total de produits, les catégories de produits et le nombre de produits dans chaque catégorie. Ajoutez quelques assertions pour les attributs individuels (prenons TotalProductCount et CategoryCount pour l’instant) et vérifiez que ces nombres ne dépassent pas leurs valeurs minimales. Par exemple, TotalProductCount doit toujours être supérieur à 1500 et CategoryCount doit être au moins 10. Ces assertions vous protégeront contre les échecs inaperçus de mise à jour de produit qui vident soudainement une grande partie de votre inventaire de produits. En cas d’incident, vous serez alerté par Uptrends et vous pourrez agir rapidement. Voilà qui répond à une partie de vos opérations quotidiennes.
Détecter les tendances des données
Mais vous pouvez faire encore plus avec ces données. Chaque contrôle individuel de moniteur vous dit que votre catalogue de produits est correct (ou non). Les quantités, pour les produits et les catégories, ont été validées lors de chaque vérification, mais vous ne voyez pas clairement quelles étaient les valeurs réelles. En fait, il serait intéressant de voir comment le nombre de produits varie au cours de la journée (des micro-changements) et au cours du mois et de l’année (macro-changements). Si le nombre de produits augmente plus rapidement que prévu, par exemple, cela pourrait indiquer que des vieux produits n’ont pas été supprimés de votre base de données, ce qui pourrait ralentir votre API et votre application mobile. Ceci est difficile à détecter à l’aide d’assertions simples - vous avez besoin d’une analyse des tendances !
Vous avez déjà défini la métrique TotalProductCount dans l’assertion MSA, il est donc très facile maintenant de commencer à collecter les données de métriques personnalisées. Voici comment !
Comment configurer la surveillance personnalisée d’API
Tout d’abord, il faut disposer d’une configuration de moniteur MSA fonctionnelle (qui peut être simple, pas nécessairement multi-étapes), comme indiqué dans la section précédente. Au moins une des étapes du moniteur MSA doit définir une variable qui capture une valeur numérique à partir de la réponse de l’API. Vous pouvez en savoir plus sur la création de variables dans les étapes de surveillance de l’API.
Une fois que vous avez au moins une variable dans l’une de vos étapes, allez vers le bas de la page à la section Mesures personnalisées. Là, vous remarquerez que les variables produites par votre moniteur MSA apparaissent dans la liste Nom de variable.
Ensuite il faut « promouvoir » cette variable vers une métrique personnalisée en lui donnant un nom sous Nom de la métrique. Ça peut être le même nom que la variable qui l’alimente, mais il peut être intéressant d’utiliser un nom plus parlant pour les rapports. Par exemple, si vous utilisez la variable TotalProductCount, un nom de métrique Nombre total de produits fonctionnerait probablement bien.
Vous pouvez ajouter jusqu’à 5 métriques personnalisées comme celle-ci dans un seul moniteur MSA. S’il vous en faut plus, contactez le support.
Enfin, enregistrez la définition de votre moniteur pour que la nouvelle métrique personnalisée commence à fonctionner !
Inspection des données et dépannage
Avant de commencer à configurer des graphiques et des tableaux, examinons d’abord nos nouvelles données. Accédez au journal du moniteur, localisez votre moniteur MSA et recherchez un résultat de vérification récent. Cliquez dessus pour ouvrir la fenêtre contextuelle des résultats de vérification.
Dans la section Vérifier les détails de la fenêtre popup, vous remarquerez que les valeurs de vos nouvelles métriques personnalisées apparaissent sous les résultats de l’étape. Cela vous donne un accès direct aux valeurs de métrique personnalisées individuelles, capturées lors de l’exécution du moniteur MSA.
Si vous ne voyez pas la valeur de métrique personnalisée à laquelle vous vous attendiez, il se peut que : - Vous avez accidentellement ouvert des résultats pour une vérification plus ancienne qui a été exécutée avant que la nouvelle métrique personnalisée n’ait été définie. - Votre nouvelle métrique personnalisée ne capture pas des données entières numériques. Si elle contient des données texte ou des nombres non entiers (tels que 99.9% ou 3.1415), la métrique personnalisée ne fonctionnera pas. Seuls les nombres entiers sont pris en charge pour le moment. Contactez-nous si vous souhaitez discuter de vos besoins. - Quelque chose s’est mal passé pendant l’exécution du moniteur MSA, alors la variable qui alimente votre métrique personnalisée peut ne pas avoir été créée du tout. Nos ingénieurs de support vous aideront à résoudre ces problèmes.
Création de rapports
Lorsque vous avez vérifié que votre nouvelle métrique personnalisée produit des résultats corrects, et vous avez collecté suffisamment de données, alors il est temps de créer un rapport qui montrera la progression des résultats de votre métrique. Pour cet exemple, créons un nouveau tableau de bord (plus d’informations sur la création de tableaux de bord). Pour ce faire, cliquez sur Tableaux de bord>Ajouter un tableau de bord. Cliquez sur l’une des tuiles vides et dans la fenêtre popup Ajouter une nouvelle tuile faites défiler vers le bas pour sélectionner la tuile Graphique de métriques personnalisées.
La nouvelle tuile n’affiche rien au début. Ouvrez les paramètres de la tuile et recherchez le moniteur qui contient la métrique personnalisée. Développez-le pour ajouter la métrique personnalisée à votre sélection. Remarquez que vous pouvez sélectionner plusieurs métriques personnalisées : elles seront affichées dans un graphique permettant de comparer leurs valeurs.
De même, vous pouvez utiliser la tuile contenant la liste des métriques personnalisées pour créer une grille qui affiche les valeurs numériques d’une ou plusieurs métriques personnalisées. Les valeurs affichées seront des valeurs moyennes.
Après avoir conçu votre tableau de bord, vous pouvez l’enregistrer, l’exporter et le planifier pour une livraison automatique par e-mail.
Inspection des données brutes
Les rapports que nous venons d’examiner serviront à visualiser les tendances des données. Mais vous voudrez peut-être creuser plus profondément et travailler avec les données sous-jacentes. Avec un accès à chaque valeur de métrique individuelle capturée, vous pouvez détecter des valeurs instantanées plus précisément, effectuer des analyses min max/médiane, etc.
Pour ce faire, il faut télécharger un fichier d’exportation (Excel) contenant toutes les métriques capturées. Tout d’abord, accédez au tableau de bord du journal du moniteur pour sélectionner le ou les moniteurs appropriés. Ensuite, ouvrez les paramètres pour la tuile de journal du moniteur. Dans l’onglet Exporter, il faut cochez la case Mesures personnalisées. Cliquez sur Définir pour confirmer vos paramètres.
Enfin, utilisez le menu du tableau de bord (icône hamburger) pour démarrer le processus d’exportation Excel (directement ou par e-mail). Dans le fichier Excel, vous verrez des colonnes distinctes pour chaque métrique personnalisée qui a été capturée pour vos moniteurs.
Donner un nom aux métriques personnalisées
Lorsque vous créez une nouvelle métrique personnalisée, il est recommandé d’utiliser un nom facile à lire dans vos rapports. Le nom de la métrique, combiné avec le nom du moniteur dont il fait partie, apparaîtra dans la liste des métriques personnalisées disponibles lorsque vous l’ajoutez à votre rapport de données d’API personnalisé.
Si vous comptez créer plusieurs métriques personnalisées qui capturent le même type de données, c’est-à-dire la même métrique mais associée à un groupe (ou produit, client, etc.) différent, il est logique de leur donner exactement le même nom. Vous pourrez toujours les différencier en raison des différents noms de moniteur.
Lorsque vous créez des métriques personnalisées, il est mieux de lui donner immédiatement le bon nom. Vous pouvez toujours modifier le nom d’une métrique plus tard, mais gardez à l’esprit qu’elle sera traitée comme une métrique différente après être renommée : la métrique est identifiée de manière unique par son nom.