Cette page a été traduite par l'API Cloud Translation.

Configurer des métriques de distribution

Cette page explique comment créer des métriques basées sur les journaux de type distribution à l'aide de la classe la console Google Cloud, l'API Logging et la Google Cloud CLI. Pour obtenir une vue d'ensemble des métriques basées sur les journaux, consultez Présentation des métriques basées sur les journaux

Présentation

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.

Pour en savoir plus sur l'affichage et l'interprétation des métriques de distribution, consultez Métriques de distribution.

Avant de commencer

Pour utiliser les métriques basées sur les journaux, vous devez disposer d'un projet Google Cloud avec facturation activée:
Assurez-vous que votre rôle Identity and Access Management inclut les autorisations requises pour créer et afficher des métriques basées sur les journaux, et créer des règles d'alerte. Pour en savoir plus, consultez Autorisations pour les métriques basées sur les journaux.

Créer une métrique de distribution

La métrique comptabilise les entrées de journal identifiées par un filtre que vous fournissez. Vous pouvez utiliser des expressions régulières ; dans votre filtre. Nous vous recommandons d'inclure un type de ressource. La la longueur d'un filtre ne peut pas dépasser 20 000 caractères.

N'incluez pas d'informations sensibles dans le filtre. Les filtres sont traités comme des données de service.

Console

Procédez comme suit pour créer une métrique de compteur basée sur les journaux dans le Console Google Cloud dans votre projet Google Cloud:

Dans la console Google Cloud, accédez à la page Métriques basées sur les journaux.
Accéder à la page Métriques basées sur les journaux

Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Logging.
Cliquez sur Créer une métrique. Le panneau Créer une métrique de journaux s'affiche.
Définissez le Type de métrique: sélectionnez Distribution.
Définissez les champs suivants dans la section Détails :
- Nom de la métrique de journal: choisissez un nom unique parmi les basées sur les journaux dans votre projet Google Cloud. Certaines restrictions en termes de dénomination s'appliquent, consultez la section Dépannage pour plus de détails.
- Description : saisissez une description de la métrique.
- Units (Unités) : (facultatif) pour les métriques de distribution, vous avez la possibilité saisissez des unités, par exemple s et ms. Pour en savoir plus, consultez le champ unit de MetricDescriptor.
Définissez le filtre de votre métrique dans la section Sélection du filtre.
1. Utilisez le menu Sélectionner un projet ou un bucket de journaux pour indiquer si le métrique compte les entrées de journal de votre projet Google Cloud dans un bucket de journaux spécifique.
2. Créez un filtre qui ne collecte que les entrées de journal que vous souhaitez comptabiliser dans votre métrique à l'aide du langage de requête de journalisation. Vous pouvez également utiliser des expressions régulières pour créer les filtres de votre métrique.
3. 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 :
```
protoPayload.latency
```
4. Expression régulière: (facultatif) si Nom du champ est toujours contient une valeur numérique convertible en type double, vous pouvez laissez ce champ vide. Sinon, spécifiez une expression régulière qui extrait la valeur de distribution numérique de la valeur du champ.
  
  Exemple : Supposons que votre champ d'entrée de journal latency contienne un nombre suivi de ms, pour "millisecondes". L'expression régulière suivante permet d'extraire le chiffre sans le suffixe d'unité :
```
([0-9.]+)
```
  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 plus de détails, consultez la section Utiliser des expressions régulières.
