Résoudre les problèmes liés à l'API Monitoring

Pour diagnostiquer les erreurs d'API, corriger les refus d'ingestion de métriques et résoudre les problèmes de résultats de requête manquants lorsque vous utilisez l'API Monitoring, vous pouvez utiliser les techniques de dépannage et les solutions d'erreur de ce guide.

L'API Monitoring fait partie des APIs Cloud. Pour obtenir la liste des codes d'erreur partagés et des recommandations générales de gestion, consultez Gérer les erreurs.

Utiliser APIs Explorer pour le débogage

APIs Explorer est un widget intégré aux pages de référence pour les méthodes d'API. Il vous permet d'appeler la méthode en remplissant des champs. Il n'est pas nécessaire d'écrire du code.

Si vous rencontrez des problèmes avec un appel de méthode, utilisez le widget APIs Explorer (Essayer cette API) sur la page de référence de cette méthode pour déboguer votre problème. Pour en savoir plus, consultez APIs Explorer.

Erreurs générales d'API et d'authentification

Cette section répertorie les codes d'erreur qui peuvent être renvoyés par différentes méthodes de l'API Monitoring.

401 UNAUTHENTICATED

Le code d'erreur 401 UNAUTHENTICATED indique que les identifiants OAuth2 ou IAM sont manquants, ont expiré ou ne sont pas valides.

Les deux messages d'erreur courants pour ce code d'erreur sont Request is missing required authentication credential et User is not authorized to access the project (or metric).

  • Cause : En-tête Authorization: Bearer <token> manquant, jeton OAuth2 ou OIDC expiré, ou identifiants de compte de service non valides.
  • Résolution : actualisez les jetons d'authentification à l'aide des Identifiants par défaut de l'application (ADC) ou de gcloud auth print-access-token. Vérifiez également que la clé du compte de service est valide.
Si vous n'utilisez pas APIs Explorer, essayez de l'utiliser. Si votre appel d'API fonctionne dans APIs Explorer, vous rencontrez probablement un problème d'autorisation dans l'environnement où vous effectuez l'appel d'API. Accédez à la page du gestionnaire d'API pour vérifier que l'API Monitoring est activée pour votre projet.

403 PERMISSION_DENIED pour l'accès au projet et la facturation

Le code d'erreur 403 PERMISSION_DENIED indique que vous ne disposez pas des autorisations requises pour effectuer l'action demandée.

Plusieurs messages d'erreur peuvent être associés à ce code d'erreur. Voici deux messages d'erreur courants : Billing check failed for project [PROJECT_ID] et Billing account disabled.

  • Cause : Cloud Billing est désactivée ou suspendue dans le projetGoogle Cloud . L'ingestion de métriques personnalisées nécessite un compte de facturation actif.
  • Solution : Associez un compte de facturation Cloud actif au projet dans la console Google Cloud .

Si ce code d'erreur s'affiche lorsque vous écrivez des données de métrique, consultez également 403 PERMISSION_DENIED lors de l'écriture de données de métrique.

404 NOT_FOUND

Le code d'erreur 404 NOT_FOUND indique que l'ID du projet cible n'existe pas ou que la région ou l'emplacement ne sont pas reconnus.

Voici une liste des messages d'erreur courants pour ce code d'erreur :

  • Project [PROJECT_ID] not found

    • Cause : le projet spécifié dans l'URI de la demande n'existe pas ou a été supprimé.
    • Solution : Vérifiez l'orthographe de l'ID du projet et assurez-vous que le projet est actif dans la console Google Cloud .

  • Unavailable region or location ou Unrecognized region or location

    • Cause : le libellé de l'emplacement ou de la région de la ressource surveillée n'est pas valide ou n'est pas reconnu.
    • Résolution : Utilisez des noms de région et de zone Google Cloud valides, tels que us-central1 ou us-central1-a.

  • The requested URL was not found on this server

    • Cause : le chemin d'accès à la ressource dans l'URL est incorrect.
    • Résolution : comparez l'URL à l'URL de la méthode indiquée sur la page de référence de la méthode. Cette erreur peut signifier qu'il y a une erreur d'orthographe, par exemple "projet" au lieu de "projets", ou une erreur de majuscule, par exemple "TimeSeries" au lieu de "timeSeries".

