Tests API
Rapport de recherche Datadog : Bilan sur l'adoption de l'informatique sans serveur Rapport : Bilan sur l'adoption de l'informatique sans serveur

Tests API

Présentation

Les tests API vous permettent de surveiller vos endpoints d’API et de recevoir des alertes en cas d’échec ou de lenteur excessive. Ces tests vérifient que vos applications répondent aux requêtes et respectent les conditions que vous avez définies, comme le temps de réponse, le code de statut HTTP, ainsi que les contenus de l’en-tête et du corps de message. Utilisez l’API Datadog pour voir la liste complète.

Configuration

La configuration des tests API dépend du type de test API que vous souhaitez créer : un test HTTP, un test SSL, un test TCP ou un test DNS.

Créer une requête

Définissez la requête HTTP, SSL, TCP ou DNS que vous souhaitez que Datadog exécute :

Définissez la requête que vous souhaitez que Datadog exécute :

  1. Choose a request type : HTTP.
  2. Choisissez la Method et l’URL à interroger. Les méthodes disponibles sont les suivantes : GET, POST, PATCH, PUT, HEAD, DELETE et OPTIONS.
  3. Ajoutez des Advanced Options (facultatif) à votre test :
  • Follow redirects : activez cette fonction pour que l’endpoint surveillé suive jusqu’à dix redirections.
  • Allow insecure server certificates : activez cette fonction pour que votre test HTTP poursuive son processus de connexion même lorsqu’une erreur de validation du certificat survient.
  • Client certificate : authentifiez-vous via mTLS en important votre certificat client et la clé privée associée.
  • Request headers : les en-têtes définis remplacent les en-têtes par défaut du navigateur. Par exemple, vous pouvez définir le user-agent dans l’en-tête de façon à identifier les scripts Datadog.
  • Cookies : les cookies définis sont ajoutés aux cookies de navigateur par défaut. Définissez plusieurs cookies en suivant le format <COOKIE_NOM1>=<COOKIE_VALEUR1>; <COOKIE_NOM2>=<COOKIE_VALEUR2>.
  • HTTP Basic Auth : authentification HTTP de base avec nom d’utilisateur et mot de passe.
  • Request body : corps de la requête et type de corps (text/plain, application/json, text/xml, text/html ou None). Remarque : la taille du corps de la requête est limitée à 50 Ko.
  • Proxy URL : URL du proxy à utiliser par la requête HTTP (http://<VOTRE_UTILISATEUR>:<VOTRE_MOT_DE_PASSE>@<VOTRE_IP>:<VOTRE_PORT>).
  • Proxy Header : en-têtes à inclure dans la requête HTTP envoyée au proxy.
  1. Name : le nom de votre test API.
  2. Select your tags : les tags à appliquer à votre test Browser. Utilisez le format <KEY>:<VALUE> pour filtrer une valeur <VALUE> pour une clé <KEY> donnée sur la page Synthetic Monitoring.
  3. Locations : les sites gérés par Datadog à partir desquels le test doit être exécuté. De nombreux sites AWS répartis dans le monde entier sont disponibles. Vous pouvez récupérer la liste complète via l’API Datadog. Vous pouvez également configurer un site privé pour lancer un test API Synthetic sur un endpoint privé qui n’est pas accessible à partir de l’Internet public.
  4. How often should we run the test? : utilisez cette option pour définir la fréquence d’exécution du test. Cette fréquence peut aller d’une fois par minute à une fois par semaine.
  5. Cliquez sur Test URL pour essayer la configuration de requête. Un aperçu de la réponse devrait s’afficher sur le côté droit de votre écran.
  1. Choose a request type : SSL.
  2. Précisez le Host et le Port SSL. Par défaut, le port est défini sur 443.
  3. Ajoutez des Advanced Options (facultatif) à votre test :
  • Accept self-signed certificates : ignorez les erreurs liées au certificat auto-signé.
  • Client certificate : authentifiez-vous via mTLS en important votre certificat client et la clé privée associée.
  1. Name : le nom de votre test SSL.
  2. Select your tags : les tags à appliquer à votre test SSL. Utilisez le format <KEY>:<VALUE> pour filtrer une valeur <VALUE> pour une clé <KEY> donnée sur la page Synthetic Monitoring.
  3. Locations : les emplacements gérés par Datadog à partir desquels le test doit être exécuté. De nombreux emplacements AWS répartis dans le monde entier sont disponibles. Vous pouvez récupérer la liste complète via l’API Datadog. Vous pouvez également configurer un emplacement privé pour lancer votre test SSL Synthetic sur un host privé qui n’est pas accessible à partir de l’Internet public.
  4. How often should we run the test? : utilisez cette option pour définir la fréquence d’exécution du test. Cette fréquence peut aller d’une fois par minute à une fois par semaine.
  5. Cliquez sur Test Connection pour essayer la configuration de requête. Un aperçu de la réponse devrait s’afficher sur le côté droit de votre écran.
  1. Choose a request type : TCP.
  2. Précisez le Host et le Port TCP.
  3. Name : le nom de votre test TCP.
  4. Select your tags : les tags à appliquer à votre test TCP. Utilisez le format <KEY>:<VALUE> pour filtrer une valeur <VALUE> pour une clé <KEY> donnée sur la page Synthetic Monitoring.
  5. Locations : les emplacements gérés par Datadog à partir desquels le test doit être exécuté. De nombreux emplacements AWS répartis dans le monde entier sont disponibles. Vous pouvez récupérer la liste complète via l’API Datadog. Vous pouvez également configurer un emplacement privé pour lancer votre test TCP Synthetic sur un host ou un port privé qui n’est pas accessible à partir de l’Internet public.
  6. How often should we run the test? : utilisez cette option pour définir la fréquence d’exécution du test. Cette fréquence peut aller d’une fois par minute à une fois par semaine.
  7. Cliquez sur Test URL pour essayer la configuration de requête et voir un aperçu de la réponse à droite.
  1. Choose a request type : DNS.
  2. Précisez le Domain et l’éventuel DNS Server à utiliser.
  3. Name : le nom de votre test DNS.
  4. Select your tags : les tags à appliquer à votre test DNS. Utilisez le format <KEY>:<VALUE> pour filtrer une valeur <VALUE> pour une clé <KEY> donnée sur la page Synthetic Monitoring.
  5. Locations : les emplacements gérés par Datadog à partir desquels le test doit être exécuté. De nombreux emplacements AWS répartis dans le monde entier sont disponibles. Vous pouvez récupérer la liste complète via l’API Datadog. Vous pouvez également configurer un emplacements privé pour lancer un test DNS Synthetic sur un domaine privé qui ne peut pas être résolu à partir de l’Internet public.
  6. How often should we run the test? : utilisez cette option pour définir la fréquence d’exécution du test. Cette fréquence peut aller d’une fois par minute à une fois par semaine.
  7. Cliquez sur Test URL pour essayer la configuration de requête et voir un aperçu de la réponse à droite.

Assertions

Lorsque vous exécutez un test API, vous devez définir au moins une assertion gérée par Datadog. Une assertion est définie par un paramètre, une propriété facultative, un comparateur et une valeur cible.

TypeOpérateurType de valeur
bodycontains, does not contain, is, is not,
matches, does not match,
jsonpath
Chaîne
Regex
Chaîne, Regex
headercontains, does not contain, is, is not,
matches, does not match
Chaîne
Regex
response timeis less thanNombre entier (ms)
status codeis, is notNombre entier

Remarque : les tests HTTP peuvent décompresser les corps de réponse contenant les en-têtes content-encoding suivants : br, deflate, gzip et identity.

Si vous cliquez sur Test URL, les assertions de base sont automatiquement renseignées :

  • response time is less than 1000 ms
  • status code is « valeur renvoyée »
  • header content-type is « valeur renvoyée »
TypeOpérateurType de valeur
certificateexpires in more than, expires in less thanNombre entier (nombre de jours)
propertycontains, does not contain, is, is not,
matches, does not match
Chaîne
Regex
response timeis less thanNombre entier (ms)
TLS versionis less than, is less than or equal, is, is more than, is more than or equalNombre décimal

Si vous cliquez sur Test URL, l’assertion de base est automatiquement renseignée :

  • certificate expires in more than 10 days
  • response time is less than 1000 ms.
TypeOpérateurType de valeur
response timeis less thanNombre entier (ms)

Si vous cliquez sur Test URL, l’assertion de base est automatiquement renseignée :

  • response time is less than 1000 ms.
TypeType d’enregistrementOpérateurType de valeur
response timeis less thanNombre entier (ms)
every recordof type A, of type AAAAis, contains,
matches, does not match
Chaîne
Regex
at least one recordof type A, of type AAAAis, contains,
matches, does not match
Chaîne
Regex

Si vous cliquez sur Test URL, les assertions de base sont automatiquement renseignées :

  • response time is less than 1 000 ms
  • at least one record of type A is « valeur renvoyée » (le cas échéant)
  • at least one record of type AAAA is « valeur renvoyée » (le cas échéant)

Vous pouvez créer jusqu’à 10 assertions par test API en cliquant sur Add new assertion ou en cliquant directement sur l’aperçu de la réponse :

Conditions d’alerte

Définissez des conditions d’alerte afin de spécifier les circonstances dans lesquelles vous souhaitez qu’un test échoue et déclenche une alerte.

Règle d’alerte

Lorsque vous définissez les conditions d’alerte sur : An alert is triggered if any assertion fails for X minutes from any n of N locations, une alerte se déclenche si :

  • Au moins un emplacement était en échec (au moins une assertion a échoué) au cours des X dernières minutes, et
  • À un moment au cours des X dernières minutes, au moins n emplacements étaient en échec.

La barre d’uptime s’affiche différemment sur vos résultats de test : l’uptime d’un site est affiché pour chaque évaluation (quels que soient les résultats du dernier test). L’uptime total est affiché selon les conditions d’alerte configurées. Les notifications envoyées se basent sur la barre d’uptime total.

Nouvelle tentative rapide

Vous pouvez choisir le nombre de tentatives à effectuer avant qu’un site soit considéré comme en échec. Par défaut, les tests Synthetic n’effectuent aucune nouvelle tentative après un échec pour un emplacement donné.

Utiliser des variables globales

Les variables globales définies sur la page Settings peuvent être utilisées dans l’URL, les options avancées et les assertions de vos tests API. Pour afficher la liste de vos variables, saisissez {{ dans le champ souhaité.

Informer votre équipe

Une notification est envoyée selon les conditions d’alerte définies. Pour configurer les notifications :

  1. Sélectionnez les utilisateurs et/ou les services qui recevront les notifications. Remarque : tout comme pour les monitors, la fonctionnalité @-notifications peut être utilisée dans le champ message.

  2. Saisissez un message pour le test API. Ce champ accepte l’utilisation du format de mise en forme Markdown standard ainsi que les variables conditionnelles suivantes :

    Variable conditionnelleDescription
    {{#is_alert}}Afficher en cas d’alerte du monitor
    {{^is_alert}}Afficher sauf en cas d’alerte du monitor
    {{#is_recovery}}Afficher lorsque le monitor est rétabli depuis un état ALERT
    {{^is_recovery}}Afficher sauf si le monitor est rétabli depuis un état ALERT

    Les messages de notification comprennent le message défini dans cette section ainsi que des informations sur les assertions qui ont échoué et les raisons de cet échec.

  3. Indiquez une fréquence de renvoi de notifications. Pour éviter de renvoyer des notifications pour les tests qui ont échoué, choisissez l’option Never renotify if the monitor has not been resolved.

  4. Cliquez sur Save.

Exemples de notifications :

Calculs de temps des opérations réseau

La page de détails Synthetic présente les calculs de temps suivants :

TempsDescription
DNSTemps passé à résoudre le nom DNS de la dernière requête.
ConnectTemps passé à établir une connexion au serveur.
SSLTemps passé à établir la liaison TLS. Si la dernière requête ne suit pas le protocole HTTPS, cette métrique n’apparaît pas.
TTFB (time to first byte)Temps écoulé avant la réception du premier octet de la réponse.
DownloadTemps passé à télécharger la réponse.

Le temps de réponse est la somme de ces calculs de temps des opérations réseau.

Échec d’un test

Un test est considéré comme FAILED s’il ne répond pas à ses assertions ou si la requête a échoué pour une autre raison. Ces raisons incluent :

ErreurDescription
CONNRESETLa connexion a été interrompue de façon soudaine par le serveur à distance. Causes possibles : erreur ou plantage du serveur Web lors de la réponse ou perte de connectivité du serveur Web.
DNSEntrée DNS introuvable pour l’URL du check. Causes possibles : URL du check mal configurée, configuration des entrées DNS incorrecte, etc.
INVALID_REQUESTLa configuration du check n’est pas valide (par exemple, en raison d’une faute de frappe dans l’URL).
SSLLa connexion SSL n’a pas pu être effectuée. Consultez la page dédiée à ce type d’erreurs pour en savoir plus.
TIMEOUTLa requête n’a pas pu être effectuée dans un délai raisonnable. Deux types d’erreur TIMEOUT peuvent se produire. TIMEOUT: The request couldn’t be completed in a reasonable time. indique que la requête a expiré lors de la connexion au socket TCP. TIMEOUT: Retrieving the response couldn’t be completed in a reasonable time. indique que la requête a expiré lors de son traitement global (qui comprend la connexion au socket TCP, le transfert de données et les assertions).

Si un test échoue, l’uptime considère directement que l’endpoint est down. Il n’est pas retesté avant le prochain test.

Pour aller plus loin