Centiles et métriques à valeur de distribution

Ce document explique comment comprendre les centiles et le modèle d'histogramme pour des données de métrique avec un type de valeur Distribution. Une métrique de distribution définit des plages de valeurs, appelées buckets, et enregistre le nombre de valeurs mesurées comprises dans chaque bucket. Les métriques de distribution n'indiquent pas les valeurs de mesure individuelles, mais un histogramme du nombre de mesures dans les buckets. Ce type de valeur est utilisé par les services lorsque les mesures individuelles sont trop nombreuses à collecter, mais que des informations statistiques, telles que des moyennes ou des centiles, concernent ces mesures.

La section suivante de cette page utilise un exemple synthétique pour montrer comment les centiles sont déterminés. L'exemple montre que les valeurs des centiles dépendent du nombre de buckets, de la largeur des buckets, de la distribution des mesures et du nombre total d'échantillons. Les valeurs des centiles ne dépendent pas des valeurs réelles mesurées, car ces valeurs ne sont pas disponibles dans l'histogramme.

Exemple avec des données synthétiques

Prenons l'exemple d'un modèle de bucket Exponential ayant une échelle de 1, un facteur de croissance de 2 et 10 buckets finis. Cet histogramme contient 12 buckets, les 10 buckets finis, un bucket qui ne spécifie qu'une limite supérieure et un qui ne spécifie qu'une limite inférieure. Dans cet exemple, le bucket fini avec l'indice n+1 est deux fois plus large que le bucket fini avec l'indice n.

Les exemples suivants montrent que la largeur du bucket détermine l'erreur maximale entre le centile calculé et les mesures. Ils indiquent également que le nombre d'échantillons dans un histogramme est important. Par exemple, si le nombre d'échantillons est inférieur à 20, les 95e et 99e centiles se trouvent toujours dans le même bucket.

Scénario 1 : le nombre total d'échantillons est de 1.

Lorsqu'il existe une seule mesure, les trois valeurs de centile diffèrent, mais elles n'affichent que les 50e, 95e et 99e centiles du même bucket. L'erreur entre l'estimation et les mesures réelles ne peut pas être déterminée, car la mesure n'est pas connue.

Par exemple, supposons que l'histogramme des mesures se présente comme indiqué dans le tableau suivant :

Pour calculer le 50e centile, procédez comme suit :

1. Utilisez le nombre de buckets pour déterminer le bucket qui contient le 50e centile. Dans cet exemple, le bucket numéro 8 contient le 50e centile.

2. Calculez l'estimation à l'aide de la règle suivante:

   pth percentage = bucket_low +
                   (bucket_up - bucket_low)*(p - p_low)/(p_up - p_low)
   

   Dans l'expression précédente, p_low et p_up correspondent aux limites inférieure et supérieure de la plage de percentiles du bucket. De même, bucket_low et bucket_up sont les limites inférieure et supérieure du bucket. Les valeurs de p_low et p_up dépendent de la répartition des totaux entre les différents buckets.

Par exemple, le 50e centile est calculé comme suit:

   50th percentile = 128 + (256-128)*(50-0)/(100-0)
                   = 128 + 128 * 50 / 100
                   = 128 + 64
                   = 192

Pour calculer le 95e percentile, remplacez 50 par 95 dans l'expression précédente. Dans cet exemple, où il n'y a qu'un seul échantillon, les percentiles sont les suivants:

L'erreur entre l'estimation et les mesures réelles peut être limitée, mais elle ne peut pas être déterminée, car la mesure n'est pas connue.

Scénario 2: le nombre total d'échantillons est de 10.

Lorsqu'il y a 10 échantillons, le 50e centile peut se trouver dans un bucket différent des 95e et 99e centiles. Toutefois, il n'existe toujours pas suffisamment de mesures pour permettre aux 95e et 99e centiles de se trouver dans des buckets différents.

Par exemple, supposons que l'histogramme des mesures se présente comme indiqué dans le tableau suivant :

Vous pouvez utiliser la procédure décrite précédemment pour calculer les 50e, 95e et 99e centiles. Par exemple, le 50e centile, qui se trouve dans le bucket 1, est calculé comme suit:

50th percentile = 1 + (2-1)*(50-40)/(60-40)
                = 1 + (1 * 10 / 20)
                = 1 + 0.5
                = 1.5

De même, le 95e centile est calculé comme suit:

95th percentile = 128 + (256-128)*(95-90)/(100-90)
                = 128 + 128 * 5 / 10
                = 128 + 64
                = 192

À l'aide du processus décrit précédemment, les centiles peuvent être calculés. Chaque ligne du tableau suivant présente un centile, le bucket correspondant et la valeur calculée :

Dans cet exemple et dans l'exemple précédent, le 95e centile se trouve dans le bucket 8. Toutefois, le calcul du centile est différent. La différence est due à la façon dont les échantillons sont distribués. Dans le premier exemple, tous les échantillons se trouvent dans le même bucket, tandis que dans l'exemple le plus récent, les échantillons se trouvent dans différents buckets.

Exemple avec des données réelles

Cette section contient un exemple illustrant comment déterminer le modèle de bucket utilisé par une métrique particulière. Cette section montre également comment évaluer l'erreur potentielle dans les valeurs de centiles calculées.

Identifier le modèle de bucket

Pour déterminer les buckets utilisés pour une métrique sur un intervalle de temps spécifique, appelez la méthode projects.timeSeries/list de l'API Cloud Monitoring.

Par exemple, pour identifier le modèle de bucket d'une métrique, procédez comme suit :