500 INTERNAL, 503 UNAVAILABLE, 504 DEADLINE_EXCEEDED

Deux messages d'erreur courants sont associés à ces codes d'erreur : Internal error encountered. Please retry after a few seconds et The service is currently unavailable.

  • Cause : erreurs temporaires de l'infrastructure de backend, problèmes de réseau ou rééquilibrage des partitions de la base de données interne.
  • Solution : implémentez un intervalle exponentiel tronqué entre les tentatives avec gigue, en commençant par une seconde et en allant jusqu'à 32 secondes. Définissez les délais des clients RPC sur 15 secondes ou plus. Pour en savoir plus, consultez Réessayer en cas d'erreur d'API.

Résultats manquants

Lorsqu'un appel d'API renvoie le code d'état 200 et une réponse vide, tenez compte des points suivants :

  • Si l'appel utilise un filtre, ce dernier n'a probablement rien trouvé. La correspondance du filtre est sensible à la casse. Pour résoudre les problèmes de filtre, commencez par spécifier un seul composant de filtre, tel que metric.type, et vérifiez si vous obtenez des résultats. Ajoutez les autres composants de filtre un par un pour créer votre requête.
  • Lorsque vous utilisez une métrique personnalisée, vérifiez que le projet qui définit la métrique est spécifié.

Plusieurs raisons peuvent expliquer l'absence de points de données lorsque vous utilisez la méthode timeSeries.list :

  • Les données sont peut-être trop anciennes. Pour en savoir plus, consultez l'article Conservation des données.

  • Il est possible que les données ne soient pas encore propagées à Monitoring. Pour en savoir plus, consultez la section Latence des données de métriques.

  • L'intervalle n'est pas valide :

    • Vérifiez que l'heure de fin est correcte.
    • Vérifiez que l'heure de début est correcte et antérieure à l'heure de fin. Lorsque l'heure de début est manquante ou mal mise en forme, l'API la définit sur l'heure de fin. Pour les métriques GAUGE, cet intervalle de temps ne correspond qu'aux points dont les heures de début et de fin correspondent exactement à l'heure de fin de l'intervalle. Pour les métriques CUMULATIVE ou DELTA, qui mesurent les intervalles de temps, aucun point n'est mis en correspondance. Pour en savoir plus, consultez la page Intervalles de temps.

Erreurs lors de l'interrogation des données de métriques

Cette section fournit des informations sur les erreurs qui peuvent se produire lorsque vous lisez des données de métriques à l'aide d'une méthode telle que timeSeries.list.

400 INVALID_ARGUMENT lors de l'interrogation des données de métriques

Le code d'erreur 400 INVALID_ARGUMENT indique une erreur de validation côté client. Le message d'erreur associé au code d'erreur fournit des informations plus détaillées et est spécifique à la méthode d'API.

Par exemple, lorsque vous interrogez des données de métriques, vous pouvez recevoir les messages suivants :

  • Field filter had an invalid value ou Field filter had an invalid value of "[FILTER]": [EXPLANATION]

    • Cause : indique un problème avec le filtre de surveillance.
    • Résolution : Pour résoudre le problème, vérifiez l'orthographe et la mise en forme du filtre. Pour en savoir plus, consultez Filtres de surveillance.

  • Request was missing field interval.endTime ou Field interval.endTime had an invalid value

    • Cause : indique que l'heure de fin est manquante dans la requête ou que la valeur est incorrecte.

    • Résolution : Si vous utilisez APIs Explorer, ne citez pas la valeur du champ de temps. Voici les formats valides :

      2026-05-11T01:23:45Z
