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

Configurer des étiquettes sur les métriques basées sur les journaux

Ce document présente les libellés de métriques basées sur les journaux et explique comment créer et utiliser des libellés sur les métriques basées sur les journaux.

Si vous connaissez bien les libellés, vous pouvez directement passer à la section Créer un libellé de la présente page.

Présentation des étiquettes pour les métriques basées sur les journaux

Les étiquettes permettent aux métriques basées sur les journaux de contenir plusieurs séries temporelles (une pour chaque combinaison de valeurs d'étiquette. Toutes les métriques basées sur les journaux possèdent des libellés par défaut.

Vous pouvez créer des libellés supplémentaires définis par l'utilisateur pour les métriques de compteur et de distribution, en spécifiant des expressions d'extracteur. Une expression d'extracteur indique à Cloud Logging comment extraire la valeur du libellé des entrées de journal. Vous pouvez spécifier la valeur du libellé comme suit :

Contenu entier d'un champ nommé dans l'objet LogEntry.
Partie d'un champ nommé qui correspond à une expression régulière (regexp).

Vous pouvez extraire les libellés des champs intégrés LogEntry, tels que httpRequest.status, ou de l'un des champs de charge utile textPayload, jsonPayload ou protoPayload.

Pour en savoir plus sur les expressions régulières, consultez la section Syntaxe RE2.

N'incluez pas d'informations sensibles dans l'expression de l'extracteur et n'extrayez pas de données sensibles dans des libellés. Celles-ci sont traitées comme des données de service.

Limites des libellés définis par l'utilisateur

Les restrictions suivantes s'appliquent aux libellés définies par l'utilisateur :

Vous pouvez créer jusqu'à 10 libellés définis par l'utilisateur par métrique.
Une fois que vous avez créé un libellé, vous ne pouvez plus le supprimer.
- Vous pouvez modifier l'expression d'extracteur et la description du libellé que vous avez déjà créé.
- Vous ne pouvez pas modifier le nom ou le type de valeur d'un libellé que vous avez déjà créé.
Seuls les 1 024 premiers caractères d'une valeur de libellé sont conservés.
Chaque métrique basée sur les journaux est limitée à environ 30 000 séries temporelles actives. Cette limite dépend du nombre de valeurs possibles pour chaque libellé, y compris pour les libellés par défaut.

Par exemple, si vos entrées de journal proviennent de 100 ressources différentes, telles que des instances de VM, et que vous définissez un libellé avec 20 valeurs possibles, votre métrique peut compter jusqu'à 2 000 séries temporelles.

Un nombre excessif de séries temporelles ou de points de données augmente vos coûts et risque de limiter votre activité. Pour plus d'informations sur le coût des métriques basées sur les journaux, consultez la page Tarifs de Cloud Monitoring : métriques facturables. Pour en savoir plus sur les limites qui s'appliquent aux métriques basées sur les journaux, consultez les pages Quotas et limites : métriques basées sur les journaux et Résoudre les problèmes liés aux métriques basées sur les journaux.

Libellés par défaut

Toutes les métriques basées sur les journaux possèdent des libellés prédéfinis :

Libellés de ressources : toutes les métriques utilisent un objet ressource surveillé pour identifier la source d'où proviennent les données de la série temporelle. Chaque type de ressource inclut un nom de type ainsi qu'un ou plusieurs libellés. Les instances de VM, les bases de données CloudSQL et les équilibreurs de charge constituent des exemples de types de ressources.

La ressource et ses libellés sont répertoriés séparément des autres libellés de métrique dans Cloud Monitoring, mais ils ont le même effet : ils créent des séries temporelles supplémentaires dans la métrique. Pour en savoir plus, consultez la page Métriques, séries temporelles et ressources.
log : ce libellé contient la valeur de la partie LOG_ID du champ logName des entrées de journal.
severity : ce libellé contient la valeur du champ severity des entrées de journal. Le libellé de gravité n'est fourni par défaut que dans les métriques basées sur les journaux système.

Exemple: Utiliser l'Explorateur de métriques

La capture d'écran suivante, tirée de l'explorateur de métriques, montre les libellés présents sur l'une des métriques basées sur les journaux système. Vous pouvez obtenir la liste des libellés en cliquant dans la zone de texte Filter (Filtre) :

Explorateur de métriques

La capture d'écran montre les informations suivantes :

L'explorateur de métrique utilise les séries temporelles issues de la métrique logging/log_entry_count et du type de ressource gce_instance (instances de Compute Engine).

Cette métrique contient également des séries temporelles provenant d'autres types de ressources, mais l'explorateur ne vous permet de consulter qu'un seul type de ressource à la fois.
Le type de ressource gce_instance comporte trois libellés de ressources : project_id, instance_id et zone.
La métrique présente deux libellés de métrique : log et severity. Vos libellés définis par l'utilisateur apparaissent également dans cette section.

Créer un libellé

Vous pouvez créer des libellés définis par l'utilisateur lorsque vous créez la métrique. Les métriques de compteur et de distribution peuvent toutes deux avoir des libellés. Par contre, vous ne pouvez pas ajouter de libellés aux métriques système basées sur les journaux.

Console

Lorsque vous créez une métrique basée sur les journaux, le panneau Créer une métrique de journaux inclut une option permettant d'ajouter des libellés.
Cliquez sur Ajouter une étiquette.

Conseil : Pour afficher les champs et les valeurs d'une entrée de journal, procédez comme suit :
1. Dans la section Sélection des filtres, cliquez sur Prévisualiser les journaux.
2. Dans le volet Afficher les journaux, choisissez une entrée de journal et cliquez sur l'outil de développement situé à côté.
3. Cliquez sur Développer les champs imbriqués.
Définissez les champs suivants dans la section Libellés :
1. Nom du libellé : saisissez un nom pour le libellé. Exemple :ID
  
  Le nom doit respecter les critères suivants :
  - Ne pas dépasser 100 caractères
  - Respecter le format d'expression régulière [a-zA-Z][a-zA-Z0-9_]*
  - Inclure d'autres chaînes en plus de la chaîne "log"
2. Description : décrivez le libellé. Soyez aussi précis que possible sur le format des valeurs de journal attendues. Exemple : Instance number.
3. Type de libellé : choisissez Chaîne, Booléen ou Entier.
4. Field name (Nom du champ) : saisissez le nom du champ d'entrée de journal qui contient la valeur du libellé. Des suggestions sont affichées à mesure que vous saisissez des caractères. Dans cet exemple, le champ est :
```
labels."compute.googleapis.com/resource_id"
```
5. Expression régulière : si la valeur de votre libellé comprend tout le contenu du champ, vous pouvez laisser ce champ vide. Sinon, spécifiez un groupe de capture regexp qui extrait la valeur de libellé à partir de la valeur de champ.
  
  Supposons par exemple que le champ contienne généralement un texte semblable à celui-ci :
```
The instance number is 0123456789; the ID is my-test-instance22
```
  Si vous souhaitez que la valeur du libellé soit le numéro de l'instance, il existe de nombreuses expressions régulières qui pourront extraire le nombre correct. Par exemple, dans l'expression suivante, les parenthèses constituent un groupe de capture qui identifie la partie du texte à extraire :
```
The instance number is ([0-9]+); .*
```
  Pour en savoir plus sur les expressions régulières, consultez la section Syntaxe RE2.
Cliquez sur Done (OK) pour créer le libellé. Vous pouvez ajouter d'autres libellés en répétant ces étapes.
Pour terminer la création de la métrique, cliquez sur Créer la métrique.

gcloud

Pour créer une métrique basée sur les journaux avec des libellés personnalisés, vous devez créer un fichier contenant une représentation de votre définition LogMetric au format JSON ou YAML, y compris les libellés personnalisés. Créez ensuite la métrique en appelant la commande create avec l'indicateur --config-from-file, en remplaçant FILENAME par le nom de votre fichier JSON ou YAML :

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

Pour en savoir plus, consultez les sections sur gcloud logging metrics create

API

Les libellés sont spécifiés comme faisant partie de l'objet LogMetric dans le corps de requête des appels à la méthode projects.metrics.create de l'API Logging. Pour plus d'informations sur les appels de méthode complets, consultez la page Créer des métriques de compteur ou Créer des métriques de distribution.

Pour chaque libellé, vous devez ajouter un segment aux champs metricDescriptor et labelExtractors dans l'objet LogMetric.

La syntaxe est la suivante :

{
  ...
  metricDescriptor: {
      labels: [
        { key: LABEL_NAME, valueType: LABEL_TYPE,
          description: LABEL_DESCRIPTION },
        ...
      ]
  },
  labelExtractors: {
    LABEL_NAME: EXTRACTOR_EXPRESSION,
    ...
  },
}

Les éléments de syntaxe ont la signification suivante :

LABEL_NAME : nom du libellé en tant que chaîne.
VALUE_TYPE : type du libellé : STRING, BOOL ou INT64.
LABEL_DESCRIPTION : description du libellé.
EXTRACTOR_EXPRESSION : chaîne qui combine le nom du champ de l'entrée de journal et une expression régulière facultative. L'expression d'extracteur peut être l'une des suivantes :
```
EXTRACT(FIELD)
```
```
REGEXP_EXTRACT(FIELD, REGEXP)
```

Pour en savoir plus sur les expressions régulières, consultez la section Syntaxe RE2.

Voici un exemple avec deux libellés :

{
  ...
  metricDescriptor: {
      labels: [
        { key: "label_name_a", valueType: STRING },
        { key: "label_name_b", valueType: INT64 },
      ]
  },
  labelExtractors: {
    "label_name_a":
      "REGEXP_EXTRACT(jsonPayload.field_a, \"before ([a-zA-Z ]+) after\")",
    "label_name_b": "EXTRACT(jsonPayload.field_b)",
  },
}

Pour plus de détails, reportez-vous au type LogMetric.