Guide de démarrage rapide: écrire et interroger des entrées de journal à l'aide de la CLI gcloud

Écrire et interroger des entrées de journal avec gcloud CLI

Ce document présente certaines des fonctionnalités de Cloud Logging et vous explique comment effectuer les opérations suivantes:

  • Écrire des entrées de journal à l'aide de la CLI Google Cloud
  • Répertorier les entrées de journal à l'aide de la CLI gcloud
  • répertorier les entrées de journal à l'aide de l'API Logging ;
  • afficher et interroger des entrées de journal à l'aide de l'explorateur de journaux.

Avant de commencer

Pour pouvoir réaliser cet exercice de démarrage rapide, vous devez disposer d'un projet Google Cloud avec la facturation activée. Si vous n'avez pas de projet Cloud ou si la facturation n'est pas activée pour votre projet Cloud, procédez comme suit :
  1. Connectez-vous à votre compte Google Cloud. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.
  2. Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

    Accéder au sélecteur de projet

  3. Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier si la facturation est activée sur un projet.

  4. Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

    Accéder au sélecteur de projet

  5. Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier si la facturation est activée sur un projet.

Premiers pas

La CLI gcloud comporte un groupe de commandes, gcloud logging, qui fournissent une interface de ligne de commande à l'API Cloud Logging.

Vous pouvez utiliser l'environnement Cloud Shell ou une instance de machine virtuelle (VM) Compute Engine pour les commandes de CLI gcloud dans ce guide de démarrage rapide. La CLI gcloud est préinstallée dans l'environnement Cloud Shell.

Cloud Shell

Vérifiez que la CLI gcloud est configurée pour utiliser le bon projet Cloud:

  1. Dans la console, cliquez sur Activer Cloud Shell :

    Capture d'écran du bouton Cloud Shell dans la console.

    Cloud Shell s'ouvre dans une fenêtre et affiche une bannière de bienvenue : Le message de bienvenue reflète l'ID du projet configuré :

    Capture d'écran de Cloud Shell affichant un message de bienvenue.

  2. Si vous souhaitez utiliser un projet Cloud différent de celui répertorié dans le message de bienvenue, exécutez la commande suivante après avoir remplacé PROJECT_ID par votre ID de projet:

       gcloud config set project PROJECT_ID
       

    Pour obtenir l'ID du projet, consultez la section Identifier des projets.

VM instance

Pour créer une instance de VM Compute Engine dans la console, procédez comme suit:

  1. Dans la console, sélectionnez Compute Engine, puis Instances de VM.

  2. Sélectionnez Créer une instance.

  3. Sous Identité et accès à l'API, sous Niveaux d'accès, sélectionnez Définir l'accès pour chaque API.

  4. Faites défiler les listes jusqu'à trouver l'API Stackdriver Logging. Basculez le niveau d'accès sur Complet.

  5. Conservez les valeurs par défaut des autres paramètres, puis cliquez sur Créer. L'instance de votre VM est prête à l'emploi.

  6. Cliquez sur SSH pour vous connecter à l'interface système de votre instance de VM. Après quelques instants, une interface système Debian GNU/Linux s'ouvre dans une fenêtre et affiche un message de bienvenue.

  7. Exécutez la commande suivante pour vérifier que la CLI gcloud est configurée pour votre projet Compute Engine:

    gcloud config list
    
  8. Si vous souhaitez utiliser un autre projet Cloud, exécutez la commande suivante après avoir remplacé PROJECT_ID par l'ID de votre projet:

      gcloud config set project PROJECT_ID
      

    Pour obtenir l'ID du projet, consultez la section Identifier des projets.

Écrire des entrées de journal à l'aide de la CLI gcloud

Logging accepte les entrées de journal avec des données structurées et non structurées. Les données structurées comprennent une structure de données JSON (par exemple, {"weather": "partly cloudy"}). Les données non structurées sont une chaîne de caractères, par exemple "A simple entry". Au cours des étapes suivantes, vous allez utiliser la CLI gcloud pour écrire une entrée de journal avec des données non structurées et une entrée de journal avec des données structurées:

  1. Écrivez une entrée de journal avec des données non structurées dans le journal my-test-log :

    gcloud logging write my-test-log "A simple entry."
    

    Une fois l'exécution de la commande terminée, le message suivant s'affiche : Created log entry.

  2. Écrivez une entrée de journal avec des données non structurées dans le journal my-test-log :

    gcloud logging write --payload-type=json my-test-log '{ "message": "My second entry", "weather": "partly cloudy"}'
    

    Lorsque vous écrivez une entrée de journal avec des données structurées, vous devez inclure --payload-type=json. Si vous omettez ce champ, Logging interprète la charge utile comme des données non structurées.