1. Accédez à la page Web projects.timeSeries/list.

2. Dans APIs Explorer, saisissez le filtre qui spécifie la métrique, une heure de début et une heure de fin.

   Par exemple, pour obtenir des informations sur la métrique qui stocke les latences des requêtes API, saisissez les informations suivantes:

   metric.type="serviceruntime.googleapis.com/api/request_latencies"
   resource.type="consumed_api"
   

   Dans cet exemple, le champ de filtre spécifie un type de métrique et un type de ressource. Pour en savoir plus sur ces filtres, consultez la section Filtres de surveillance.

3. Appuyez sur Entrée.

Voici la réponse de l'API list pour une métrique à valeur de distribution disponible dans un projet Google Cloud :

{
  "timeSeries": [
    {
      "metric": {...},
      "resource": {...},
      },
      "metricKind": "DELTA",
      "valueType": "DISTRIBUTION",
      "points": [
        {
          "interval": {
            "startTime": "2020-11-03T15:05:00Z",
            "endTime": "2020-11-03T15:06:00Z"
          },
          "value": {
            "distributionValue": {
              "count": "3",
              "mean": 25.889,
              "bucketOptions": {
                "exponentialBuckets": {
                  "numFiniteBuckets": 66,
                  "growthFactor": 1.4,
                  "scale": 1
                }
              },
              "bucketCounts": [
                "0",
                "0",
                "0",
                "0",
                "0",
                "0",
                "0",
                "0",
                "0",
                "0",
                "3"
              ]
            }
          }
        },

Dans la réponse de l'API, le champ value décrit les données stockées dans le tableau points. Les champs count et mean indiquent que, pour l'intervalle de temps spécifié, il existe trois mesures et leur valeur moyenne est de 25,889. Le champ bucketOptions indique que le modèle exponentiel est configuré pour avoir 66 buckets, une échelle de 1 et un facteur de croissance de 1,4.

Pour calculer les limites inférieure et supérieure du bucket avec l'index n, utilisez les règles suivantes :

• Limite inférieure (1 ≤ n < N) = échelle * (facteur de croissance)^(n-1)
• Limite supérieure (0 ≤ n < N-1) = échelle * (facteur de croissance)ⁿ

Dans les expressions précédentes, N correspond au nombre total de buckets.

Les buckets pour cette métrique, ainsi que le milieu de chaque bucket, sont présentés dans le tableau suivant:

Vérifier les calculs de centiles

Maintenant que la configuration du bucket est connue, vous pouvez prédire les valeurs des 50e, 95e et 99e centiles pour n'importe quel ensemble de mesures. Par exemple, s'il n'y a qu'un seul échantillon et qu'il se trouve dans le bucket numéro 10, la valeur du 50e centile est de 24,79.

Pour récupérer les valeurs des 50e, 95e et 99e centiles de la métrique, vous pouvez utiliser la méthode API projects.timeSeries/list, et inclure une période d'alignement et un aligneur. Dans cet exemple, les paramètres suivants ont été sélectionnés :

• Aligneur : ALIGN_PERCENTILE_50, ALIGN_PERCENTILE_95 ou ALIGN_PERCENTILE_99
• Période d'alignement : 60 s

Pour la sélection ALIGN_PERCENTILE_50, chaque valeur de la série temporelle correspond au 50e centile d'un bucket :

{
  "timeSeries": [
    {
      "metric": {...},
      "resource": {...},
      "metricKind": "GAUGE",
      "valueType": "DOUBLE",
      "points": [
        {
          "interval": {
            "startTime": "2020-11-03T15:06:36Z",
            "endTime": "2020-11-03T15:06:36Z"
          },
          "value": {
            "doubleValue": 24.793256140799986
          }
        },
        {
          "interval": {
            "startTime": "2020-11-03T15:05:36Z",
            "endTime": "2020-11-03T15:05:36Z"
          },
          "value": {
            "doubleValue": 34.710558597119977
          }
        },
        {
          "interval": {
            "startTime": "2020-11-03T15:04:36Z",
            "endTime": "2020-11-03T15:04:36Z"
          },
          "value": {
            "doubleValue": 24.793256140799986
          }
        }
      ]
    },

Pour deux des échantillons, le 50e centile se trouve dans le bucket 10. Pour l'autre échantillon, il se trouve dans le bucket 11.

Le tableau suivant présente les résultats de l'exécution de la méthode projects.timeSeries/list avec différents aligneurs. La première ligne correspond au cas où l'aligneur n'est pas spécifié. Lorsque vous ne spécifiez pas d'aligneur, le modèle de bucket et les valeurs moyennes sont renvoyés. Les trois lignes suivantes présentent les données renvoyées lorsque l'aligneur est défini sur ALIGN_PERCENTILE_50, ALIGN_PERCENTILE_95 et ALIGN_PERCENTILE_99 :

Comme le montrent les deux exemples avec des données synthétiques, les valeurs des percentiles dépendent de la distribution des échantillons. Lorsque tous les échantillons se trouvent dans le bucket d'échantillons, le 50e centile correspond au milieu de ce bucket. Toutefois, lorsque les échantillons se trouvent dans différents buckets, cette distribution affecte les estimations.

Pour déterminer si le 50e centile est une estimation raisonnable de la moyenne, vous pouvez comparer la valeur moyenne au 50e centile. La valeur moyenne est renvoyée avec les détails du bucket.

Étape suivante

Pour savoir comment visualiser les métriques à valeur de distribution, consultez la section À propos des métriques à valeur de distribution.