- Advanced (Histogram buckets) (Avancé (buckets d'histogramme)) : (facultatif) cliquez sur Advanced (Avancé) pour ouvrir une section du formulaire dans laquelle vous pouvez spécifier des dispositions de buckets personnalisées. Si vous 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.
1. Pour voir les entrées de journal qui correspondent à votre filtre, cliquez sur Prévisualiser les journaux.
(Facultatif) Ajoutez un libellé dans la section Libellés. Pour obtenir des instructions sur la création de libellés, consultez la page Créer un libellé.
Cliquez sur Créer une métrique pour créer la métrique.

gcloud

Pour créer une métrique basée sur les journaux de type distribution, créer un fichier contenant une représentation de votre LogMetric définition dans JSON ou YAML. Utilisez ensuite la commande suivante pour lire les depuis votre fichier:

gcloud logging metrics create METRIC_NAME --config-from-file FILENAME

Pour en savoir plus sur la description des buckets d'histogramme d'une distribution, consultez la section Buckets d'histogrammes.

API

Pour créer une métrique de distribution, utilisez la méthode projects.metrics.create de l'API Logging. Vous pouvez tester la méthode dans l'explorateur d'API. Préparez les arguments de la méthode comme suit :

Définissez le champ parent sur le projet ou le bucket dans lequel la métrique est à créer:
- Pour une métrique basée sur les journaux à l'échelle du projet, spécifiez le projet:
```
projects/PROJECT_ID
```
- Pour une métrique basée sur les journaux à l'échelle du bucket, spécifiez le bucket:
```
projects/PROJECT_ID/locations/LOCATION/bucket/BUCKET_ID
```

Définissez le corps de la requête sur un objet LogMetric. Le suivi est un échantillon pour une métrique de distribution.

{
  name:        "my-metric"
  description: "Description of my-metric."
  filter:      "resource.type=gce_instance AND log_id(\"syslog\")",
  valueExtractor: "REGEXP_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 :

Certaines restrictions en termes de dénomination s'appliquent, consultez la section Dépannage pour plus de détails.
metricDescriptor : un 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) : tous les buckets ont la même largeur. Les limites sont offset + width * i, pour i=0,1,2,...,N. Pour en savoir plus sur les buckets linéaires, consultez la documentation de référence de l'API.
Exponential (Exponentielle) (scale, growth_factor, i) : la largeur des buckets augmente pour les valeurs plus élevées. Les limites sont scale * growth_factorⁱ, pour i=0,1,2,...,N. Pour en savoir plus sur les buckets exponentiels, consultez la documentation de référence de l'API.
explicite, vous listez toutes les limites des buckets dans le bounds. Le bucket i comporte les limites suivantes :
```
Upper bound: bounds[*i*] for (0 <= *i* < *N*-1)
Lower bound: bounds[*i* - 1] for (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

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 suivant concerne la disposition du bucket linéaire:

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érieur ou égal à 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 exponentiel) : 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 de bucket sont les suivantes :

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

Pour plus d'informations sur les buckets, consultez BucketOptions dans l'API Cloud Monitoring.

API

La disposition facultative du bucket est spécifiée par le champ bucketOptions dans L'objet LogMetric fourni à projects.metrics.create Pour le l'objet LogMetric complet, 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 ^ i où i=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

Votre nouvelle métrique apparaît immédiatement dans la liste des métriques et dans les menus 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 définies par l'utilisateur dans votre projet Google Cloud ou pour inspecter une métrique particulière dans votre projet Google Cloud, procédez comme suit :

Console

Dans la console Google Cloud, accédez à la page Métriques basées sur les journaux.
Accéder à la page Métriques basées sur les journaux

Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Logging.
Le volet Métriques définies par l'utilisateur contient les métriques basées sur les journaux dans le projet Google Cloud actuel:
Pour afficher les données d'une métrique basée sur les journaux, cliquez sur l'icône Menu dans ligne de la métrique, puis sélectionnez Afficher dans l'explorateur de métriques.

gcloud

Pour répertorier les métriques basées sur les journaux définies par l'utilisateur dans votre projet Google Cloud, procédez comme suit : exécutez 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 Google Cloud, exécutez la commande suivante:

gcloud logging metrics describe METRIC_NAME

Pour obtenir de l'aide, utilisez la commande suivante:

gcloud logging metrics --help

Vous ne pouvez pas lire les données de séries temporelles d'une métrique à partir de la Google Cloud CLI.

API

Répertorier les statistiques

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

parent : nom de la ressource du projet Google Cloud : projects/PROJECT_ID.
pageSize : nombre maximal de résultats.
pageToken : obtient la page suivante des résultats. Pour en savoir plus sur l'utilisation des jetons de page, consultez la page projects.metrics.list.

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

Pour récupérer une seule métrique basée sur les journaux définie par l'utilisateur, utilisez le 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 de séries temporelles d'une métrique basée sur les journaux, utilisez la méthode projects.timeseries.list API Cloud Monitoring. Pour plus d'informations sur les données de séries temporelles, consultez la page Lire les séries temporelles.

Pour lire une seule métrique basée sur les journaux définie par l'utilisateur, renseignez les paramètres de la méthode avec ce type de métrique et cet identifiant :

logging.googleapis.com/user/METRIC_ID

Mettre à jour les métriques de distribution

Vous pouvez modifier une métrique basée sur les journaux définie par l'utilisateur pour changer sa description, son filtre 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. Si vous utilisez une métrique à l'échelle du bucket, vous pouvez aussi mettre à jour le bucket de la métrique.

Vous ne pouvez pas modifier le nom ni le type des métriques basées sur les journaux définies par l'utilisateur. et vous ne pouvez pas supprimer de libellés existants dans une métrique basée sur les journaux.

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

Console

Dans la console Google Cloud, accédez à la page Métriques basées sur les journaux.
Accéder à la page Métriques basées sur les journaux

Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Logging.
Cliquez sur Modifier la métrique dans la Menu correspondant à la métrique basée sur les journaux que vous voulez modifier.
Ne modifiez que les éléments autorisés dans la métrique.
Cliquez sur Mettre à jour la métrique.

gcloud

Utiliser la Google Cloud CLI pour modifier la description, le filtre d'une métrique de compteur une requête et un bucket. Vous pouvez mettre à jour tout ou partie des champs à la fois.

gcloud logging update METRIC_NAME \
  --description="METRIC_DESCRIPTION" \
  --log-filter="FILTER" \
  --bucket-name=BUCKET_NAME

Si vous modifiez le bucket associé à une métrique de portée bucket, toutes les données de métrique collectées avant la modification ne reflètent plus la configuration actuelle. Les données de métriques collectées pour le bucket précédent n'est pas supprimée.

Pour mettre à jour les métriques de distribution ou d'autres champs de métriques de compteur, à l'exception du METRIC_NAME, créez un fichier contenant la spécification révisée de votre LogMetric au format JSON ou YAML. Ensuite, mettez à jour en appelant la commande update avec le champ "--config-from-file" en remplaçant FILENAME par le nom de votre fichier JSON ou YAML:

gcloud logging update METRIC_NAME --config-from-file FILENAME

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

gcloud logging metrics update --help

API

Pour modifier une métrique basée sur les journaux, utilisez 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.

Supprimer des métriques de distribution

Pour supprimer une métrique basée sur les journaux définie par l'utilisateur, procédez comme suit:

Console

Dans la console Google Cloud, accédez à la page Métriques basées sur les journaux.
Accéder à la page Métriques basées sur les journaux

Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Logging.
Sélectionnez la métrique que vous souhaitez supprimer et cliquez sur Supprimer.

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

gcloud

Utilisez la commande suivante pour supprimer une métrique basée sur les journaux définie par l'utilisateur dans le projet Google Cloud actuel:

gcloud logging metrics delete METRIC_NAME

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

gcloud logging metrics delete --help

API

Pour supprimer une métrique basée sur les journaux définie par l'utilisateur, utilisez la méthode projects.metrics.delete dans l'API.

De plus, sur la page Métrique basée sur les journaux de la console Google Cloud, Le volet Métriques définies par l'utilisateur de l'interface des métriques basées sur les journaux fournit plus de fonctionnalités pour vous aider à gérer les métriques définies par l'utilisateur projet Google Cloud. Pour en savoir plus, consultez le volet de métriques définies par l'utilisateur.