Si le journal my-test-log n'existe pas, Logging le crée lorsque l'entrée de journal est reçue.

Lister les entrées de journal à l'aide de la CLI gcloud

Vous pouvez récupérer des entrées de journal à partir de Logging et les afficher à l'aide de la CLI gcloud. Par exemple, pour récupérer et afficher les entrées de journal avec un type de ressource global, exécutez la commande suivante:

gcloud logging read "resource.type=global"

La commande renvoie un résultat semblable à celui-ci :

---
insertId: jpj9zjf73t1mn
jsonPayload:
  message: My second entry
  weather: partly cloudy
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:31.114507977Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
timestamp: '2018-11-01T18:39:31.114507977Z'
---
insertId: vd4m1if7h7u1a
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:19.718100792Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
textPayload: A simple entry
timestamp: '2018-11-01T18:39:19.718100792Z'

Répertorier les entrées de journal à l'aide de l'explorateur d'API

Pour exécuter des méthodes d'API Logging sans écrire de code, consultez la page Utiliser APIs Explorer. Pour lire une liste d'entrées de journal à partir de Logging, procédez comme suit:

  1. Consultez la page traitant de la méthode d'API entries.list dans la documentation de référence de l'API :

    Accéder à la page de l'API entry.list

  2. Configurez et exécutez la commande d'API :

    1. Remplacez PROJECT_ID dans le texte suivant:

      "resourceNames": [
      "projects/PROJECT_ID"
      ],
      "filter": "resource.type=global",
      "orderBy": "timestamp desc"
      
    2. Copiez le texte mis à jour à l'étape précédente et collez-le dans le champ Corps de la requête d'Apis Explorer.

    3. Cliquez sur Exécuter.

    La méthode renvoie une réponse semblable à la suivante :

    {
      "entries": [
        {
          "textPayload": "A simple entry",
          "insertId": "vd4m1if7h7u1a",
          "resource": {
            "type": "global",
            "labels": {
              "project_id": "myloggingproject"
            }
          },
          "timestamp": "2018-11-01T18:39:19.718100792Z",
          "logName": "projects/myloggingproject/logs/my-test-log",
          "receiveTimestamp": "2018-11-01T18:39:19.718100792Z"
        },
        {
          "insertId": "jpj9zjf73t1mn",
          "jsonPayload": {
            "message": "My second entry",
            "weather": "partly cloudy"
          },
          "resource": {
            "type": "global",
            "labels": {
              "project_id": "myloggingproject"
            }
          },
          "timestamp": "2018-11-01T18:39:31.114507977Z",
          "logName": "projects/myloggingproject/logs/my-test-log",
          "receiveTimestamp": "2018-11-01T18:39:31.114507977Z"
        }
      ]
    }
    

Afficher les entrées de journal dans l'explorateur de journaux

Pour afficher les entrées de journal dans la console, vous pouvez utiliser l'explorateur de journaux. La plupart des projets Cloud stockent un grand nombre de journaux. Vous pouvez sélectionner certaines entrées de journal en écrivant une requête.

Pour afficher les entrées de journal que vous avez écrites à l'aide de l'explorateur de journaux, procédez comme suit:

  1. Accédez à l'explorateur de journaux dans Google Cloud Console:

    Accéder à l'explorateur de journaux

    Assurez-vous de sélectionner votre projet Cloud dans la barre de navigation Google Cloud. Si nécessaire, sélectionnez votre projet Cloud dans la liste déroulante des projets Cloud.

  2. Dans le menu Ressource, sélectionnez Global.

    Si vous ne voyez pas l'option de menu Global ou si vous ne voyez pas vos entrées de journal, attendez quelques minutes et actualisez la page. Logging peut mettre quelques minutes avant de recevoir des entrées de journal.

  3. Pour afficher les détails d'une entrée de journal, cliquez sur son menu .

    Les données de la première entrée de journal sont stockées dans textPayload. La deuxième entrée de journal contient des données structurées stockées dans jsonPayload. La charge utile structurée contient les clés message et weather.

Pour en savoir plus sur le format de données des entrées de journal, consultez la section Type LogEntry.

Interroger des entrées de journal dans l'explorateur de journaux

