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

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

  • Écrivez des entrées de journal à l'aide de la Google Cloud CLI.
  • Répertoriez les entrées de journal à l'aide de la gcloud CLI.
  • 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 suivre ce guide de démarrage rapide, vous devez disposer d'un projet Google Cloud pour lequel la facturation est activée. Si vous n'avez pas de projet Google Cloud ou si la facturation n'est pas activée pour votre projet Google 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 sans frais pour exécuter, tester et déployer des charges de travail.

  2. Installez la Google Cloud CLI.

  3. Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  4. Pour initialiser la gcloud CLI, exécutez la commande suivante : 

    gcloud init

  5. Créez ou sélectionnez un projet Google Cloud .

    Rôles requis pour sélectionner ou créer un projet

    • Sélectionnez un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique. Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
    • Créer un projet : pour créer un projet, vous devez disposer du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

    • Créez un projet Google Cloud  :

      gcloud projects create PROJECT_ID

      Remplacez PROJECT_ID par le nom du projet Google Cloud que vous créez.

    • Sélectionnez le projet Google Cloud que vous avez créé :

      gcloud config set project PROJECT_ID

      Remplacez PROJECT_ID par le nom de votre projet Google Cloud .

  6. Si vous utilisez un projet existant pour ce guide, vérifiez que vous disposez des autorisations nécessaires pour suivre les instructions. Si vous avez créé un projet, vous disposez déjà des autorisations requises.

  7. Vérifiez que la facturation est activée pour votre projet Google Cloud .

  8. Installez la Google Cloud CLI.

  9. Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  10. Pour initialiser la gcloud CLI, exécutez la commande suivante : 

    gcloud init

  11. Créez ou sélectionnez un projet Google Cloud .

    Rôles requis pour sélectionner ou créer un projet

    • Sélectionnez un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique. Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
    • Créer un projet : pour créer un projet, vous devez disposer du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

    • Créez un projet Google Cloud  :

      gcloud projects create PROJECT_ID

      Remplacez PROJECT_ID par le nom du projet Google Cloud que vous créez.

    • Sélectionnez le projet Google Cloud que vous avez créé :

      gcloud config set project PROJECT_ID

      Remplacez PROJECT_ID par le nom de votre projet Google Cloud .

  12. Si vous utilisez un projet existant pour ce guide, vérifiez que vous disposez des autorisations nécessaires pour suivre les instructions. Si vous avez créé un projet, vous disposez déjà des autorisations requises.

  13. Vérifiez que la facturation est activée pour votre projet Google Cloud .

Rôles requis

Pour obtenir les autorisations nécessaires pour créer, lister et supprimer des entrées de journal, demandez à votre administrateur de vous accorder le rôle IAM Administrateur Logging (roles/logging.admin) sur votre projet. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Les rôles Rédacteur de journaux (roles/logging.logWriter) et Visionneuse de journaux (roles/logging.viewer) contiennent les autorisations permettant de créer et de lister les entrées de journaux. Pour supprimer des entrées de journaux, accordez le rôle Administrateur de journaux (roles/logging.admin), qui contient les autorisations permettant de créer, lister et supprimer des entrées de journaux. Notez que le rôle Administrateur Logging (roles/logging.admin) accorde également les autorisations nécessaires pour effectuer toutes les actions dans Logging.

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

Logging accepte les entrées de journal avec des données structurées et non structurées. Les données structurées se composent d'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".

Dans les étapes suivantes, vous utiliserez la gcloud CLI 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. La gcloud CLI fournit une interface de ligne de commande à l'API Cloud Logging.

  1. Pour écrire une entrée de journal avec des données non structurées dans le journal my-test-log, exécutez la commande gcloud logging write :

    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, la journalisation 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 gcloud CLI

Vous pouvez récupérer les entrées de journal de Logging et les afficher à l'aide de la gcloud CLI. 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'

Pour en savoir plus sur la lecture des journaux, consultez la documentation de référence sur gcloud logging read.

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

Pour exécuter des méthodes de l'API Logging sans écrire de code, consultez 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 entries.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 Google Cloud , vous pouvez utiliser l'explorateur de journaux. La plupart des projets Google 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. Dans la console Google Cloud , accédez à la pageExplorateur de journaux :

    Accéder à l'explorateur de journaux

    Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Logging.

    Assurez-vous que votre projet Google Cloud est sélectionné dans la barre de navigation Google Cloud. Si nécessaire, utilisez la liste déroulante des projets Google Cloud pour sélectionner votre projet Google 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 des données des entrées de journal, consultez le type LogEntry.

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

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

  1. Dans la console Google Cloud , accédez à la pageExplorateur de journaux :

    Accéder à l'explorateur de 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 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, puis cliquez sur Exécuter la requête. Les deux entrées de journal réapparaissent à l'écran.

Pour afficher toutes les entrées de journal avec des données structurées dont la clé est weather et dont 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 entraînent l'exécution des commandes gcloud CLI avec des messages invalid argument (argument non valide). Par exemple, si vous oubliez le point dans resource.type, l'erreur suivante s'affiche :

     ERROR: (gcloud.logging.read) INVALID_ARGUMENT: Field not found: 'resourcetype'.

  • Lorsque Cloud Logging ne dispose pas des autorisations d'accès nécessaires, les commandes gcloud CLI se terminent par des messages 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 votre instance de VM Compute Engine afin d'accorder l'autorisation de lecture à Cloud Logging en procédant comme suit :

    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. Passez l'entrée de l'API Cloud Logging sur Complet. 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 qu'APIs Explorer 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 écrivez gloobal au lieu de global, le message Unsupported resource type: gloobal s'affiche.
    • Code de réponse 404 : l'ID du projet n'est pas valide. Vérifiez l'orthographe de votre identifiant de projet.
    • Vous serez peut-être invité à vous connecter à votre projetGoogle Cloud et à autoriser APIs Explorer à accéder à votre compte.

Effectuer un nettoyage

Pour éviter que les ressources utilisées dans cette démonstration soient facturées sur votre compte Google Cloud , supprimez le projet Google Cloud qui les contient.

  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 vos entrées de journal, elles expirent et sont supprimées. Pour obtenir des informations sur la conservation des entrées, consultez la page Quotas et limites.

Étape suivante