2026-05-11T01:23:45.678Z
2026-05-11T01:23:45.678+05:00
2026-05-11T01:23:45.678-04:30
```

Erreurs d'écriture des données de métriques

Cette section fournit des informations sur les erreurs qui peuvent se produire lorsque vous utilisez la méthode timeSeries.create pour écrire des données de métriques, y compris les suivantes :

  • Récapitulatif des codes d'erreur.
  • Une liste des messages d'erreur associés à chaque code d'erreur. Ces entrées incluent à la fois une cause et des informations sur la résolution. Les erreurs d'API générales s'appliquent également à la méthode create.

Si vous n'activez pas les journaux d'audit des accès aux données pour Monitoring, les échecs de la méthode timeSeries.create peuvent être silencieux. Toutefois, vous pouvez effectuer les opérations suivantes :

  • Utilisez l'explorateur de métriques pour obtenir des informations sur les taux d'erreur. Utilisez les paramètres suivants :

    • Métrique : monitoring.googleapis.com/api/request_count
    • Filtre : method = "google.monitoring.v3.MetricService.CreateTimeSeries"
    • Agrégation : Grouper par response_code

  • Utilisez l'explorateur de journaux pour interroger vos journaux d'activité d'administration. Le système les crée lorsqu'il tente de créer automatiquement un descripteur de la métrique et que cette action échoue. Pour afficher ces entrées de journal, exécutez la requête suivante en remplaçant PROJECT_ID par l'ID de votre projet Google Cloud  :

    logName="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity"
protoPayload.serviceName="monitoring.googleapis.com"
protoPayload.methodName="google.monitoring.v3.MetricService.CreateMetricDescriptor"
severity>=ERROR

  • Utilisez l'explorateur de journaux pour interroger vos journaux côté client.

Si vous activez les journaux d'audit des accès aux données pour Cloud Monitoring, le système écrit une entrée de journal pour chaque accès aux données. En particulier, ces entrées de journal incluent des informations sur le nombre de points qui n'ont pas pu être écrits et la cause de l'échec :

  • Pour savoir comment activer les journaux d'audit d'accès aux données, consultez Configurer les journaux d'audit d'accès aux données.

  • Pour afficher ces entrées de journal, utilisez l'explorateur de journaux et exécutez la requête suivante en remplaçant PROJECT_ID par l'ID de votre projetGoogle Cloud  :

    logName="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access"
protoPayload.serviceName="monitoring.googleapis.com"
protoPayload.methodName="google.monitoring.v3.MetricService.CreateTimeSeries"
severity>=ERROR

Résumé des codes d'erreur timeSeries.create

HTTP Code Code d'état gRPC Causes principales
400 INVALID_ARGUMENT Échec de la validation de la charge utile : taille de lot, taille ou clé du libellé, ordre chronologique, structure de l'histogramme de distribution, schéma ou type non concordants.
400 FAILED_PRECONDITION Le taux d'échantillonnage a été dépassé, le type de métrique n'est pas compatible ou les données sont arrivées en retard en dehors de la période de conservation.
401 UNAUTHENTICATED Identifiants OAuth2 ou IAM manquants, expirés ou non valides.
403 PERMISSION_DENIED Rôle IAM roles/monitoring.metricWriter manquant, Cloud Billing désactivé ou tentative non autorisée d'écriture dans des domaines de métriques système réservés.
404 NOT_FOUND L'ID du projet cible n'existe pas ou la région/l'emplacement ne sont pas reconnus.
429 RESOURCE_EXHAUSTED La limite de cardinalité des séries temporelles actives a été dépassée sur une ressource surveillée, les limites de descripteur de la métrique de projet ont été atteintes ou les limites de taux de requêtes d'API ont été dépassées.
500 INTERNAL Échec du service de stockage interne ou de schéma.
503 UNAVAILABLE Indisponibilité temporaire du service de backend.
504 DEADLINE_EXCEEDED La requête a expiré avant l'écriture des points de données sur les nœuds de stockage.

400 INVALID_ARGUMENT lors de l'écriture des données de métrique

400 INVALID_ARGUMENT indique des erreurs de validation côté client dans la structure de la requête, les métadonnées de métrique, les définitions de libellé, l'alignement du code temporel ou les valeurs de point.

Demander la résolution des problèmes liés à la structure et au traitement par lot

Vous trouverez ci-dessous la liste des messages d'erreur liés aux cas de non-respect de la structure et du traitement par lot :

  • Request was missing field timeSeries

    • Cause : Le tableau time_series de la requête était vide.
    • Résolution : Incluez au moins un objet TimeSeries dans chaque requête.

  • The maximum number of TimeSeries objects per Create request is 200

    • Cause : La requête contient plus de 200 objets TimeSeries.
    • Solution : Regroupez les écritures par lots de 200 séries temporelles maximum par requête.

  • Field points had an invalid value: Only one point can be written per TimeSeries per request

    • Cause : Un seul objet TimeSeries contient plusieurs entrées dans son champ points.
    • Solution : Fournissez exactement un Point par objet TimeSeries et par demande. Pour écrire plusieurs points de données au fil du temps pour la même métrique, envoyez-les dans des requêtes distinctes.

  • Duplicate TimeSeries encountered. Only one point can be written per TimeSeries per request

    • Cause : Au moins deux objets TimeSeries dans la même requête partagent des types de métriques, des libellés de métriques et des libellés de ressources surveillées identiques.
    • Résolution : dédupliquez les séries temporelles dans les lots côté client afin que chaque série temporelle unique apparaisse au maximum une fois par requête.

  • user defined metrics are not supported on the metric domain "[DOMAIN]"

    • Cause : Les métriques définies par l'utilisateur ne sont pas acceptées dans le domaine spécifié.
    • Solution : aucune.

Libellés et contraintes de dénomination

Vous trouverez ci-dessous la liste des messages d'erreur liés aux libellés et aux contraintes de dénomination :

  • Field metric.labels had an invalid value of "[KEY]": Label value exceeds the maximum string size of 1024 characters

    • Cause : La valeur d'un libellé de métrique ou de ressource dépasse 1 024 caractères.
    • Résolution : configurez votre collecteur ou votre application pour tronquer les valeurs des libellés à 1 024 caractères ou moins. Évitez de stocker des volumes de texte importants dans les libellés de métriques. Écrivez plutôt ces détails dans Cloud Logging.

  • Field metric.labels had an invalid value of "[KEY]": Label key contains invalid characters

    • Cause : Une clé d'étiquette contient des caractères ne correspondant pas au modèle autorisé. Les clés peuvent contenir des caractères alphanumériques et des traits de soulignement. Elles ne doivent pas dépasser 100 caractères et doivent commencer par une lettre.
    • Résolution : Renommez les clés de libellé pour n'utiliser que des caractères valides.

  • The metric type must be a URL-formatted string with a domain and non-empty path

    • Cause : le metric.type est mal formé ou il manque un préfixe de domaine.
    • Résolution : Mettez en forme les types de métriques personnalisées comme custom.googleapis.com/<category>/<name> ou workload.googleapis.com/<name>.

  • Field metric.labels had an invalid value: The metric [METRIC_NAME] has more than [LIMIT] labels

    • Cause : Le nombre de libellés dans un descripteur de la métrique personnalisée dépasse 30 ou, pour les métriques Prometheus, dépasse 200.
    • Résolution : Supprimez les libellés inutiles pour ne pas dépasser la limite de descripteurs.

  • unrecognized metric label "[LABEL_KEY]"

    • Cause : le descripteur de la métrique existe déjà, mais la requête fournit une clé de libellé qui n'est pas définie dans le descripteur.
    • Solution : Assurez-vous que les clés de libellé correspondent à MetricDescriptor existant ou créez un descripteur de la métrique si la modification du schéma est nécessaire.

Incohérences entre les identifiants de projet et de ressource

Vous trouverez ci-dessous la liste des messages d'erreur liés aux incohérences entre les identifiants de projet et de ressources :

  • Field resource.labels.project_id had an invalid value of "[VAL]": if present, must be the project number or ID in the request name ([PROJECT]) ou Field resource.labels.project_id had an invalid value of "[VAL]": if present, must be the resource container ID in the request name [PROJECT]

    • Cause : le libellé project_id ou resource_container spécifié dans resource.labels ne correspond pas à l'ID du projet ni au numéro de projet dans le nom de la demande.
    • Solution : Définissez le libellé project_id de la ressource pour qu'il corresponde au projet de la demande, ou omettez le libellé project_id de resource.labels afin qu'il soit défini par défaut sur le projet de la demande.

  • unrecognized resource type "[RESOURCE_TYPE]" ou missing resource type

    • Cause : resource.type n'est pas reconnu par Cloud Monitoring ou est omis pour une métrique non personnalisée.
    • Résolution : utilisez un type de ressource surveillée valide, tel que gce_instance, k8s_container, generic_task ou global.

Horodatages et intervalles

Vous trouverez ci-dessous la liste des messages d'erreur liés aux codes temporels et aux intervalles :

  • Points must be written in order. One or more of the points specified had an older end time than the most recent point

    • Cause : le end_time du point de données est antérieur ou égal au code temporel du point de données le plus récent précédemment ingéré pour cette série temporelle.
    • Solution : Ingestez les points strictement dans l'ordre chronologique.

  • Field points[0].interval.start_time had an invalid value of "[START]": The start time must be equal to the end time ([END]) for the gauge metric '[METRIC]'

    • Cause : Un point de métrique GAUGE a été envoyé alors que start_time n'est pas égal à end_time.
    • Résolution : pour les métriques GAUGE, définissez start_time sur end_time ou omettez start_time.

  • Field points[0].interval.start_time had an invalid value of "[START]": The start time must be before the end time ([END]) for the non-gauge metric '[METRIC]'

    • Cause : un point de données de métrique CUMULATIVE ou DELTA a une valeur start_time supérieure ou égale à la valeur end_time.
    • Résolution : Assurez-vous que la valeur start_time est inférieure à la valeur end_time et qu'elle représente un intervalle de temps non nul.

  • Field points[0].interval.end_time had an invalid value of "[TIME]": Data points cannot be written more than 5m into the future.

    • Cause : Le code temporel du point est supérieur de plus de cinq minutes à l'heure actuelle du serveur.
    • Résolution : synchronisez l'horloge système avec le serveur NTP public de Google (time.google.com).

  • Field points[0].interval.end_time had an invalid value of "[TIME]": Data points cannot be written more than approximately 24 hours in the past

    • Cause : L'horodatage du point est antérieur à l'horizon de conservation en mémoire, qui est de 24 heures.
    • Solution : écrivez les données en temps réel dans les 24 heures suivant leur génération.

Types de valeurs et distributions

Vous trouverez ci-dessous la liste des messages d'erreur liés aux types et aux distributions de valeurs :

  • value type for metric must be [EXPECTED], but is [ACTUAL] ou metric kind for metric must be [EXPECTED], but is [ACTUAL]

    • Cause : le type de valeur entrante (INT64, DOUBLE, STRING, BOOL, DISTRIBUTION) ou le type de métrique (GAUGE, DELTA, CUMULATIVE) sont en conflit avec le MetricDescriptor existant.
    • Solution : Assurez-vous que les types de données correspondent au descripteur existant. Les types de valeurs et les genres de métriques ne peuvent pas être modifiés après leur création.

  • Field points[0].value had an invalid value: The metric value exceeds the maximum string size of 1024 characters

    • Cause : un point de données de métrique de type de valeur STRING dépasse 1 024 caractères.
    • Résolution : Tronquez les valeurs de métriques de chaîne à 1 024 caractères ou moins, ou envoyez plutôt les journaux à Cloud Logging.

  • Field points[0].value had an invalid value: Bucket options must be specified for Distribution metric

    • Cause : Un point DISTRIBUTION ne spécifie pas bucket_options.
    • Résolution : définissez linear_buckets, exponential_buckets ou explicit_buckets pour les métriques de distribution.

  • Field points[0].value.distributionValue had an invalid value: Distribution value has |bucket_counts| fields that sum to X which does not equal the |count| field value of Y

    • Cause : la somme des nombres dans bucket_counts n'est pas égale au champ count.
    • Solution : Assurez-vous que la somme de tous les nombres de buckets est égale à l'échantillon count.

  • Field points[0].value had an invalid value: Distribution metric has too many buckets

    • Cause : Le nombre de buckets de l'histogramme est supérieur à 200.
    • Résolution : ajustez les paramètres des buckets pour que leur nombre total ne dépasse pas 200.

400 FAILED_PRECONDITION

Vous trouverez ci-dessous la liste des messages d'erreur associés à ce code d'erreur :

  • One or more points were written more frequently than the maximum sampling period configured for the metric

    • Cause : des points pour la même série temporelle ont été envoyés plus rapidement que le taux maximal autorisé d'un point toutes les cinq secondes.
    • Résolution : Limitez le débit d'ingestion afin que les points consécutifs d'une série temporelle spécifique soient espacés d'au moins cinq secondes.

  • ingestion of prometheus delta metrics is not supported in this API

    • Cause : La requête a tenté d'écrire des métriques Prometheus DELTA via timeSeries.create.
    • Résolution : utilisez les métriques Prometheus GAUGE ou CUMULATIVE, ou ingérez-les via les points de terminaison OTLP Google Cloud Managed Service pour Prometheus.

  • One or more points arrived late outside of its aggregation window

    • Cause : Les points sont arrivés après la période d'agrégation pour les métriques agrégées de la collection.
    • Résolution : videz et diffusez les points avec des latences de tampon inférieures.

403 PERMISSION_DENIED lors de l'écriture des données de métrique

Lorsque vous écrivez des données de métriques, vous pouvez recevoir une réponse 403 PERMISSION_DENIED pour des raisons liées à l'accès au projet et à la facturation, ainsi que pour les raisons suivantes :

  • Permission monitoring.timeSeries.create denied on resource (or it may not exist)

    • Cause: L'appelant ne dispose pas de l'autorisation monitoring.timeSeries.create sur le projet cible.
    • Solution : Attribuez le rôle Monitoring Metric Writer (roles/monitoring.metricWriter) au compte de service ou au compte principal.

  • Billing check failed for project [PROJECT_ID] ou Billing account disabled

    • Cause: Cloud Billing est désactivée ou suspendue sur leGoogle Cloud projet. L'ingestion de métriques personnalisées nécessite un compte de facturation actif.
    • Solution : Associez un compte de facturation Cloud actif au projet dans la console Google Cloud .

  • User does not have permission to write to metric [METRIC]

    • Cause : L'appelant a tenté d'écrire des métriques personnalisées directement dans des domaines réservés au système, tels que compute.googleapis.com ou storage.googleapis.com.
    • Solution : Utilisez des domaines de métriques personnalisées tels que custom.googleapis.com/ ou workload.googleapis.com/.

429 RESOURCE_EXHAUSTED

Vous trouverez ci-dessous la liste des messages d'erreur associés à ce code d'erreur :

  • Monitored resource ([RESOURCE_ID]) has too many time series (custom metrics)

    • Cause : Limite de séries temporelles actives dépassée (cardinalité élevée). Le nombre de séries temporelles actives pour une seule ressource surveillée a dépassé la limite de 200 000 séries actives sur une période de 24 heures. Pour les métriques Prometheus, la limite est de 1 000 000 de séries actives. Cela se produit généralement lorsque des ID éphémères, tels que des ID de conteneur, des UUID de pod, des ID de requête, des ID utilisateur ou des codes temporels, sont inclus dans les libellés de métriques sur les ressources en perte d'utilisateurs.
    • Solution :
      • Supprimez les libellés éphémères ou à cardinalité élevée de vos métriques.
      • Si vous devez suivre les métriques pour des tâches éphémères individuelles, utilisez plutôt le type de ressource surveillée generic_task au lieu de types spécifiques aux ressources comme dataflow_job. Mappez l'identifiant éphémère au libellé task_id de la ressource generic_task.

  • Your Metric Ingestion quota has been exhausted

    • Cause : Le projet a dépassé le quota de débit d'ingestion de l'API.
    • Solution : Écrivez des séries temporelles par lot jusqu'à 200 séries par requête, ou demandez une augmentation de quota sur la page "Quotas" de la console Google Cloud .

  • Your Metric Descriptors quota has been exhausted

    • Cause : Le projet a atteint la limite maximale de 10 000 descripteurs de métriques personnalisées par projet. Pour les métriques Prometheus, cette limite est de 25 000 par projet.
    • Résolution : supprimez les descripteurs de métriques inutilisés à l'aide de projects.metricDescriptors.delete ou réduisez l'attribution de noms dynamiques aux métriques.

  • Rate of metric descriptor creation exceeded

    • Cause : Le projet a tenté de créer des descripteurs de métriques plus rapidement que 6 000 par minute et par projet.
    • Résolution : Évitez de créer dynamiquement de nouveaux types de métriques lors de l’ingestion de données ; pré-créez des descripteurs lorsque cela est possible.

Réessayer les erreurs d'API

Deux des codes d'erreur des API Cloud indiquent des circonstances dans lesquelles il peut être utile de réessayer la requête :

  • 503 UNAVAILABLE : les tentatives sont utiles si le problème est une condition de courte durée ou temporaire.
  • 429 RESOURCE_EXHAUSTED : les nouvelles tentatives sont utiles, après un délai, pour les tâches en arrière-plan de longue durée associées à un quota horaire, par exemple n appels par t secondes. Les tentatives ne sont pas utiles lorsque le problème est une condition de courte durée ou temporaire, ou lorsque vous avez épuisé un quota basé sur le volume. Pour les conditions transitoires, envisagez de tolérer l'échec. Pour les problèmes liés aux quotas, envisagez de réduire votre utilisation de quota ou de demander une augmentation de quota.

Lorsque vous écrivez du code susceptible de relancer des requêtes, assurez-vous d'abord que la requête est sécurisée.

La requête peut-elle être réessayée en toute sécurité ?

Si la requête est idempotente, vous pouvez réessayer en toute sécurité. Une action idempotente est une opération où toute modification de l'état ne dépend pas de l'état actuel. Exemple :

  • La lecture de x est idempotente. La valeur ne change pas.
  • Définir x sur 10 est idempotent. Cela peut modifier l'état, si la valeur n'est pas déjà égale à 10, mais peu importe la valeur actuelle. Peu importe le nombre de fois que vous tentez de définir la valeur.
  • Augmenter x n'est pas idempotent. La nouvelle valeur dépend de la valeur actuelle.

Réessayer avec un intervalle exponentiel entre les tentatives

Lorsque vous mettez en œuvre du code pour relancer des requêtes, vous ne souhaitez pas rapidement émettre de nouvelles requêtes indéfiniment. Si un système est surchargé, cette approche contribue au problème.

Optez plutôt pour un intervalle exponentiel tronqué entre les tentatives. Lorsque les requêtes échouent à cause d'une surcharge transitoire plutôt que d'une véritable indisponibilité, la solution réduit la charge. Un intervalle exponentiel tronqué entre les tentatives suit le modèle général suivant :

  • Déterminez la durée pendant laquelle vous souhaitez attendre ou le nombre de tentatives que vous êtes prêt à effectuer. Lorsque cette limite est dépassée, considérez le service comme indisponible et gérez cette condition correctement pour votre application. C'est ce qui rend l'intervalle entre les tentatives tronqué. Vous arrêtez d'effectuer de nouvelles tentatives à un moment donné.

  • Réessayez d'exécuter la requête avec des pauses de plus en plus longues avec un intervalle entre la fréquence des tentatives. Réessayez jusqu'à ce que la requête aboutisse ou que la limite établie soit atteinte.

    L'intervalle est généralement augmenté par une fonction de la puissance du nombre de nouvelles tentatives, ce qui en fait un intervalle exponentiel entre les tentatives.

Il existe plusieurs façons de mettre en œuvre un intervalle exponentiel entre les tentatives. Voici un exemple qui ajoute un délai d'attente croissant à un délai minimal de 1 000 ms. Le délai initial de l'intervalle entre les tentatives est de 2 ms, puis il augmente à 2retry_count ms à chaque tentative.

Le tableau suivant indique les intervalles de nouvelles tentatives à l'aide des valeurs initiales :

  • Délai minimal = 1 s = 1 000 ms
  • Intervalle initial entre les tentatives = 2 ms
Nombre de nouvelles tentatives Délai supplémentaire (ms) Réessayer après (ms)
0 20 = 1 1001
1 21 = 2 1002
2 22 = 4 1004
3 23 = 8 1008
4 24 = 16 1016
… … …
n 2n 1 000 + 2n

Vous pouvez tronquer le cycle de nouvelle tentative en arrêtant n fois ou lorsque le temps passé est supérieur à une valeur raisonnable pour votre application.

Pour en savoir plus, consultez l'article Wikipédia Intervalle exponentiel entre les tentatives.