Vous pouvez interroger des entrées de journal à l'aide de l'éditeur de requête et, avec des journaux structurés, de la clé et de la valeur. Par exemple, pour afficher toutes les entrées de journal contenant le texte simple, procédez comme suit:

  1. Accédez à l'explorateur de journaux dans Google Cloud Console:

    Accéder à l'explorateur de journaux

  2. Dans le menu Ressource, sélectionnez Global.

  3. Dans l'éditeur de requête, saisissez la chaîne simple entre guillemets. Seule l'entrée de journal A simple entry. apparaît dans l'affichage de journaux.

  4. Après avoir consulté votre journal, supprimez la chaîne de requête que vous avez ajoutée et cliquez sur Run query (Exécuter la requête). Les deux entrées du journal réapparaissent à l'écran.

Pour afficher toutes les entrées de journal avec des données structurées ayant une clé weather où le champ value contient partly, procédez comme suit:

  1. L'éditeur de requête contient la ligne resource.type="global". Saisissez la commande suivante :

    jsonPayload.weather:partly
    
  2. Cliquez sur Exécuter la requête. Le résultat est l'unique entrée de journal My second entry :

L'explorateur de journaux propose également des requêtes enregistrées, suggérées et récentes. Pour en savoir plus sur les requêtes, consultez la page Générer des requêtes dans l'explorateur de journaux.

Pour obtenir des exemples de requêtes, consultez la page Exemples de requêtes avec l'explorateur de journaux.

Dépannage

  • Les erreurs typographiques et les noms de champs inconnus donnent lieu à l'exécution des commandes de CLI gcloud avec des messages d'argument incorrect. Par exemple, si vous oubliez le point dans resource.type, l'erreur est renvoyée:

     ERROR: (gcloud.logging.read) INVALID_ARGUMENT: Field not found: 'resourcetype'.
    
  • Lorsque Cloud Logging n'a pas les autorisations d'accès nécessaires, les commandes de la CLI gcloud sont accompagnées des messages d'autorisation refusée. Par exemple, si une instance de VM Compute Engine est configurée avec les paramètres d'API par défaut, la commande list se termine par une erreur d'autorisation refusée:

     ERROR: (gcloud.logging.read) PERMISSION_DENIED: Request had insufficient authentication scopes.
    

    Pour résoudre ce problème, modifiez les autorisations de l'instance de VM Compute Engine de façon à accorder à Cloud Logging les autorisations de lecture:

    1. Accédez à la page Informations sur l'instance de VM correspondant à votre instance de VM. Cliquez sur Arrêter. Cette action peut prendre une minute ou deux.
    2. Pour modifier la configuration, cliquez sur Modifier.
    3. Recherchez l'en-tête Niveaux d'accès aux API Cloud, puis cliquez sur Détails pour afficher les paramètres de chaque API. Remplacez l'entrée de l'API Cloud Logging par Full. Cliquez sur Enregistrer.
    4. Pour redémarrer votre instance de VM, cliquez sur Démarrer. Après quelques instants, votre VM est prête à être utilisée.
  • Lorsque l'explorateur d'API ne peut pas terminer votre commande ou nécessite une autorisation supplémentaire, il affiche un message ou un code d'erreur :

    • Code de réponse 200 et aucune entrée : si le message nextPageToken s'affiche, cela signifie que l'explorateur d'API n'a pas eu le temps de terminer la recherche. Ajoutez un pageToken à votre requête, définissez la valeur à l'identique de celle indiquée avec la clé nextPageToken, puis réessayez d'exécuter la commande.
    • Code de réponse 400 : la valeur de la requête n'est pas valide. Par exemple, si vous indiquez globalgloobal comme message, Unsupported resource type: gloobal.
    • Code de réponse 404 : l'ID de projet n'est pas valide. Vérifiez l'orthographe de votre identifiant de projet.
    • Vous serez peut-être invité à vous connecter à votre compte Google pour permettre à l'explorateur d'API d'accéder à votre compte.

Effectuer un nettoyage

Pour éviter que les ressources utilisées sur cette page ne soient facturées sur votre compte Google Cloud, procédez comme suit :

  1. (Facultatif) Pour supprimer les entrées de journal que vous avez créées, exécutez la commande gcloud suivante :

    gcloud logging logs delete my-test-log
    

    Si vous ne supprimez pas les entrées de journal, celles-ci expirent et sont supprimées. Pour obtenir des informations sur la conservation des entrées, consultez la page Quotas et limites.

Étapes suivantes