Configurer des métriques de distribution

Console

Pour créer une métrique de compteur basée sur les journaux dans la console Google Cloud de votre projet Google Cloud, procédez comme suit:

1. 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.

2. Cliquez sur Créer une métrique. Le panneau Créer une métrique de journaux s'affiche.

3. Définissez le Type de métrique: sélectionnez Distribution.

4. Définissez les champs suivants dans la section Détails :

   • Nom de la métrique de journaux: choisissez un nom unique parmi les métriques basées sur les journaux de 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é de saisir des unités, telles que s et ms. Pour en savoir plus, consultez le champ unit de MetricDescriptor.

5. 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 la métrique compte les entrées de journal de votre projet Google Cloud ou uniquement celles d'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 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.

      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.

6. (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é.

7. 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éez un fichier contenant une représentation de votre définition LogMetric au format JSON ou YAML. Utilisez ensuite la commande suivante pour lire la configuration à partir de 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. Si vous utilisez le volet APIs Explorer sur la page de référence, préparez les arguments comme suit:

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

   • Pour une métrique basée sur les journaux de portée 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
   

2. Définissez le corps de la requête sur un objet LogMetric. Voici un exemple d'objet 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: objet MetricDescriptor. metricKind doit être DELTA. valueType doit être DISTRIBUTION.

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 est destiné à la disposition des buckets linéaire:

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 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 en savoir plus sur les buckets, consultez BucketOptions dans l'API Cloud Monitoring.

API

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 ^ 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)

Console

1. 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.

2. Dans le volet Métriques définies par l'utilisateur, les métriques basées sur les journaux définies par l'utilisateur s'affichent dans le projet Google Cloud en cours:

3. Pour afficher les données d'une métrique basée sur les journaux, cliquez sur le menu more_vert sur la 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, 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 Google Cloud, utilisez 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 des 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 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 de séries temporelles d'une métrique basée sur les journaux, utilisez projects.timeseries.list dans l'API Cloud Monitoring. Pour en savoir plus sur les données de séries temporelles, consultez la section 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

Console

1. 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.

2. Cliquez sur Modifier la métrique dans le menu more_vert pour 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 Mettre à jour la métrique.

gcloud

Utilisez la Google Cloud CLI pour modifier la description, la requête de filtrage et le bucket d'une métrique de compteur. Vous pouvez mettre à jour un ou tous les champs en même temps.

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étrique collectées pour le bucket précédent ne sont pas supprimées.

Pour mettre à jour les métriques de distribution ou d'autres champs de métrique de compteur, à l'exception de METRIC_NAME, créez un fichier contenant la spécification révisée de votre LogMetric au format JSON ou YAML. Mettez ensuite à jour la métrique 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.

Console

1. 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.

2. 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 more_vert de la métrique basée sur les journaux que vous souhaitez supprimer.

gcloud

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

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 de l'API.