Créer des métriques de distribution

Cette page explique comment créer des métriques de type distribution basées sur les journaux à l'aide de la console GCP et de l'API Stackdriver Logging.

Aperçu

Les métriques de distribution nécessitent à la fois un filtre pour sélectionner les entrées de journal pertinentes et un extracteur de valeur pour saisir la valeur numérique de distribution. L'extracteur de valeur est du même type que celui utilisé pour les libellés personnalisés.

Une métrique de distribution enregistre la distribution statistique des valeurs extraites dans des buckets d'histogramme. Les valeurs extraites ne sont pas enregistrées individuellement, mais leur distribution entre les buckets configurés est enregistrée, ainsi que le nombre, la moyenne et la somme des écarts au carré des valeurs. Vous pouvez utiliser la disposition par défaut des buckets d'histogramme dans votre distribution ou vous pouvez affiner les limites des buckets pour capturer approximativement les valeurs.

Créer une métrique de distribution

Console Logging

Suivez ces étapes pour créer une métrique basée sur les journaux dans la console GCP :

  1. Cliquez sur Stackdriver Logging > Métriques basées sur les journaux dans la liste de navigation de gauche de la console GCP, ou cliquez sur le bouton suivant :

    Accéder à la visionneuse de journaux

  2. Sélectionnez un projet dans le menu déroulant en haut de la page.

  3. Cliquez sur Create Metric (Créer une métrique) en haut de la page. Le volet Metric Editor (Éditeur de métriques) s'affiche sur le côté droit de la page et le panneau de visualisation affichant vos journaux sur le côté gauche :

    Créer une métrique de distribution

  4. Dans le panneau de visualisation, créez un filtre n'affichant que les entrées de journal que vous souhaitez inclure dans la métrique.

    Le filtre de base est disponible dans les menus déroulants au-dessus des entrées de journal. Vous pouvez également accéder à l'interface de filtrage avancé en cliquant sur le menu déroulant dans la partie droite de la barre de recherche et en sélectionnant Convertir en filtre avancé.

    Pour en savoir plus, consultez la section Interfaces utilisateur.

  5. Dans le panneau Metric Editor (Éditeur de métriques), définissez les champs suivants :

    • Name (Nom) : choisissez un nom unique parmi les métriques basées sur les journaux de votre projet. Certaines restrictions en termes de dénomination s'appliquent, consultez la section Dépannage pour plus de détails.
    • Description : ajoutez une description pour la métrique.
    • Labels (Libellés) : (facultatif) ajoutez des libellés en cliquant sur Ajouter un élément pour chaque libellé. Pour plus de détails sur la définition des libellés, consultez la section Libellés de métriques basées sur les journaux.
    • Units (Unités) : (facultatif) pour les métriques de distribution, vous pouvez éventuellement saisir des unités, telles que s, ms, etc. Pour en savoir plus, reportez-vous au champ unit de MetricDescriptor.
    • Type : distribution.
    • Field name (Nom du champ) : saisissez le nom du champ d'entrée de journal qui contient la valeur de distribution. Des suggestions sont affichées à mesure que vous saisissez des caractères. Exemple :

      jsonPayload.latency
      
    • Extraction expression (Expression d'extraction) : (facultatif) si le paramètre Field name (Nom du champ) contient toujours une valeur numérique convertible en type double, vous pouvez laisser ce champ vide. Sinon, spécifiez une expression régulière qui extrait la valeur de distribution numérique de la valeur du champ. Vous pouvez accéder au menu Build (Créer) pour créer et vérifier l'expression régulière de manière interactive.

      Exemple : Supposons que le champ d'entrée du journal latency contienne un chiffre suivi de ms pour "millisecondes". L'expression régulière suivante permet d'extraire le chiffre sans le suffixe d'unité :

      ([0-9.]+)ms
      

      Les parenthèses, connues sous le nom de groupe de capture de l'expression régulière, permettent d'identifier la partie de la correspondance de texte qui sera extraite. Pour en savoir plus sur les expressions régulières, consultez la section Syntaxe RE2.

    • More (Histogram buckets) (Plus (Buckets d'histogrammes)) : (facultatif) cliquez sur More (Plus) pour ouvrir une section du formulaire dans laquelle vous pouvez spécifier des formes de buckets personnalisées. Si ne spécifiez rien, une forme de bucket par défaut est utilisée. Pour en savoir plus, consultez la section Buckets d'histogrammes sur cette page.

  6. Cliquez sur Create Metric (Créer une métrique).

API Logging

Pour créer une métrique de distribution, utilisez la méthode projects.metrics.create de l'API Stackdriver Logging. Vous pouvez l'essayer dans [APIs Explorer][apis-explorer-create]. Préparez les arguments de la méthode comme suit :

  1. Définissez le champ parent sur le projet dans lequel la métrique doit être créée :

    projects/[PROJECT_ID]
    
  2. Définissez le corps de la requête sur un objet LogMetric. Voici un exemple de l'objet pour une métrique de distribution :

    {
      name:        "my-metric"
      description: "Description of my-metric."
      filter:      "resource.type=gce_instance AND logName:\"logs/syslog\"",
      valueExtractor: "REGEX_EXTRACT(jsonPayload.latencyField, \"([0-9.]+)ms\")",
    
      labelExtractors: {
        "my-label-1":
          "REGEXP_EXTRACT(jsonPayload.someField, \"before ([[:word:]]+) after\")",
        "my-label-2":
          "EXTRACT(jsonPayload.anotherField, \"before ([0-9]+) after\")",
      },
      bucketOptions: { [SEE_BELOW] },
    
      metricDescriptor: {
          metricKind: DELTA,
          valueType: DISTRIBUTION,
          unit: "ms",
    
          labels: [
            {
              key: "my-label-1",
              valueType: STRING,
              description: "Description of string my-label-1.",
            },
            {
              key: "my-label-2",
              valueType: INT64,
              description: "Description of integer my-label-2.",
            }
          ]
      },
    }
    

Remarques pour les métriques de distribution :

  • Certaines restrictions en termes de dénomination s'appliquent, consultez la section Dépannage pour plus de détails.

  • metricDescriptor : objet MetricDescriptor. metricKind doit être DELTA. valueType doit être DISTRIBUTION.

Buckets d'histogrammes

Les métriques de distribution incluent un histogramme qui compte le nombre de valeurs comprises dans des plages spécifiées (buckets). Vous pouvez avoir jusqu'à 200 buckets dans une métrique de distribution.

Chaque bucket comprend deux valeurs limites (L et H) définissant la valeur la plus basse et la valeur la plus élevée qu'il couvre. La largeur du bucket est égale à H – L. Comme il ne peut pas y avoir d'intervalles entre les buckets, la limite inférieure d'un bucket correspond à la limite supérieure du bucket précédent, et ainsi de suite. Pour que les limites n'appartiennent pas à plus d'un bucket, un bucket inclut la limite inférieure, et la limite supérieure appartient au bucket suivant.

Toutes les dispositions de buckets peuvent être spécifiées en répertoriant, dans l'ordre croissant, les valeurs limites entre les buckets individuels. Le premier bucket, le bucket de dépassement de capacité négatif, inclut les valeurs inférieures à la première limite. Le dernier bucket, le bucket de dépassement de capacité positif, inclut les valeurs supérieures ou égales à la dernière limite. Les autres buckets incluent les valeurs supérieures ou égales à leur limite inférieure et les valeurs inférieures à leur limite supérieure. S'il y a n valeurs limites, il y a n+1 buckets. En excluant les buckets de dépassement de capacité négatif et positif, on obtient n-1 buckets finis.

Il existe trois manières différentes de spécifier les limites entre les buckets d'histogrammes pour les métriques de distribution. Vous pouvez spécifier une formule pour les valeurs limites ou les répertorier :

  • Linear (Linéaire) (offset, width, i) : chaque bucket a la même largeur. Les limites sont offset + width x i, où i = 0, 1, 2, ..., N. Pour plus d'informations sur les buckets linéaires, consultez la section Documentation de référence sur les API.

  • Exponential (Exponentielle) (scale, growth_factor, i) : les largeurs de bucket augmentent pour les valeurs les plus élevées. Les limites sont scale x growth_factor^i, où i = 0, 1, 2, ..., N. Pour plus d'informations sur les buckets exponentiels, consultez la section Documentation de référence sur les API.

  • Explicit (Explicite) : vous répertoriez toutes les limites des buckets dans le tableau bounds. Le bucket i comporte les limites suivantes :

    Limite supérieure : limites[i] où (0 <= i < N-1)
    Limite inférieure : limites[i - 1] où (1 <= i < N)

    Pour plus d'informations sur les buckets explicites, consultez la section Documentation de référence sur les API.

La façon dont vous spécifiez les buckets d'histogrammes est expliquée à la section suivante :

Console Logging

Le sous-menu Histogram buckets (Buckets d'histogrammes) s'ouvre lorsque vous créez une métrique de distribution et que vous cliquez sur More (Plus) dans le formulaire Metric editor (Éditeur de métriques). Le sous-formulaire associé à la disposition du bucket linéaire se présente comme suit :

Buckets d'histogrammes

Buckets linéaires : remplissez le formulaire du bucket d'histogrammes comme suit.

  • Type : linear (linéaire).
  • Start value (a) (Valeur de début) : limite inférieure du premier bucket fini. Cette valeur est appelée offset dans l'API.
  • Number of buckets (N) (Nombre de buckets) : nombre de buckets finis. La valeur doit être supérieure ou égale à 0.
  • Bucket width (b) (Largeur du bucket) : différence entre la limite supérieure et la limite inférieure dans chaque bucket fini. La valeur doit être supérieure à 0.

Par exemple, si la valeur de départ est 5, le nombre de buckets est de 4 et la largeur du bucket est de 15, les plages de buckets sont les suivantes :

[-INF, 5), [5, 20), [20, 35), [35, 50), [50, 65), [65, +INF]

Buckets explicites : remplissez le formulaire de bucket d'histogrammes comme suit.

  • Type : explicite.
  • Bounds (b) (Limites) : liste séparée par des virgules des valeurs limites des buckets finis. Cette option détermine également le nombre de buckets et leur largeur.

Par exemple, si la liste des limites est la suivante :

0, 1, 2, 5, 10, 20

il y a cinq buckets finis avec les plages suivantes :

[-INF, 0), [0, 1), [1, 2), [2,5), [5, 10), [10, 20), [20, +INF]

Buckets exponentiels : remplissez le formulaire du bucket d'histogrammes comme suit.

  • Type : exponential (exponentiel).
  • Number of buckets (N) (Nombre de buckets) : nombre total de buckets finis. La valeur doit être supérieure à 0.

  • Linear scale (a)(Échelle linéaire) : échelle linéaire pour les buckets. La valeur doit être supérieure à 0.

  • Exponential growth factor (b) (Facteur de croissance exponentielle) : facteur de croissance exponentiel pour les buckets. La valeur doit être supérieure à 1.

Par exemple, si N = 4, a = 3 et b = 2, les plages du bucket sont les suivantes :

[-INF, 3), [3, 6), [6, 12), [12, 24), [24, 48), [48, +INF]

Pour en savoir plus sur les buckets, consultez BucketOptions dans l'API Stackdriver Monitoring.

API Logging

La disposition facultative du bucket est spécifiée par le champ bucketOptions de l'objet LogMetric fourni à projects.metrics.create. Pour en savoir plus sur l'objet LogMetric, consultez la section Créer une métrique de distribution sur cette page. Les ajouts pour les dispositions de bucket sont indiqués ci-dessous :

Buckets linéaires

{ # LogMetric object
  ...
  bucketOptions: {
    linearBuckets: {
      numFiniteBuckets: 4,
      width: 15,
      offset: 5
    }
  },

Dans l'exemple précédent, les buckets suivants sont créés :

[-INF, 5), [5, 20), [20, 35), [35, 50), [50, 65), [65, +INF]

Buckets explicites : les limites sont répertoriées individuellement.

{ # LogMetric object
  ...
  bucketOptions: {
    explicitBuckets: {
      bounds: [0, 1, 2, 5, 10, 20 ]
    }
  },

Dans l'exemple précédent, les buckets suivants sont créés :

[-INF, 0), [0, 1), [1, 2), [2, 5), [5, 10), [10, 20), [20, +INF]

Buckets exponentiels : les limites sont scale x growthFactor ^ ii = 0, 1, 2, …, numFiniteBuckets.

{ # LogMetric object
  ...
  bucketOptions: {
    exponentialBuckets: {
      numFiniteBuckets: 4,
      growthFactor: 2,
      scale: 3
    }
  },
  ...
}

Dans l'exemple précédent, les buckets suivants sont créés :

[-INF, 3), [3, 6), [6, 12), [12, 24), [24, 48), [48, +INF]

Latence de création

La nouvelle métrique apparaît immédiatement dans la liste des métriques de la visionneuse de journaux et dans les menus de Stackdriver Monitoring correspondants. Toutefois, la métrique peut prendre jusqu'à une minute pour commencer à collecter des données pour les entrées de journal correspondantes.

Inspecter les métriques de distribution

Pour répertorier les métriques basées sur les journaux dans votre projet GCP ou pour inspecter une métrique particulière dans votre projet, procédez comme suit :

Console de journalisation

Accédez à la page Métriques basées sur les journaux, qui répertorie toutes les métriques basées sur les journaux du projet actuellement sélectionné, en cliquant sur le bouton suivant :

Accéder aux métriques basées sur les journaux

Pour afficher les données d'une métrique basée sur les journaux, sélectionnez Afficher dans l'explorateur de métriques dans le menu à développer situé à droite de la liste des métriques.

API Logging

Répertorier les métriques

Pour répertorier les métriques basées sur les journaux définies par l'utilisateur dans un projet, utilisez la méthode API projects.metrics.list. Spécifiez les paramètres associés à la méthode comme suit :

  • parent : nom de ressource du projet projects/[PROJECT_ID].
  • pageSize : nombre maximal de résultats.
  • pageToken : obtient la page suivante des résultats. Consultez la section projects.metrics.list.

Récupérer les définitions de métrique

Pour extraire une seule métrique basée sur les journaux définie par l'utilisateur, utilisez la méthode API projects.metrics.get. Spécifiez les paramètres associés à la méthode comme suit :

  • metricName : nom de la ressource de la métrique au format

    projects/[PROJECT_ID]/metrics/[METRIC_ID]
    

Lire les données de métrique

Pour lire les données des séries temporelles d'une métrique basée sur les journaux, exécutez la commande projects.timeseries.list dans l'API Stackdriver Monitoring. Pour en savoir plus, consultez la page Lire les séries temporelles. Vous aurez besoin de l'information suivante pour les métriques basées sur les journaux :

  • Le type de métrique est logging.googleapis.com/user/[METRIC_ID].

SDK Cloud

Pour répertorier les métriques basées sur les journaux définies par l'utilisateur dans votre projet, utilisez la commande suivante :

gcloud logging metrics list

Pour afficher une métrique basée sur les journaux définie par l'utilisateur dans votre projet, utilisez la commande suivante :

gcloud logging metrics describe [METRIC_NAME]

Pour plus de détails, exécutez la commande suivante :

gcloud logging metrics --help

Vous ne pouvez pas lire les données des séries temporelles d'une métrique à partir du SDK Cloud.

Mettre à jour les métriques de distribution

Vous pouvez mettre à jour une métrique basée sur les journaux pour modifier la description, les filtres et les noms des champs référencés dans la métrique. Vous pouvez ajouter de nouveaux libellés à la métrique, et modifier les expressions régulières utilisées pour extraire des valeurs associées à la métrique et à ses libellés.

Vous ne pouvez pas modifier les noms ni les types de métriques basées sur les journaux (ni leurs libellés) et vous ne pouvez pas supprimer les libellés existants dans une métrique basée sur les journaux.

Pour modifier ou mettre à jour une métrique basée sur les journaux, procédez comme suit :

Console Logging

  1. Accédez à la page Métriques basées sur les journaux :

    Accéder aux métriques basées sur les journaux

  2. Cliquez sur Modifier la métrique dans le menu situé à droite de la métrique basée sur les journaux que vous souhaitez modifier.

  3. Ne modifiez que les éléments autorisés dans la métrique.

  4. Cliquez sur OK.

API Logging

Pour modifier ou mettre à jour une métrique basée sur les journaux, appelez la méthode projects.metrics.update dans l'API. Définissez les champs comme suit :

  • metricName : nom complet de la ressource au format

    projects/[PROJECT_ID]/metrics/[METRIC_ID]
    

    Exemple :

    projects/my-gcp-project/metrics/my-error-metric
    
  • Dans le corps de la requête, incluez un objet LogMetric identique à la métrique existante, à l'exception des modifications et des ajouts que vous souhaitez effectuer.

SDK Cloud

Vous ne pouvez modifier que la description et le filtre d'une métrique existante à l'aide du SDK Cloud.

Pour mettre à jour une métrique basée sur les journaux, exécutez la commande suivante. Vous pouvez spécifier l'un des indicateurs ou les deux :

gcloud logging metrics update [METRIC_NAME] --description=[DESCRIPTION] --log-filter=[FILTER]

Pour plus de détails, exécutez la commande suivante :

gcloud logging metrics update --help

Supprimer des métriques de distribution

Pour supprimer une métrique basée sur les journaux, procédez comme suit :

Console de journalisation

  1. Accédez à la page Métriques basées sur les journaux :

    Accéder aux métriques basées sur les journaux

  2. Sélectionnez les métriques que vous souhaitez supprimer et cliquez sur Supprimer en haut de la page.

    Vous pouvez également cliquer sur Supprimer la métrique dans le menu situé à droite de la métrique basée sur les journaux que vous souhaitez supprimer.

API Logging

Appelez la méthode projects.metrics.delete dans l'API.

SDK Cloud

Exécutez la commande suivante pour supprimer une métrique basée sur les journaux définie par l'utilisateur dans le projet en cours :

gcloud logging metrics delete [METRIC_NAME]

Pour plus de détails, exécutez la commande suivante :

gcloud logging metrics delete --help

Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Stackdriver Logging
Besoin d'aide ? Consultez notre page d'assistance.